diff --git a/ViGEmClient.h b/ViGEmClient.h index 721c366..64f8416 100644 --- a/ViGEmClient.h +++ b/ViGEmClient.h @@ -28,7 +28,11 @@ SOFTWARE. #include "ViGEmBusShared.h" - +/** + * \typedef enum _VIGEM_ERRORS + * + * \brief Defines an alias representing the ViGEm errors. + */ typedef enum _VIGEM_ERRORS { VIGEM_ERROR_NONE = 0x20000000, @@ -46,10 +50,30 @@ typedef enum _VIGEM_ERRORS VIGEM_ERROR_BUS_ALREADY_CONNECTED = 0xE0000012 } VIGEM_ERROR; +/** + * \def VIGEM_SUCCESS(_val_) (_val_ == VIGEM_ERROR_NONE); + * + * \brief A macro that defines success. + * + * \author Benjamin "Nefarius" Höglinger + * \date 28.08.2017 + * + * \param _val_ The VIGEM_ERROR value. + */ #define VIGEM_SUCCESS(_val_) (_val_ == VIGEM_ERROR_NONE) - +/** + * \typedef struct _VIGEM_CLIENT_T *PVIGEM_CLIENT + * + * \brief Defines an alias representing a driver connection object. + */ typedef struct _VIGEM_CLIENT_T *PVIGEM_CLIENT; + +/** + * \typedef struct _VIGEM_TARGET_T *PVIGEM_TARGET + * + * \brief Defines an alias representing a target device object. + */ typedef struct _VIGEM_TARGET_T *PVIGEM_TARGET; typedef VOID(CALLBACK* PVIGEM_X360_NOTIFICATION)( @@ -125,40 +149,276 @@ VIGEM_ERROR vigem_connect(PVIGEM_CLIENT vigem); */ void vigem_disconnect(PVIGEM_CLIENT vigem); +/** + * \fn PVIGEM_TARGET vigem_target_x360_alloc(void); + * + * \brief Allocates an object representing an Xbox 360 Controller device. + * + * \author Benjamin "Nefarius" Höglinger + * \date 28.08.2017 + * + * \return A PVIGEM_TARGET representing an Xbox 360 Controller device. + */ PVIGEM_TARGET vigem_target_x360_alloc(void); +/** + * \fn PVIGEM_TARGET vigem_target_ds4_alloc(void); + * + * \brief Allocates an object representing a DualShock 4 Controller device. + * + * \author Benjamin "Nefarius" Höglinger + * \date 28.08.2017 + * + * \return A PVIGEM_TARGET representing a DualShock 4 Controller device. + */ PVIGEM_TARGET vigem_target_ds4_alloc(void); +/** + * \fn void vigem_target_free(PVIGEM_TARGET target); + * + * \brief Frees up memory used by the target device object. This does not automatically remove + * the associated device from the bus, if present. If the target device doesn't get + * removed before this call, the device becomes orphaned until the owning process is + * terminated. + * + * \author Benjamin "Nefarius" Höglinger + * \date 28.08.2017 + * + * \param target The target device object. + */ void vigem_target_free(PVIGEM_TARGET target); +/** + * \fn VIGEM_ERROR vigem_target_add(PVIGEM_CLIENT vigem, PVIGEM_TARGET target); + * + * \brief Adds a provided target device to the bus driver, which is equal to a device plug-in + * event of a physical hardware device. This function blocks until the target device is + * in full operational mode. + * + * \author Benjamin "Nefarius" Höglinger + * \date 28.08.2017 + * + * \param vigem The driver connection object. + * \param target The target device object. + * + * \return A VIGEM_ERROR. + */ VIGEM_ERROR vigem_target_add(PVIGEM_CLIENT vigem, PVIGEM_TARGET target); +/** + * \fn VIGEM_ERROR vigem_target_add_async(PVIGEM_CLIENT vigem, PVIGEM_TARGET target, PVIGEM_TARGET_ADD_RESULT result); + * + * \brief Adds a provided target device to the bus driver, which is equal to a device plug-in + * event of a physical hardware device. This function immediately returns. An optional + * callback may be registered which gets called on error or if the target device has + * become fully operational. + * + * \author Benjamin "Nefarius" Höglinger + * \date 28.08.2017 + * + * \param vigem The driver connection object. + * \param target The target device object. + * \param result An optional function getting called when the target device becomes available. + * + * \return A VIGEM_ERROR. + */ VIGEM_ERROR vigem_target_add_async(PVIGEM_CLIENT vigem, PVIGEM_TARGET target, PVIGEM_TARGET_ADD_RESULT result); +/** + * \fn VIGEM_ERROR vigem_target_remove(PVIGEM_CLIENT vigem, PVIGEM_TARGET target); + * + * \brief Removes a provided target device from the bus driver, which is equal to a device + * unplug event of a physical hardware device. The target device object may be reused + * after this function is called. If this function is never called on target device + * objects, they will be removed from the bus when the owning process terminates. + * + * \author Benjamin "Nefarius" Höglinger + * \date 28.08.2017 + * + * \param vigem The driver connection object. + * \param target The target device object. + * + * \return A VIGEM_ERROR. + */ VIGEM_ERROR vigem_target_remove(PVIGEM_CLIENT vigem, PVIGEM_TARGET target); +/** + * \fn VIGEM_ERROR vigem_target_x360_register_notification(PVIGEM_CLIENT vigem, PVIGEM_TARGET target, PVIGEM_X360_NOTIFICATION notification); + * + * \brief Registers a function which gets called, when LED index or vibration state changes + * occur on the provided target device. This function fails if the provided target + * device isn't fully operational or in an erroneous state. + * + * \author Benjamin "Nefarius" Höglinger + * \date 28.08.2017 + * + * \param vigem The driver connection object. + * \param target The target device object. + * \param notification The notification callback. + * + * \return A VIGEM_ERROR. + */ VIGEM_ERROR vigem_target_x360_register_notification(PVIGEM_CLIENT vigem, PVIGEM_TARGET target, PVIGEM_X360_NOTIFICATION notification); +/** + * \fn VIGEM_ERROR vigem_target_ds4_register_notification(PVIGEM_CLIENT vigem, PVIGEM_TARGET target, PVIGEM_DS4_NOTIFICATION notification); + * + * \brief Registers a function which gets called, when LightBar or vibration state changes + * occur on the provided target device. This function fails if the provided target + * device isn't fully operational or in an erroneous state. + * + * \author Benjamin "Nefarius" Höglinger + * \date 28.08.2017 + * + * \param vigem The driver connection object. + * \param target The target device object. + * \param notification The notification callback. + * + * \return A VIGEM_ERROR. + */ VIGEM_ERROR vigem_target_ds4_register_notification(PVIGEM_CLIENT vigem, PVIGEM_TARGET target, PVIGEM_DS4_NOTIFICATION notification); +/** + * \fn void vigem_target_x360_unregister_notification(PVIGEM_TARGET target); + * + * \brief Removes a previously registered callback function from the provided target object. + * + * \author Benjamin "Nefarius" Höglinger + * \date 28.08.2017 + * + * \param target The target device object. + */ void vigem_target_x360_unregister_notification(PVIGEM_TARGET target); +/** + * \fn void vigem_target_ds4_unregister_notification(PVIGEM_TARGET target); + * + * \brief Removes a previously registered callback function from the provided target object. + * + * \author Benjamin "Nefarius" Höglinger + * \date 28.08.2017 + * + * \param target The target device object. + */ void vigem_target_ds4_unregister_notification(PVIGEM_TARGET target); +/** + * \fn void vigem_target_set_vid(PVIGEM_TARGET target, USHORT vid); + * + * \brief Overrides the default Vendor ID value with the provided one. + * + * \author Benjamin "Nefarius" Höglinger + * \date 28.08.2017 + * + * \param target The target device object. + * \param vid The Vendor ID to set. + */ void vigem_target_set_vid(PVIGEM_TARGET target, USHORT vid); +/** + * \fn void vigem_target_set_pid(PVIGEM_TARGET target, USHORT pid); + * + * \brief Overrides the default Product ID value with the provided one. + * + * \author Benjamin "Nefarius" Höglinger + * \date 28.08.2017 + * + * \param target The target device object. + * \param pid The Product ID to set. + */ void vigem_target_set_pid(PVIGEM_TARGET target, USHORT pid); +/** + * \fn USHORT vigem_target_get_vid(PVIGEM_TARGET target); + * + * \brief Returns the Vendor ID of the provided target device object. + * + * \author Benjamin "Nefarius" Höglinger + * \date 28.08.2017 + * + * \param target The target device object. + * + * \return The Vendor ID. + */ USHORT vigem_target_get_vid(PVIGEM_TARGET target); +/** + * \fn USHORT vigem_target_get_pid(PVIGEM_TARGET target); + * + * \brief Returns the Product ID of the provided target device object. + * + * \author Benjamin "Nefarius" Höglinger + * \date 28.08.2017 + * + * \param target The target device object. + * + * \return The Product ID. + */ USHORT vigem_target_get_pid(PVIGEM_TARGET target); +/** + * \fn VIGEM_ERROR vigem_target_x360_update(PVIGEM_CLIENT vigem, PVIGEM_TARGET target, XUSB_REPORT report); + * + * \brief Sends a state report to the provided target device. + * + * \author Benjamin "Nefarius" Höglinger + * \date 28.08.2017 + * + * \param vigem The driver connection object. + * \param target The target device object. + * \param report The report to send to the target device. + * + * \return A VIGEM_ERROR. + */ VIGEM_ERROR vigem_target_x360_update(PVIGEM_CLIENT vigem, PVIGEM_TARGET target, XUSB_REPORT report); +/** + * \fn VIGEM_ERROR vigem_target_ds4_update(PVIGEM_CLIENT vigem, PVIGEM_TARGET target, DS4_REPORT report); + * + * \brief Sends a state report to the provided target device. + * + * \author Benjamin "Nefarius" Höglinger + * \date 28.08.2017 + * + * \param vigem The driver connection object. + * \param target The target device object. + * \param report The report to send to the target device. + * + * \return A VIGEM_ERROR. + */ VIGEM_ERROR vigem_target_ds4_update(PVIGEM_CLIENT vigem, PVIGEM_TARGET target, DS4_REPORT report); +/** + * \fn ULONG vigem_target_get_index(PVIGEM_TARGET target); + * + * \brief Returns the internal index (serial number) the bus driver assigned to the provided + * target device object. Note that this value is specific to the inner workings of the + * bus driver, it does not reflect related values like player index or device arrival + * order experienced by other APIs. It may be used to identify the target device object + * for its lifetime. This value becomes invalid once the target device is removed from + * the bus and may change on the next addition of the device. + * + * \author Benjamin "Nefarius" Höglinger + * \date 28.08.2017 + * + * \param target The target device object. + * + * \return The internally used index of the target device. + */ ULONG vigem_target_get_index(PVIGEM_TARGET target); +/** + * \fn VIGEM_TARGET_TYPE vigem_target_get_type(PVIGEM_TARGET target); + * + * \brief Returns the type of the provided target device object. + * + * \author Benjamin "Nefarius" Höglinger + * \date 28.08.2017 + * + * \param target The target device object. + * + * \return A VIGEM_TARGET_TYPE. + */ VIGEM_TARGET_TYPE vigem_target_get_type(PVIGEM_TARGET target); #endif // ViGEmClient_h__