hid_ddk_api.h
Overview
Declares the HID DDK functions for accessing an input device from the host.
File to include: <hid/hid_ddk_api.h>
Library: libhid.z.so
System capability: SystemCapability.Driver.HID.Extension
Since: 11
Related module: HidDdk
Summary
Functions
Function Description
OH_Hid_CreateDevice()
int32_t OH_Hid_CreateDevice(Hid_Device *hidDevice, Hid_EventProperties *hidEventProperties)
Description
Creates a device.
Required permissions: ohos.permission.ACCESS_DDK_HID
Since: 11
Parameters
| Name | Description |
|---|---|
| Hid_Device *hidDevice | Pointer to the basic information about the device to create, including the device name, vendor ID, and product ID. |
| Hid_EventProperties *hidEventProperties | Pointer to the event properties related to the device to create, including the event type, key event properties, absolute coordinate event properties, and relative coordinate event properties. |
Returns
| Type | Description |
|---|---|
| int32_t | deviceID (a non-negative number) if the API call is successful. HID_DDK_NO_PERM: The permission verification fails. HID_DDK_INVALID_OPERATION: The hid_ddk service connection fails. HID_DDK_INVALID_PARAMETER: The parameter check fails. Possible causes: 1. The input hidDevice is a null pointer. 2. The input hidEventProperties is a null pointer. 3. The length of properties exceeds 7 characters. 4. The length of hidEventTypes exceeds 5 characters. 5. The length of hidKeys exceeds 100 characters. 6. The length of hidAbs exceeds 26 characters. 7. The length of hidRelBits exceeds 13 characters. 8. The length of hidMiscellaneous exceeds 6 characters. HID_DDK_FAILURE: The number of devices reaches the maximum value 200. |
OH_Hid_EmitEvent()
int32_t OH_Hid_EmitEvent(int32_t deviceId, const Hid_EmitItem items[], uint16_t length)
Description
Sends an event list to a device.
Required permissions: ohos.permission.ACCESS_DDK_HID
Since: 11
Parameters
| Name | Description |
|---|---|
| int32_t deviceId | Device ID. |
| items | List of the events to send. The event information includes the event type (Hid_EventType), code (Hid_SynEvent, Hid_KeyCode, HidBtnCode, Hid_AbsAxes, Hid_RelAxes, or Hid_MscEvent), and value (depending on the actual device input). |
| uint16_t length | Length of the event list (number of events to be sent at a time). |
Returns
| Type | Description |
|---|---|
| int32_t | HID_DDK_SUCCESS: The API call is successful. HID_DDK_NO_PERM: The permission verification fails. HID_DDK_INVALID_OPERATION: The hid_ddk service connection fails or the caller is not the device creator. HID_DDK_INVALID_PARAMETER: The parameter check fails. Possible causes: 1. The device ID is less than 0. 2. The length of the input parameter length exceeds 7 characters. 3. The input parameter items is a null pointer. HID_DDK_NULL_PTR: The input device is a null pointer. |
OH_Hid_DestroyDevice()
int32_t OH_Hid_DestroyDevice(int32_t deviceId)
Description
Destroys a device.
Required permissions: ohos.permission.ACCESS_DDK_HID
Since: 11
Parameters
| Name | Description |
|---|---|
| int32_t deviceId | Device ID. |
Returns
| Type | Description |
|---|---|
| int32_t | HID_DDK_SUCCESS: The API call is successful. HID_DDK_NO_PERM: The permission verification fails. HID_DDK_INVALID_OPERATION: The hid_ddk service connection fails or the caller is not the device creator. HID_DDK_FAILURE: The corresponding device does not exist. |
OH_Hid_Init()
int32_t OH_Hid_Init(void)
Description
Initializes an HID DDK.
Required permissions: ohos.permission.ACCESS_DDK_HID
Since: 18
Returns
| Type | Description |
|---|---|
| int32_t | HID_DDK_SUCCESS: The operation is successful. HID_DDK_NO_PERM: The permission verification fails. HID_DDK_INIT_ERROR: The DDK initialization fails. HID_DDK_SERVICE_ERROR: Communication with the DDK server fails. |
OH_Hid_Release()
int32_t OH_Hid_Release(void)
Description
Releases an HID DDK.
Required permissions: ohos.permission.ACCESS_DDK_HID
Since: 18
Returns
| Type | Description |
|---|---|
| int32_t | HID_DDK_SUCCESS: The operation is successful. HID_DDK_NO_PERM: The permission verification fails. HID_DDK_INIT_ERROR: The DDK is not initialized. HID_DDK_SERVICE_ERROR: Communication with the DDK server fails. |
OH_Hid_Open()
int32_t OH_Hid_Open(uint64_t deviceId, uint8_t interfaceIndex, Hid_DeviceHandle **dev)
Description
Opens the device specified by deviceId and interfaceIndex.
Required permissions: ohos.permission.ACCESS_DDK_HID
Since: 18
Parameters
| Name | Description |
|---|---|
| uint64_t deviceId | Device ID. |
| uint8_t interfaceIndex | Interface index for the API of the HID device. |
| Hid_DeviceHandle **dev | Device operation handle. |
Returns
| Type | Description |
|---|---|
| int32_t | HID_DDK_SUCCESS: The operation is successful. HID_DDK_NO_PERM: The permission verification fails. HID_DDK_INIT_ERROR: The DDK is not initialized. HID_DDK_SERVICE_ERROR: Communication with the DDK server fails. HID_DDK_MEMORY_ERROR: Memory allocation for the device fails. HID_DDK_IO_ERROR: The I/O operation fails. HID_DDK_INVALID_PARAMETER: The dev parameter or *dev is null. HID_DDK_DEVICE_NOT_FOUND: No device is found based on deviceId and interfaceIndex. |
OH_Hid_Close()
int32_t OH_Hid_Close(Hid_DeviceHandle **dev)
Description
Closes an HID device.
Required permissions: ohos.permission.ACCESS_DDK_HID
Since: 18
Parameters
| Name | Description |
|---|---|
| Hid_DeviceHandle **dev | Device operation handle. |
Returns
| Type | Description |
|---|---|
| int32_t | HID_DDK_SUCCESS: The operation is successful. HID_DDK_NO_PERM: The permission verification fails. HID_DDK_INIT_ERROR: The DDK is not initialized. HID_DDK_SERVICE_ERROR: Communication with the DDK server fails. HID_DDK_IO_ERROR: The I/O operation fails. HID_DDK_INVALID_PARAMETER: The dev parameter or *dev is null. |
OH_Hid_Write()
int32_t OH_Hid_Write(Hid_DeviceHandle *dev, uint8_t *data, uint32_t length, uint32_t *bytesWritten)
Description
Writes a report to an HID device.
Required permissions: ohos.permission.ACCESS_DDK_HID
Since: 18
Parameters
| Name | Description |
|---|---|
| Hid_DeviceHandle *dev | Device operation handle. |
| uint8_t *data | Data to be written. |
| uint32_t length | Length of data to be written. The maximum value is HID_MAX_REPORT_BUFFER_SIZE. Otherwise, the parameter verification fails. |
| uint32_t *bytesWritten | Number of written bytes. |
Returns
| Type | Description |
|---|---|
| int32_t | HID_DDK_SUCCESS: The operation is successful. HID_DDK_NO_PERM: The permission verification fails. HID_DDK_INVALID_PARAMETER: The parameter check fails. Possible causes: 1. dev is null. 2. data is null. 3. The value of length is 0; 4. The value of length exceeds HID_MAX_REPORT_BUFFER_SIZE. 5. bytesWritten is null. HID_DDK_INIT_ERROR: The DDK is not initialized. HID_DDK_SERVICE_ERROR: Communication with the DDK server fails. HID_DDK_IO_ERROR: The I/O operation fails. |
OH_Hid_ReadTimeout()
int32_t OH_Hid_ReadTimeout(Hid_DeviceHandle *dev, uint8_t *data, uint32_t bufSize, int timeout, uint32_t *bytesRead)
Description
Reads a report from the HID device within the specified timeout interval.
Required permissions: ohos.permission.ACCESS_DDK_HID
Since: 18
Parameters
| Name | Description |
|---|---|
| Hid_DeviceHandle *dev | Device operation handle. |
| uint8_t *data | Buffer for storing the read data. |
| uint32_t bufSize | Size of the buffer for storing the read data. The maximum size is HID_MAX_REPORT_BUFFER_SIZE. Otherwise, the parameter verification fails. |
| int timeout | Timeout interval, in ms. The value -1 indicates block waiting. |
| uint32_t *bytesRead | Number of bytes to read. |
Returns
| Type | Description |
|---|---|
| int32_t | HID_DDK_SUCCESS: The operation is successful. HID_DDK_NO_PERM: The permission verification fails. HID_DDK_INVALID_PARAMETER: The parameter check fails. Possible causes: 1. dev is null. 2. data is null. 3. The value of bufSize is 0. 4. The value of bufSize exceeds HID_MAX_REPORT_BUFFER_SIZE. 5. bytesRead is null. HID_DDK_INIT_ERROR: The DDK is not initialized. HID_DDK_SERVICE_ERROR: Communication with the DDK server fails. HID_DDK_MEMORY_ERROR: The memory data copy fails. HID_DDK_IO_ERROR: The I/O operation fails. HID_DDK_TIMEOUT: The read operation times out. |
OH_Hid_Read()
int32_t OH_Hid_Read(Hid_DeviceHandle *dev, uint8_t *data, uint32_t bufSize, uint32_t *bytesRead)
Description
Reads a report from the HID device. The blocking mode (that is, blocking remains active until data can be read) is used by default. You can call OH_Hid_SetNonBlocking to change the mode.
Required permissions: ohos.permission.ACCESS_DDK_HID
Since: 18
Parameters
| Name | Description |
|---|---|
| Hid_DeviceHandle *dev | Device operation handle. |
| uint8_t *data | Buffer for storing the read data. |
| uint32_t bufSize | Size of the buffer for storing the read data. The maximum size is HID_MAX_REPORT_BUFFER_SIZE. Otherwise, the parameter verification fails. |
| uint32_t *bytesRead | Number of bytes to read. |
Returns
| Type | Description |
|---|---|
| int32_t | HID_DDK_SUCCESS: The operation is successful. HID_DDK_NO_PERM: The permission verification fails. HID_DDK_INVALID_PARAMETER: The parameter check fails. Possible causes: 1. dev is null. 2. data is null. 3. The value of bufSize is 0. 4. The value of bufSize exceeds HID_MAX_REPORT_BUFFER_SIZE. 5. bytesRead is null. HID_DDK_INIT_ERROR: The DDK is not initialized. HID_DDK_SERVICE_ERROR: Communication with the DDK server fails. HID_DDK_MEMORY_ERROR: The memory data copy fails. HID_DDK_IO_ERROR: The I/O operation fails. HID_DDK_TIMEOUT: The read operation times out. |
OH_Hid_SetNonBlocking()
int32_t OH_Hid_SetNonBlocking(Hid_DeviceHandle *dev, int nonBlock)
Description
Sets the device read mode to non-blocking mode.
Required permissions: ohos.permission.ACCESS_DDK_HID
Since: 18
Parameters
| Name | Description |
|---|---|
| Hid_DeviceHandle *dev | Device operation handle. |
| int nonBlock | Whether to enable the non-blocking mode for reading data. - 1: The non-blocking mode is enabled. When OH_Hid_Read is called, if the device has readable data, HID_DDK_SUCCESS is returned; if the device has no readable data, HID_DDK_TIMEOUT is returned. - 0: The non-blocking mode is disabled. |
Returns
| Type | Description |
|---|---|
| int32_t | HID_DDK_SUCCESS: The operation is successful. HID_DDK_NO_PERM: The permission verification fails. HID_DDK_INIT_ERROR: The DDK is not initialized. HID_DDK_INVALID_PARAMETER: The parameter check fails. Possible causes: 1. dev is null. 2. The value of nonBlock is not 1 or 0. HID_DDK_SERVICE_ERROR: Communication with the DDK server fails. |
OH_Hid_GetRawInfo()
int32_t OH_Hid_GetRawInfo(Hid_DeviceHandle *dev, Hid_RawDevInfo *rawDevInfo)
Description
Obtains the original device information.
Required permissions: ohos.permission.ACCESS_DDK_HID
Since: 18
Parameters
| Name | Description |
|---|---|
| Hid_DeviceHandle *dev | Device operation handle. |
| Hid_RawDevInfo *rawDevInfo | Original device information, including the vendor ID, product ID, and bus type. |
Returns
| Type | Description |
|---|---|
| int32_t | HID_DDK_SUCCESS: The operation is successful. HID_DDK_NO_PERM: The permission verification fails. HID_DDK_INVALID_PARAMETER: The parameter check fails. Possible causes: 1. dev is null. 2. rawDevInfo is null. HID_DDK_INIT_ERROR: The DDK is not initialized. HID_DDK_SERVICE_ERROR: Communication with the DDK server fails. HID_DDK_IO_ERROR: The I/O operation fails. HID_DDK_INVALID_OPERATION: This operation is not supported. |
OH_Hid_GetRawName()
int32_t OH_Hid_GetRawName(Hid_DeviceHandle *dev, char *data, uint32_t bufSize)
Description
Obtains the original device name.
Required permissions: ohos.permission.ACCESS_DDK_HID
Since: 18
Parameters
| Name | Description |
|---|---|
| Hid_DeviceHandle *dev | Device operation handle. |
| char *data | Buffer for storing the read data. |
| uint32_t bufSize | Size of the buffer for storing the read data. The maximum size is HID_MAX_REPORT_BUFFER_SIZE. Otherwise, the parameter verification fails. |
Returns
| Type | Description |
|---|---|
| int32_t | HID_DDK_SUCCESS: The operation is successful. HID_DDK_NO_PERM: The permission verification fails. HID_DDK_INVALID_PARAMETER: The parameter check fails. Possible causes: 1. dev is null. 2. data is null. 3. The value of bufSize is 0. 4. The value of bufSize exceeds HID_MAX_REPORT_BUFFER_SIZE. HID_DDK_INIT_ERROR: The DDK is not initialized. HID_DDK_SERVICE_ERROR: Communication with the DDK server fails. HID_DDK_MEMORY_ERROR: The memory data copy fails. HID_DDK_IO_ERROR: The I/O operation fails. HID_DDK_INVALID_OPERATION: This operation is not supported. |
OH_Hid_GetPhysicalAddress()
int32_t OH_Hid_GetPhysicalAddress(Hid_DeviceHandle *dev, char *data, uint32_t bufSize)
Description
Obtains the physical address of the HID device.
Required permissions: ohos.permission.ACCESS_DDK_HID
Since: 18
Parameters
| Name | Description |
|---|---|
| Hid_DeviceHandle *dev | Device operation handle. |
| char *data | Buffer for storing the read data. |
| uint32_t bufSize | Size of the buffer for storing the read data. The maximum size is HID_MAX_REPORT_BUFFER_SIZE. Otherwise, the parameter verification fails. |
Returns
| Type | Description |
|---|---|
| int32_t | HID_DDK_SUCCESS: The operation is successful. HID_DDK_NO_PERM: The permission verification fails. HID_DDK_INVALID_PARAMETER: The parameter check fails. Possible causes: 1. dev is null. 2. data is null. 3. The value of bufSize is 0. 4. The value of bufSize exceeds HID_MAX_REPORT_BUFFER_SIZE. HID_DDK_INIT_ERROR: The DDK is not initialized. HID_DDK_SERVICE_ERROR: Communication with the DDK server fails. HID_DDK_MEMORY_ERROR: The memory data copy fails. HID_DDK_IO_ERROR: The I/O operation fails. HID_DDK_INVALID_OPERATION: This operation is not supported. |
OH_Hid_GetRawUniqueId()
int32_t OH_Hid_GetRawUniqueId(Hid_DeviceHandle *dev, uint8_t *data, uint32_t bufSize)
Description
Obtains the original unique identifier of a device.
Required permissions: ohos.permission.ACCESS_DDK_HID
Since: 18
Parameters
| Name | Description |
|---|---|
| Hid_DeviceHandle *dev | Device operation handle. |
| uint8_t *data | Buffer for storing the read data. |
| uint32_t bufSize | Size of the buffer for storing the read data. The maximum size is HID_MAX_REPORT_BUFFER_SIZE. Otherwise, the parameter verification fails. |
Returns
| Type | Description |
|---|---|
| int32_t | HID_DDK_SUCCESS: The operation is successful. HID_DDK_NO_PERM: The permission verification fails. HID_DDK_INVALID_PARAMETER: The parameter check fails. Possible causes: 1. dev is null. 2. data is null. 3. The value of bufSize is 0. 4. The value of bufSize exceeds HID_MAX_REPORT_BUFFER_SIZE. HID_DDK_INIT_ERROR: The DDK is not initialized. HID_DDK_SERVICE_ERROR: Communication with the DDK server fails. HID_DDK_MEMORY_ERROR: The memory data copy fails. HID_DDK_IO_ERROR: The I/O operation fails. HID_DDK_INVALID_OPERATION: This operation is not supported. |
OH_Hid_SendReport()
int32_t OH_Hid_SendReport(Hid_DeviceHandle *dev, Hid_ReportType reportType, const uint8_t *data, uint32_t length)
Description
Sends a report to the HID device.
Required permissions: ohos.permission.ACCESS_DDK_HID
Since: 18
Parameters
| Name | Description |
|---|---|
| Hid_DeviceHandle *dev | Device operation handle. |
| Hid_ReportType reportType | Report type. |
| const uint8_t *data | Data to be sent. |
| uint32_t length | Length of the data to be sent, in bytes. The maximum value is HID_MAX_REPORT_BUFFER_SIZE. Otherwise, the parameter verification fails. |
Returns
| Type | Description |
|---|---|
| int32_t | HID_DDK_SUCCESS: The operation is successful. HID_DDK_NO_PERM: The permission verification fails. HID_DDK_INVALID_PARAMETER: The parameter check fails. Possible causes: 1. dev is null. 2. data is null. 3. The value of length is 0; 4. The value of length exceeds HID_MAX_REPORT_BUFFER_SIZE. HID_DDK_INIT_ERROR: The DDK is not initialized. HID_DDK_SERVICE_ERROR: Communication with the DDK server fails. HID_DDK_IO_ERROR: The I/O operation fails. HID_DDK_INVALID_OPERATION: This operation is not supported. |
OH_Hid_GetReport()
int32_t OH_Hid_GetReport(Hid_DeviceHandle *dev, Hid_ReportType reportType, uint8_t *data, uint32_t bufSize)
Description
Obtains a report from the HID device.
Required permissions: ohos.permission.ACCESS_DDK_HID
Since: 18
Parameters
| Name | Description |
|---|---|
| Hid_DeviceHandle *dev | Device operation handle. |
| Hid_ReportType reportType | Report type. |
| uint8_t *data | Buffer for storing the read data. |
| uint32_t bufSize | Size of the buffer for storing the read data. The maximum size is HID_MAX_REPORT_BUFFER_SIZE. Otherwise, the parameter verification fails. |
Returns
| Type | Description |
|---|---|
| int32_t | HID_DDK_SUCCESS: The operation is successful. HID_DDK_NO_PERM: The permission verification fails. HID_DDK_INVALID_PARAMETER: The parameter check fails. Possible causes: 1. dev is null. 2. data is null. 3. The value of bufSize is 0. 4. The value of bufSize exceeds HID_MAX_REPORT_BUFFER_SIZE. HID_DDK_INIT_ERROR: The DDK is not initialized. HID_DDK_SERVICE_ERROR: Communication with the DDK server fails. HID_DDK_MEMORY_ERROR: The memory data copy fails. HID_DDK_IO_ERROR: The I/O operation fails. HID_DDK_INVALID_OPERATION: This operation is not supported. |
OH_Hid_GetReportDescriptor()
int32_t OH_Hid_GetReportDescriptor(Hid_DeviceHandle *dev, uint8_t *buf, uint32_t bufSize, uint32_t *bytesRead)
Description
Obtains the report descriptor of the HID device.
Required permissions: ohos.permission.ACCESS_DDK_HID
Since: 18
Parameters
| Name | Description |
|---|---|
| Hid_DeviceHandle *dev | Device operation handle. |
| uint8_t *buf | Buffer for storing descriptors. |
| uint32_t bufSize | Size of the buffer, in bytes. The maximum value is HID_MAX_REPORT_BUFFER_SIZE. Otherwise, the parameter verification fails. |
| uint32_t *bytesRead | Number of bytes to read. |
Returns
| Type | Description |
|---|---|
| int32_t | HID_DDK_SUCCESS: The operation is successful. HID_DDK_NO_PERM: The permission verification fails. HID_DDK_INVALID_PARAMETER: The parameter check fails. Possible causes: 1. dev is null. 2. buf is null. 3. The value of bufSize is 0. 4. The value of bufSize exceeds HID_MAX_REPORT_BUFFER_SIZE. 5. bytesRead is null. HID_DDK_INIT_ERROR: The DDK is not initialized. HID_DDK_SERVICE_ERROR: Communication with the DDK server fails. HID_DDK_MEMORY_ERROR: The memory data copy fails. HID_DDK_IO_ERROR: The I/O operation fails. HID_DDK_INVALID_OPERATION: This operation is not supported. |