/*
 * Copyright (c) 2025 Huawei Device Co., Ltd.
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

/**
 * @addtogroup GameController
 * @{
 *
 * @brief Provides APIs for game controller capability.
 *
 * @since 21
 */

/**
 * @file game_device.h
 * @brief Defines APIs for game devices.
 *
 * @kit GameControllerKit
 * @library libohgame_controller.z.so
 * @syscap SystemCapability.Game.GameController
 * @since 21
 */

#ifndef GAME_DEVICE_H
#define GAME_DEVICE_H

#include <stdint.h>
#include "game_device_event.h"

#ifdef __cplusplus
extern "C" {
#endif

/**
 * @brief Defines the result returned by {@link OH_GameDevice_GetAllDeviceInfos}.
 *
 * @since 21
 * @see {@link OH_GameDevice_AllDeviceInfos_GetCount} obtains the number of devices.
 * @see {@link OH_GameDevice_AllDeviceInfos_GetDeviceInfo} obtains the device information at the specified index.
 */
typedef struct GameDevice_AllDeviceInfos GameDevice_AllDeviceInfos;

/**
 * @brief Obtains information about all online devices.
 *
 * @param allDeviceInfos Output parameter. Double pointer to the {@link GameDevice_AllDeviceInfos} instance. The
 *     pointer cannot be null.
 * @return <ul><li>If the operation is successful, {@link GAME_CONTROLLER_SUCCESS} is returned.</li>     <li>If the **
 *     allDeviceInfos** parameter is null, {@link GAME_CONTROLLER_PARAM_ERROR} is returned.</li>     <li>If querying
 *     all device information in multimodal input fails, {@link GAME_CONTROLLER_MULTIMODAL_INPUT_ERROR} is returned.
 *     </li></ul>
 * @since 21
 * @see {@link OH_GameDevice_DestroyAllDeviceInfos} destroys all device information instances.
 */
GameController_ErrorCode OH_GameDevice_GetAllDeviceInfos(GameDevice_AllDeviceInfos** allDeviceInfos);

/**
 * @brief Registers a callback for device status change events.
 *
 * @param deviceMonitorCallback Callback function {@link GameDevice_DeviceMonitorCallback}, which cannot be null.
 * @return <ul><li>If the operation is successful, {@link GAME_CONTROLLER_SUCCESS} is returned.</li>     <li>If the **
 *     deviceMonitorCallback** parameter is null, {@link GAME_CONTROLLER_PARAM_ERROR} is returned.</li></ul>
 * @since 21
 * @see {@link OH_GameDevice_UnregisterDeviceMonitor} unregisters the callback for device status change events.
 */
GameController_ErrorCode OH_GameDevice_RegisterDeviceMonitor(
    GameDevice_DeviceMonitorCallback deviceMonitorCallback);

/**
 * @brief Unregisters the callback for device status change events.
 *
 * @return If the operation is successful, {@link GAME_CONTROLLER_SUCCESS} is returned.
 * @since 21
 */
GameController_ErrorCode OH_GameDevice_UnregisterDeviceMonitor(void);

/**
 * @brief Destroys all device information instances.
 *
 * @param allDeviceInfos Double pointer to the {@link GameDevice_AllDeviceInfos} instance. The pointer cannot be null.
 * @return <ul><li>If the operation is successful, {@link GAME_CONTROLLER_SUCCESS} is returned.</li>     <li>If the **
 *     allDeviceInfos** parameter is null, {@link GAME_CONTROLLER_PARAM_ERROR} is returned.</li></ul>
 * @since 21
 */
GameController_ErrorCode OH_GameDevice_DestroyAllDeviceInfos(GameDevice_AllDeviceInfos** allDeviceInfos);

/**
 * @brief Obtains the number of devices.
 *
 * @param allDeviceInfos Pointer to the {@link GameDevice_AllDeviceInfos} instance. The pointer cannot be null.
 * @param count Output parameter. Number of devices.
 * @return <ul><li>If the operation is successful, {@link GAME_CONTROLLER_SUCCESS} is returned.</li>     <li>If the **
 *     allDeviceInfos** parameter is null, {@link GAME_CONTROLLER_PARAM_ERROR} is returned.</li></ul>
 * @since 21
 */
GameController_ErrorCode OH_GameDevice_AllDeviceInfos_GetCount(
    const struct GameDevice_AllDeviceInfos* allDeviceInfos,
    int32_t* count);

/**
 * @brief Obtains the device information at the specified index.
 *
 * @param allDeviceInfos Pointer to the {@link GameDevice_AllDeviceInfos} instance. The pointer cannot be null.
 * @param index Index of the device.
 * @param deviceInfo Output parameter. Double pointer to the device information.
 * @return <ul><li>If the operation is successful, {@link GAME_CONTROLLER_SUCCESS} is returned.</li>     <li>If **
 *     allDeviceInfos** is null, or **index** is less than 0 or greater than or equal to the total number of devices,
 *     {@link GAME_CONTROLLER_PARAM_ERROR} is returned.</li></ul>
 * @since 21
 */
GameController_ErrorCode OH_GameDevice_AllDeviceInfos_GetDeviceInfo(
    const struct GameDevice_AllDeviceInfos* allDeviceInfos,
    const int32_t index,
    GameDevice_DeviceInfo** deviceInfo);

#ifdef __cplusplus
}
#endif

#endif //GAME_DEVICE_H
/** @} */