interface_sdk_c/GameControllerKit/game_pad_event.h

/*
 * 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_pad_event.h
 * @brief Defines APIs for gamepad events.
 *
 * @kit GameControllerKit
 * @library libohgame_controller.z.so
 * @syscap SystemCapability.Game.GameController
 * @since 21
 */

#ifndef GAME_PAD_EVENT_H
#define GAME_PAD_EVENT_H

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

#ifdef __cplusplus
extern "C" {
#endif

/**
 * @brief Defines source types of gamepad axis events.
 *
 * @since 21
 */
typedef enum GamePad_AxisSourceType {
    /**
     * The axis event comes from the directional pad (D-pad).
     * @since 21
     */
    DPAD = 0,

    /**
     * The axis event comes from the left thumbstick.
     * @since 21
     */
    LEFT_THUMBSTICK = 1,

    /**
     * The axis event comes from the right thumbstick.
     * @since 21
     */
    RIGHT_THUMBSTICK = 2,

    /**
     * The axis event comes from the left trigger.
     * @since 21
     */
    LEFT_TRIGGER = 3,

    /**
     * The axis event comes from the right trigger.
     * @since 21
     */
    RIGHT_TRIGGER = 4,
} GamePad_AxisSourceType;

/**
 * @brief Defines action types of gamepad button events.
 *
 * @since 21
 */
typedef enum GamePad_Button_ActionType {
    /**
     * The button is pressed.
	 * @since 21
     */
    DOWN = 0,

    /**
     * The button is released.
	 * @since 21
     */
    UP = 1,
} GamePad_Button_ActionType;

/**
 * @brief Defines gamepad button events.
 *
 * @since 21
 * @see {@link OH_GamePad_ButtonEvent_GetDeviceId} obtains the device ID from a button event.
 * @see {@link OH_GamePad_ButtonEvent_GetButtonAction} obtains the button action type from a button event.
 * @see {@link OH_GamePad_ButtonEvent_GetButtonCode} obtains the button code from a button event.
 * @see {@link OH_GamePad_ButtonEvent_GetButtonCodeName} obtains the button name from a button event.
 * @see {@link OH_GamePad_ButtonEvent_GetActionTime} obtains the action time from a button event.
 * @see {@link OH_GamePad_PressedButtons_GetCount} obtains the number of pressed buttons from a button event.
 * @see {@link OH_GamePad_PressedButtons_GetButtonInfo} obtains the button information at a specified index from
 *     a button event.
 */
typedef struct GamePad_ButtonEvent GamePad_ButtonEvent;

/**
 * @brief Defines gamepad axis events.
 *
 * @since 21
 * @see {@link OH_GamePad_AxisEvent_GetDeviceId} obtains the device ID from an axis event.
 * @see {@link OH_GamePad_AxisEvent_GetAxisSourceType} obtains the source type of an axis event.
 * @see {@link OH_GamePad_AxisEvent_GetXAxisValue} obtains the X-axis value from an axis event.
 * @see {@link OH_GamePad_AxisEvent_GetYAxisValue} obtains the Y-axis value from an axis event.
 * @see {@link OH_GamePad_AxisEvent_GetZAxisValue} obtains the Z-axis value from an axis event.
 * @see {@link OH_GamePad_AxisEvent_GetRZAxisValue} obtains the RZ-axis value from an axis event.
 * @see {@link OH_GamePad_AxisEvent_GetHatXAxisValue} obtains the HatX-axis value from an axis event.
 * @see {@link OH_GamePad_AxisEvent_GetHatYAxisValue} obtains the HatY-axis value from an axis event.
 * @see {@link OH_GamePad_AxisEvent_GetBrakeAxisValue} obtains the Brake-axis value from an axis event.
 * @see {@link OH_GamePad_AxisEvent_GetGasAxisValue} obtains the Gas-axis value from an axis event.
 * @see {@link OH_GamePad_AxisEvent_GetActionTime} obtains the action time from an axis event.
 */
typedef struct GamePad_AxisEvent GamePad_AxisEvent;

/**
 * @brief Defines pressed buttons.
 *
 * @since 21
 * @see {@link OH_GamePad_PressedButton_GetButtonCode} obtains the button code from a pressed button.
 * @see {@link OH_GamePad_PressedButton_GetButtonCodeName} obtains the button name from a pressed button.
 */
typedef struct GamePad_PressedButton GamePad_PressedButton;

/**
 * @brief Defines the callback function used by the button event listener registration API. The callback is triggered
 * when a player presses a button.
 *
 * @param buttonEvent Output parameter. Gamepad button event {@link GamePad_ButtonEvent}.
 * @since 21
 */
typedef void(* GamePad_ButtonInputMonitorCallback)(const struct GamePad_ButtonEvent* buttonEvent);

/**
 * @brief Defines the callback function used by the axis event listener registration API. The callback is triggered
 * when a player operates a joystick.
 *
 * @param axisEvent Output parameter. Gamepad axis event {@link GamePad_AxisEvent}.
 * @since 21
 */
typedef void(* GamePad_AxisInputMonitorCallback)(const struct GamePad_AxisEvent* axisEvent);

/**
 * @brief Obtains the device ID from a button event.
 *
 * @param buttonEvent Pointer to the {@link GamePad_ButtonEvent} instance. The pointer cannot be null.
 * @param deviceId Output parameter. Double pointer to the device ID.
 * @return <ul><li>If the operation is successful, {@link GAME_CONTROLLER_SUCCESS} is returned.</li>     <li>If **
 *     buttonEvent** or **deviceId** is null, {@link GAME_CONTROLLER_PARAM_ERROR} is returned.</li>     <li>If the
 *     device has insufficient memory, {@link GAME_CONTROLLER_NO_MEMORY} is returned.</li></ul>
 * @since 21
 */
GameController_ErrorCode OH_GamePad_ButtonEvent_GetDeviceId(const struct GamePad_ButtonEvent* buttonEvent,
                                                            char** deviceId);

/**
 * @brief Obtains the button action type from a button event.
 *
 * @param buttonEvent Pointer to the {@link GamePad_ButtonEvent} instance. The pointer cannot be null.
 * @param actionType Output parameter. Button action type.
 * @return <ul><li>If the operation is successful, {@link GAME_CONTROLLER_SUCCESS} is returned.</li>     <li>If **
 *     buttonEvent** is null, {@link GAME_CONTROLLER_PARAM_ERROR} is returned.</li></ul>
 * @since 21
 */
GameController_ErrorCode OH_GamePad_ButtonEvent_GetButtonAction(const struct GamePad_ButtonEvent* buttonEvent,
                                                                GamePad_Button_ActionType* actionType);

/**
 * @brief Obtains the button code from a button event.
 *
 * @param buttonEvent Pointer to the {@link GamePad_ButtonEvent} instance. The pointer cannot be null.
 * @param code Output parameter. Button code.
 * @return <ul><li>If the operation is successful, {@link GAME_CONTROLLER_SUCCESS} is returned.</li>     <li>If **
 *     buttonEvent** is null, {@link GAME_CONTROLLER_PARAM_ERROR} is returned.</li></ul>
 * @since 21
 */
GameController_ErrorCode OH_GamePad_ButtonEvent_GetButtonCode(const struct GamePad_ButtonEvent* buttonEvent,
                                                              int32_t* code);

/**
 * @brief Obtains the button name from a button event.
 *
 * @param buttonEvent Pointer to the {@link GamePad_ButtonEvent} instance. The pointer cannot be null.
 * @param codeName Output parameter. Double pointer to the button name.
 * @return <ul><li>If the operation is successful, {@link GAME_CONTROLLER_SUCCESS} is returned.</li>     <li>If **
 *     buttonEvent** or **codeName** is null. {@link GAME_CONTROLLER_PARAM_ERROR} is returned.</li>     <li>If the
 *     device has insufficient memory, {@link GAME_CONTROLLER_NO_MEMORY} is returned.</li></ul>
 * @since 21
 */
GameController_ErrorCode OH_GamePad_ButtonEvent_GetButtonCodeName(const struct GamePad_ButtonEvent* buttonEvent,
                                                                  char** codeName);

/**
 * @brief Obtains the number of pressed buttons from a button event.
 *
 * @param buttonEvent Pointer to the {@link GamePad_ButtonEvent} instance. The pointer cannot be null.
 * @param count Output parameter. Number of buttons.
 * @return <ul><li>If the operation is successful, {@link GAME_CONTROLLER_SUCCESS} is returned.</li>     <li>If **
 *     buttonEvent** is null, {@link GAME_CONTROLLER_PARAM_ERROR} is returned.</li></ul>
 * @since 21
 */
GameController_ErrorCode OH_GamePad_PressedButtons_GetCount(const struct GamePad_ButtonEvent* buttonEvent,
                                                            int32_t* count);

/**
 * @brief Obtains the button information at a specified index from a button event.
 *
 * @param buttonEvent Pointer to the {@link GamePad_ButtonEvent} instance. The pointer cannot be null.
 * @param index Button index.
 * @param pressedButton Output parameter. Double pointer to the pressed button.
 * @return <ul><li>If the operation is successful, {@link GAME_CONTROLLER_SUCCESS} is returned.</li>     <li>If **
 *     buttonEvent** is null, or **index** is less than 0 or greater than or equal to the total number of keys,
 *     {@link GAME_CONTROLLER_PARAM_ERROR} is returned.</li></ul>
 * @since 21
 * @see {@link OH_GamePad_DestroyPressedButton} destroys a pressed button instance.
 */
GameController_ErrorCode OH_GamePad_PressedButtons_GetButtonInfo(const struct GamePad_ButtonEvent* buttonEvent,
                                                                 const int32_t index,
                                                                 GamePad_PressedButton** pressedButton);

/**
 * @brief Destroys a pressed button instance.
 *
 * @param pressedButton Double pointer to the {@link GamePad_PressedButton} instance. The pointer cannot be null.
 * @return <ul><li>If the operation is successful, {@link GAME_CONTROLLER_SUCCESS} is returned.</li>     <li>If **
 *     pressedButton** is null, {@link GAME_CONTROLLER_PARAM_ERROR} is returned.</li></ul>
 * @since 21
 */
GameController_ErrorCode OH_GamePad_DestroyPressedButton(GamePad_PressedButton** pressedButton);

/**
 * @brief Obtains the button code from a pressed button.
 *
 * @param pressedButton Pointer to the {@link GamePad_PressedButton} instance. The pointer cannot be null.
 * @param code Output parameter. Button code.
 * @return <ul><li>If the operation is successful, {@link GAME_CONTROLLER_SUCCESS} is returned.</li>     <li>If **
 *     pressedButton** is null, {@link GAME_CONTROLLER_PARAM_ERROR} is returned.</li></ul>
 * @since 21
 */
GameController_ErrorCode OH_GamePad_PressedButton_GetButtonCode(const struct GamePad_PressedButton* pressedButton,
                                                                int32_t* code);

/**
 * @brief Obtains the button name from a pressed button.
 *
 * @param pressedButton Pointer to the {@link GamePad_PressedButton} instance. The pointer cannot be null.
 * @param codeName Output parameter. Double pointer to the button name.
 * @return <ul><li>If the operation is successful, {@link GAME_CONTROLLER_SUCCESS} is returned.</li>     <li>If **
 *     pressedButton** or **codeName** is null, {@link GAME_CONTROLLER_PARAM_ERROR} is returned.</li>     <li>If the
 *     device has insufficient memory, {@link GAME_CONTROLLER_NO_MEMORY} is returned.</li></ul>
 * @since 21
 */
GameController_ErrorCode OH_GamePad_PressedButton_GetButtonCodeName(const struct GamePad_PressedButton* pressedButton,
                                                                    char** codeName);

/**
 * @brief Obtains the action time from a button event.
 *
 * @param buttonEvent Pointer to the {@link GamePad_ButtonEvent} instance. The pointer cannot be null.
 * @param actionTime Output parameter. Action time. Unix timestamp, in milliseconds.
 * @return <ul><li>If the operation is successful, returns {@link GAME_CONTROLLER_SUCCESS}.</li>     <li>If the **
 *     buttonEvent** parameter is null, returns {@link GAME_CONTROLLER_PARAM_ERROR}.</li></ul>
 * @since 21
 */
GameController_ErrorCode OH_GamePad_ButtonEvent_GetActionTime(const struct GamePad_ButtonEvent* buttonEvent,
                                                              int64_t* actionTime);

/**
 * @brief Obtains the device ID from an axis event.
 *
 * @param axisEvent Pointer to the {@link GamePad_AxisEvent} instance. The pointer cannot be null.
 * @param deviceId Output parameter. Double pointer to the device ID.
 * @return <ul><li>If the operation is successful, {@link GAME_CONTROLLER_SUCCESS} is returned.</li>     <li>If **
 *     axisEvent** or **deviceId** is null, {@link GAME_CONTROLLER_PARAM_ERROR} is returned.</li>     <li>If the device
 *     has insufficient memory, {@link GAME_CONTROLLER_NO_MEMORY} is returned.</li></ul>
 * @since 21
 */
GameController_ErrorCode OH_GamePad_AxisEvent_GetDeviceId(const struct GamePad_AxisEvent* axisEvent,
                                                          char** deviceId);

/**
 * @brief Obtains the source type of an axis event.
 *
 * @param axisEvent Pointer to the {@link GamePad_AxisEvent} instance. The pointer cannot be null.
 * @param axisSourceType Output parameter. Source type of the axis event.
 * @return <ul><li>If the operation is successful, returns {@link GAME_CONTROLLER_SUCCESS}.</li>     <li>If the **
 *     axisEvent** parameter is null, {@link GAME_CONTROLLER_PARAM_ERROR} is returned.</li></ul>
 * @since 21
 */
GameController_ErrorCode OH_GamePad_AxisEvent_GetAxisSourceType(const struct GamePad_AxisEvent* axisEvent,
                                                                GamePad_AxisSourceType* axisSourceType);

/**
 * @brief Obtains the X-axis value from an axis event.
 *
 * @param axisEvent Pointer to the {@link GamePad_AxisEvent} instance. The pointer cannot be null.
 * @param axisValue Output parameter. Axis value. The value range is [-1.0, 1.0].
 * @return <ul><li>If the operation is successful, {@link GAME_CONTROLLER_SUCCESS} is returned.</li>     <li>If the **
 *     axisEvent** parameter is null, {@link GAME_CONTROLLER_PARAM_ERROR} is returned.</li></ul>
 * @since 21
 */
GameController_ErrorCode OH_GamePad_AxisEvent_GetXAxisValue(const struct GamePad_AxisEvent* axisEvent,
                                                            double* axisValue);

/**
 * @brief Obtains the Y-axis value from an axis event.
 *
 * @param axisEvent Pointer to the {@link GamePad_AxisEvent} instance. The pointer cannot be null.
 * @param axisValue Output parameter. Axis value. The value range is [-1.0, 1.0].
 * @return <ul><li>If the operation is successful, {@link GAME_CONTROLLER_SUCCESS} is returned.</li>     <li>If the **
 *     axisEvent** parameter is null, {@link GAME_CONTROLLER_PARAM_ERROR} is returned.</li></ul>
 * @since 21
 */
GameController_ErrorCode OH_GamePad_AxisEvent_GetYAxisValue(const struct GamePad_AxisEvent* axisEvent,
                                                            double* axisValue);

/**
 * @brief Obtains the Z-axis value from an axis event.
 *
 * @param axisEvent Pointer to the {@link GamePad_AxisEvent} instance. The pointer cannot be null.
 * @param axisValue Output parameter. Axis value. The value range is [-1.0, 1.0].
 * @return <ul><li>If the operation is successful, returns {@link GAME_CONTROLLER_SUCCESS}.</li>     <li>If the **
 *     axisEvent** parameter is null, {@link GAME_CONTROLLER_PARAM_ERROR} is returned.</li></ul>
 * @since 21
 */
GameController_ErrorCode OH_GamePad_AxisEvent_GetZAxisValue(const struct GamePad_AxisEvent* axisEvent,
                                                            double* axisValue);

/**
 * @brief Obtains the RZ-axis value from an axis event.
 *
 * @param axisEvent Pointer to the {@link GamePad_AxisEvent} instance. The pointer cannot be null.
 * @param axisValue Output parameter. Axis value. The value range is [-1.0, 1.0].
 * @return <ul><li>If the operation is successful, returns {@link GAME_CONTROLLER_SUCCESS}.</li>     <li>If the **
 *     axisEvent** parameter is null, {@link GAME_CONTROLLER_PARAM_ERROR} is returned.</li></ul>
 * @since 21
 */
GameController_ErrorCode OH_GamePad_AxisEvent_GetRZAxisValue(const struct GamePad_AxisEvent* axisEvent,
                                                             double* axisValue);

/**
 * @brief Obtains the HatX-axis value from an axis event.
 *
 * @param axisEvent Pointer to the {@link GamePad_AxisEvent} instance. The pointer cannot be null.
 * @param axisValue Output parameter. Axis value. The value range is [-1.0, 1.0].
 * @return <ul><li>If the operation is successful, {@link GAME_CONTROLLER_SUCCESS} is returned.</li>     <li>If the **
 *     axisEvent** parameter is null, {@link GAME_CONTROLLER_PARAM_ERROR} is returned.</li></ul>
 * @since 21
 */
GameController_ErrorCode OH_GamePad_AxisEvent_GetHatXAxisValue(const struct GamePad_AxisEvent* axisEvent,
                                                               double* axisValue);

/**
 * @brief Obtains the HatY-axis value from an axis event.
 *
 * @param axisEvent Pointer to the {@link GamePad_AxisEvent} instance. The pointer cannot be null.
 * @param axisValue Output parameter. Axis value. The value range is [-1.0, 1.0].
 * @return <ul><li>If the operation is successful, {@link GAME_CONTROLLER_SUCCESS} is returned.</li>     <li>If the **
 *     axisEvent** parameter is null, {@link GAME_CONTROLLER_PARAM_ERROR} is returned.</li></ul>
 * @since 21
 */
GameController_ErrorCode OH_GamePad_AxisEvent_GetHatYAxisValue(const struct GamePad_AxisEvent* axisEvent,
                                                               double* axisValue);

/**
 * @brief Obtains the Brake-axis value from an axis event.
 *
 * @param axisEvent Pointer to the {@link GamePad_AxisEvent} instance. The pointer cannot be null.
 * @param axisValue Output parameter. Axis value. The value range is [-1.0, 1.0].
 * @return <ul><li>If the operation is successful, {@link GAME_CONTROLLER_SUCCESS} is returned.</li>     <li>If the **
 *     axisEvent** parameter is null, {@link GAME_CONTROLLER_PARAM_ERROR} is returned.</li></ul>
 * @since 21
 */
GameController_ErrorCode OH_GamePad_AxisEvent_GetBrakeAxisValue(const struct GamePad_AxisEvent* axisEvent,
                                                                double* axisValue);

/**
 * @brief Obtains the Gas-axis value from an axis event.
 *
 * @param axisEvent Pointer to the {@link GamePad_AxisEvent} instance. The pointer cannot be null.
 * @param axisValue Output parameter. Axis value. The value range is [-1.0, 1.0].
 * @return <ul><li>If the operation is successful, returns {@link GAME_CONTROLLER_SUCCESS}.</li>     <li>If the **
 *     axisEvent** parameter is null, {@link GAME_CONTROLLER_PARAM_ERROR} is returned.</li></ul>
 * @since 21
 */
GameController_ErrorCode OH_GamePad_AxisEvent_GetGasAxisValue(const struct GamePad_AxisEvent* axisEvent,
                                                              double* axisValue);

/**
 * @brief Obtains the action time from an axis event.
 *
 * @param axisEvent Pointer to the {@link GamePad_AxisEvent} instance. The pointer cannot be null.
 * @param actionTime Output parameter. Action time. Unix timestamp, in milliseconds.
 * @return <ul><li>If the operation is successful, {@link GAME_CONTROLLER_SUCCESS} is returned.</li>     <li>If the **
 *     axisEvent** parameter is null, {@link GAME_CONTROLLER_PARAM_ERROR} is returned.</li></ul>
 * @since 21
 */
GameController_ErrorCode OH_GamePad_AxisEvent_GetActionTime(const struct GamePad_AxisEvent* axisEvent,
                                                            int64_t* actionTime);

#ifdef __cplusplus
}
#endif

#endif //GAME_PAD_EVENT_H
/** @} */