USB DDK
Overview
Provides USB DDK APIs to open and close USB interfaces, perform non-isochronous and isochronous data transfer over USB pipes, and implement control transfer and interrupt transfer, etc.
System capability: SystemCapability.Driver.USB.Extension
Since
10
Summary
File
| Name | Description |
|---|---|
| usb_ddk_api.h | Declares the USB DDK APIs used by the USB host to access USB devices. File to include: <usb/usb_ddk_api.h> Library: libusb_ndk.z.so |
| usb_ddk_types.h | Provides the enumerated variables, structures, and macros used in USB DDK APIs. File to include: <usb/usb_ddk_types.h> Library: libusb_ndk.z.so |
Structs
| Name | Description |
|---|---|
| UsbControlRequestSetup | Setup data for control transfer. It corresponds to Setup Data in the USB protocol. |
| UsbDeviceDescriptor | Standard device descriptor, corresponding to Standard Device Descriptor in the USB protocol. |
| UsbConfigDescriptor | Standard configuration descriptor, corresponding to Standard Configuration Descriptor in the USB protocol. |
| UsbInterfaceDescriptor | Standard interface descriptor, corresponding to Standard Interface Descriptor in the USB protocol. |
| UsbEndpointDescriptor | Standard endpoint descriptor, corresponding to Standard Endpoint Descriptor in the USB protocol. |
| UsbDdkEndpointDescriptor | Endpoint descriptor. |
| UsbDdkInterfaceDescriptor | Interface descriptor. |
| UsbDdkInterface | USB DDK interface, which is a collection of alternate settings for a particular USB interface. |
| UsbDdkConfigDescriptor | Configuration descriptor. |
| UsbRequestPipe | Request pipe. |
| UsbDeviceMemMap | Device memory map created by calling OH_Usb_CreateDeviceMemMap(). A buffer using the device memory map can provide better performance. |
Enums
| Name | Description |
|---|---|
| UsbDdkErrCode { USB_DDK_SUCCESS = 0, USB_DDK_FAILED = -1, USB_DDK_INVALID_PARAMETER = -2, USB_DDK_MEMORY_ERROR = -3, USB_DDK_INVALID_OPERATION = -4, USB_DDK_NULL_PTR = -5, USB_DDK_DEVICE_BUSY = -6, USB_DDK_TIMEOUT = -7 } |
USB DDK error code definitions. |
Functions
| Name | Description |
|---|---|
| OH_Usb_Init (void) | Initializes the DDK. |
| OH_Usb_Release (void) | Releases the DDK. |
| OH_Usb_GetDeviceDescriptor (uint64_t deviceId, struct UsbDeviceDescriptor *desc) | Obtains the device descriptor. |
| OH_Usb_GetConfigDescriptor (uint64_t deviceId, uint8_t configIndex, struct UsbDdkConfigDescriptor **const config) | Obtains the configuration descriptor. To avoid memory leakage, use OH_Usb_FreeConfigDescriptor to release a descriptor after use. |
| OH_Usb_FreeConfigDescriptor (const struct UsbDdkConfigDescriptor *const config) | Releases the configuration descriptor. To avoid memory leakage, release a descriptor after use. |
| OH_Usb_ClaimInterface (uint64_t deviceId, uint8_t interfaceIndex, uint64_t *interfaceHandle) | Declares a USB interface. |
| OH_Usb_ReleaseInterface (uint64_t interfaceHandle) | Releases a USB interface. |
| OH_Usb_SelectInterfaceSetting (uint64_t interfaceHandle, uint8_t settingIndex) | Activates the alternate setting of a USB interface. |
| OH_Usb_GetCurrentInterfaceSetting (uint64_t interfaceHandle, uint8_t *settingIndex) | Obtains the activated alternate setting of a USB interface. |
| OH_Usb_SendControlReadRequest (uint64_t interfaceHandle, const struct UsbControlRequestSetup *setup, uint32_t timeout, uint8_t *data, uint32_t *dataLen) | Sends a control read transfer request. This API works in a synchronous manner. |
| OH_Usb_SendControlWriteRequest (uint64_t interfaceHandle, const struct UsbControlRequestSetup *setup, uint32_t timeout, const uint8_t *data, uint32_t dataLen) | Sends a control write transfer request. This API works in a synchronous manner. |
| OH_Usb_SendPipeRequest (const struct UsbRequestPipe *pipe, UsbDeviceMemMap *devMmap) | Sends a pipe request. This API works in a synchronous manner. It applies to interrupt transfer and bulk transfer. |
| OH_Usb_CreateDeviceMemMap (uint64_t deviceId, size_t size, UsbDeviceMemMap **devMmap) | Creates a buffer. To avoid memory leakage, use OH_Usb_DestroyDeviceMemMap() to destroy a buffer after use. |
| OH_Usb_DestroyDeviceMemMap (UsbDeviceMemMap *devMmap) | Destroys a buffer. To avoid resource leakage, destroy a buffer in time after use. |
Description of deviceId
You can call queryDevices() to obtain the device ID, that is, deviceId. For details, see Peripheral Management Development.
Enum Description
UsbDdkErrCode
enum UsbDdkErrCode
Description
USB DDK error code definitions.
| Value | Description |
|---|---|
| USB_DDK_SUCCESS | Operation successful. |
| USB_DDK_FAILED | Operation failed. |
| USB_DDK_INVALID_PARAMETER | Invalid parameter. |
| USB_DDK_MEMORY_ERROR | Memory-related error, for example, insufficient memory, memory data copy failure, or memory application failure. |
| USB_DDK_INVALID_OPERATION | Invalid operation. |
| USB_DDK_NULL_PTR | Null pointer. |
| USB_DDK_DEVICE_BUSY | Device busy. |
| USB_DDK_TIMEOUT | Transfer timed out. |
Function Description
OH_Usb_ClaimInterface()
int32_t OH_Usb_ClaimInterface (uint64_t deviceId, uint8_t interfaceIndex, uint64_t * interfaceHandle )
Description
Declares a USB interface.
Required permissions: ohos.permission.ACCESS_DDK_USB
Parameters
| Name | Description |
|---|---|
| deviceId | Device ID. |
| interfaceIndex | Interface index, which corresponds to bInterfaceNumber in the USB protocol. |
| interfaceHandle | Interface operation handle. After the interface is claimed successfully, a value will be assigned to this parameter. |
Returns
0 if the operation is successful; a negative value otherwise.
OH_Usb_CreateDeviceMemMap()
int32_t OH_Usb_CreateDeviceMemMap (uint64_t deviceId, size_t size, UsbDeviceMemMap ** devMmap )
Description
Creates a buffer. To avoid memory leakage, use OH_Usb_DestroyDeviceMemMap() to destroy a buffer after use.
Required permissions: ohos.permission.ACCESS_DDK_USB
Parameters
| Name | Description |
|---|---|
| deviceId | Device ID. |
| size | Buffer size. |
| devMmap | Data memory map, through which the created buffer is returned to the caller. |
Returns
0 if the operation is successful; a negative value otherwise.
OH_Usb_DestroyDeviceMemMap()
void OH_Usb_DestroyDeviceMemMap (UsbDeviceMemMap * devMmap)
Description
Destroys a buffer. To avoid resource leakage, destroy a buffer in time after use.
Required permissions: ohos.permission.ACCESS_DDK_USB
Parameters
| Name | Description |
|---|---|
| devMmap | Destroys the buffer created by OH_Usb_CreateDeviceMemMap(). |
OH_Usb_FreeConfigDescriptor()
void OH_Usb_FreeConfigDescriptor (struct UsbDdkConfigDescriptor *const config)
Description
Releases the configuration descriptor. To avoid memory leakage, use OH_Usb_FreeConfigDescriptor to release a descriptor after use.
Required permissions: ohos.permission.ACCESS_DDK_USB
Parameters
| Name | Description |
|---|---|
| config | Configuration descriptor obtained by calling OH_Usb_GetConfigDescriptor(). |
OH_Usb_GetConfigDescriptor()
int32_t OH_Usb_GetConfigDescriptor (uint64_t deviceId, uint8_t configIndex, struct UsbDdkConfigDescriptor **const config )
Description
Obtains the configuration descriptor. To avoid memory leakage, use OH_Usb_FreeConfigDescriptor to release a descriptor after use.
Required permissions: ohos.permission.ACCESS_DDK_USB
Parameters
| Name | Description |
|---|---|
| deviceId | Device ID. |
| configIndex | Configuration ID, which corresponds to bConfigurationValue in the USB protocol. |
| config | Configuration descriptor, which includes the standard configuration descriptor defined in the USB protocol and the associated interface descriptor and endpoint descriptor. |
Returns
0 if the operation is successful; a negative value otherwise.
OH_Usb_GetCurrentInterfaceSetting()
int32_t OH_Usb_GetCurrentInterfaceSetting (uint64_t interfaceHandle, uint8_t * settingIndex )
Description
Obtains the activated alternate setting of a USB interface.
Required permissions: ohos.permission.ACCESS_DDK_USB
Parameters
| Name | Description |
|---|---|
| interfaceHandle | Interface operation handle. |
| settingIndex | Index of the alternate setting, which corresponds to bAlternateSetting in the USB protocol. |
Returns
0 if the operation is successful; a negative value otherwise.
OH_Usb_GetDeviceDescriptor()
int32_t OH_Usb_GetDeviceDescriptor (uint64_t deviceId, struct UsbDeviceDescriptor * desc )
Description
Obtains the device descriptor.
Required permissions: ohos.permission.ACCESS_DDK_USB
Parameters
| Name | Description |
|---|---|
| deviceId | Device ID. |
| desc | Device descriptor. For details, see UsbDeviceDescriptor. |
Returns
0 if the operation is successful; a negative value otherwise.
OH_Usb_Init()
int32_t OH_Usb_Init (void )
Description
Initializes the DDK.
Required permissions: ohos.permission.ACCESS_DDK_USB
Returns
0 if the operation is successful; a negative value otherwise.
OH_Usb_Release()
void OH_Usb_Release (void )
Description
Releases the DDK.
Required permissions: ohos.permission.ACCESS_DDK_USB
OH_Usb_ReleaseInterface()
int32_t OH_Usb_ReleaseInterface (uint64_t interfaceHandle)
Description
Releases a USB interface.
Required permissions: ohos.permission.ACCESS_DDK_USB
Parameters
| Name | Description |
|---|---|
| interfaceHandle | Interface operation handle. |
Returns
0 if the operation is successful; a negative value otherwise.
OH_Usb_SelectInterfaceSetting()
int32_t OH_Usb_SelectInterfaceSetting (uint64_t interfaceHandle, uint8_t settingIndex )
Description
Activates the alternate setting of a USB interface.
Required permissions: ohos.permission.ACCESS_DDK_USB
Parameters
| Name | Description |
|---|---|
| interfaceHandle | Interface operation handle. |
| settingIndex | Index of the alternate setting, which corresponds to bAlternateSetting in the USB protocol. |
Returns
0 if the operation is successful; a negative value otherwise.
OH_Usb_SendControlReadRequest()
int32_t OH_Usb_SendControlReadRequest (uint64_t interfaceHandle, const struct UsbControlRequestSetup * setup, uint32_t timeout, uint8_t * data, uint32_t * dataLen )
Description
Sends a control read transfer request. This API works in a synchronous manner.
Required permissions: ohos.permission.ACCESS_DDK_USB
Parameters
| Name | Description |
|---|---|
| interfaceHandle | Interface operation handle. |
| setup | Request parameters. For details, see UsbControlRequestSetup. |
| timeout | Timeout duration, in milliseconds. |
| data | Data to be transferred. |
| dataLen | Data length. The return value indicates the length of the actually read data. |
Returns
0 if the operation is successful; a negative value otherwise.
OH_Usb_SendControlWriteRequest()
int32_t OH_Usb_SendControlWriteRequest (uint64_t interfaceHandle, const struct UsbControlRequestSetup * setup, uint32_t timeout, const uint8_t * data, uint32_t dataLen )
Description
Sends a control write transfer request. This API works in a synchronous manner.
Required permissions: ohos.permission.ACCESS_DDK_USB
Parameters
| Name | Description |
|---|---|
| interfaceHandle | Interface operation handle. |
| setup | Request parameters. For details, see UsbControlRequestSetup. |
| timeout | Timeout duration, in milliseconds. |
| data | Data to be transferred. |
| dataLen | Data length. |
Returns
0 if the operation is successful; a negative value otherwise.
OH_Usb_SendPipeRequest()
int32_t OH_Usb_SendPipeRequest (const struct UsbRequestPipe * pipe, UsbDeviceMemMap * devMmap )
Description
Sends a pipe request. This API works in a synchronous manner. It applies to interrupt transfer and bulk transfer.
Required permissions: ohos.permission.ACCESS_DDK_USB
Parameters
| Name | Description |
|---|---|
| pipe | Pipe used to transfer data. |
| devMmap | Device memory map, which can be obtained by calling OH_Usb_CreateDeviceMemMap(). |
Returns
0 if the operation is successful; a negative value otherwise.