1# UsbDDK 2 3 4## Overview 5 6Provides 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. 7 8\@syscap SystemCapability.Driver.USB.Extension 9 10**Since** 11 1210 13 14 15## Summary 16 17 18### File 19 20| Name| Description| 21| -------- | -------- | 22| [usb_ddk_api.h](usb__ddk__api_8h.md) | Declares the USB DDK APIs used by the USB host to access USB devices.<br>File to include: <usb/usb_ddk_api.h><br>Library: libusb_ndk.z.so| 23| [usb_ddk_types.h](usb__ddk__types_8h.md) | Provides the enumerated variables, structures, and macros used in USB DDK APIs.<br>File to include: <usb/usb_ddk_types.h> <br>Library: libusb_ndk.z.so| 24 25 26### Structs 27 28| Name| Description| 29| -------- | -------- | 30| [UsbControlRequestSetup](_usb_control_request_setup.md) | Setup data for control transfer. It corresponds to **Setup Data** in the USB protocol.| 31| [UsbDeviceDescriptor](_usb_device_descriptor.md) | Standard device descriptor, corresponding to **Standard Device Descriptor** in the USB protocol.| 32| [UsbConfigDescriptor](_usb_config_descriptor.md) | Standard configuration descriptor, corresponding to **Standard Configuration Descriptor** in the USB protocol.| 33| [UsbInterfaceDescriptor](_usb_interface_descriptor.md) | Standard interface descriptor, corresponding to **Standard Interface Descriptor** in the USB protocol.| 34| [UsbEndpointDescriptor](_usb_endpoint_descriptor.md) | Standard endpoint descriptor, corresponding to **Standard Endpoint Descriptor** in the USB protocol.| 35| [UsbDdkEndpointDescriptor](_usb_ddk_endpoint_descriptor.md) | Endpoint descriptor.| 36| [UsbDdkInterfaceDescriptor](_usb_ddk_interface_descriptor.md) | Interface descriptor.| 37| [UsbDdkInterface](_usb_ddk_interface.md) | USB DDK interface, which is a collection of alternate settings for a particular USB interface.| 38| [UsbDdkConfigDescriptor](_usb_ddk_config_descriptor.md) | Configuration descriptor.| 39| [UsbRequestPipe](_usb_request_pipe.md) | Request pipe.| 40| [UsbDeviceMemMap](_usb_device_mem_map.md) | Device memory map created by calling [OH_Usb_CreateDeviceMemMap()](#oh_usb_createdevicememmap). A buffer using the device memory map can provide better performance.| 41 42### Enums 43 44| Name| Description| 45| -------- | -------- | 46| [UsbDdkErrCode](#usbddkerrcode) {<br>USB_DDK_SUCCESS = 0, USB_DDK_FAILED = -1, USB_DDK_INVALID_PARAMETER = -2, USB_DDK_MEMORY_ERROR = -3,<br>USB_DDK_INVALID_OPERATION = -4, USB_DDK_NULL_PTR = -5, USB_DDK_DEVICE_BUSY = -6, USB_DDK_TIMEOUT = -7<br>} | USB DDK error code definitions.| 47 48 49### Functions 50 51| Name| Description| 52| -------- | -------- | 53| [OH_Usb_Init](#oh_usb_init) (void) | Initializes the DDK.| 54| [OH_Usb_Release](#oh_usb_release) (void) | Releases the DDK.| 55| [OH_Usb_GetDeviceDescriptor](#oh_usb_getdevicedescriptor) (uint64_t deviceId, struct [UsbDeviceDescriptor](_usb_device_descriptor.md) \*desc) | Obtains the device descriptor.| 56| [OH_Usb_GetConfigDescriptor](#oh_usb_getconfigdescriptor) (uint64_t deviceId, uint8_t configIndex, struct [UsbDdkConfigDescriptor](_usb_ddk_config_descriptor.md) \*\*const config) | Obtains the configuration descriptor. To avoid memory leakage, use **OH_Usb_FreeConfigDescriptor** to release a descriptor after use.| 57| [OH_Usb_FreeConfigDescriptor](#oh_usb_freeconfigdescriptor) (const struct [UsbDdkConfigDescriptor](_usb_ddk_config_descriptor.md) \*const config) | Releases the configuration descriptor. To avoid memory leakage, release a descriptor after use.| 58| [OH_Usb_ClaimInterface](#oh_usb_claiminterface) (uint64_t deviceId, uint8_t interfaceIndex, uint64_t \*[interfaceHandle](usb__ddk__types_8h.md#interfacehandle)) | Declares a USB interface.| 59| [OH_Usb_ReleaseInterface](#oh_usb_releaseinterface) (uint64_t [interfaceHandle](usb__ddk__types_8h.md#interfacehandle)) | Releases a USB interface.| 60| [OH_Usb_SelectInterfaceSetting](#oh_usb_selectinterfacesetting) (uint64_t [interfaceHandle](usb__ddk__types_8h.md#interfacehandle), uint8_t settingIndex) | Activates the alternate setting of a USB interface.| 61| [OH_Usb_GetCurrentInterfaceSetting](#oh_usb_getcurrentinterfacesetting) (uint64_t [interfaceHandle](usb__ddk__types_8h.md#interfacehandle), uint8_t \*settingIndex) | Obtains the activated alternate setting of a USB interface.| 62| [OH_Usb_SendControlReadRequest](#oh_usb_sendcontrolreadrequest) (uint64_t [interfaceHandle](usb__ddk__types_8h.md#interfacehandle), const struct [UsbControlRequestSetup](_usb_control_request_setup.md) \*setup, uint32_t [timeout](usb__ddk__types_8h.md#timeout), uint8_t \*data, uint32_t \*dataLen) | Sends a control read transfer request. This API works in a synchronous manner.| 63| [OH_Usb_SendControlWriteRequest](#oh_usb_sendcontrolwriterequest) (uint64_t [interfaceHandle](usb__ddk__types_8h.md#interfacehandle), const struct [UsbControlRequestSetup](_usb_control_request_setup.md) \*setup, uint32_t [timeout](usb__ddk__types_8h.md#timeout), const uint8_t \*data, uint32_t dataLen) | Sends a control write transfer request. This API works in a synchronous manner.| 64| [OH_Usb_SendPipeRequest](#oh_usb_sendpiperequest) (const struct [UsbRequestPipe](_usb_request_pipe.md) \*pipe, [UsbDeviceMemMap](_usb_device_mem_map.md) \*devMmap) | Sends a pipe request. This API works in a synchronous manner. It applies to interrupt transfer and bulk transfer.| 65| [OH_Usb_CreateDeviceMemMap](#oh_usb_createdevicememmap) (uint64_t deviceId, size_t size, [UsbDeviceMemMap](_usb_device_mem_map.md) \*\*devMmap) | Creates a buffer. To avoid memory leakage, use [OH_Usb_DestroyDeviceMemMap()](#oh_usb_destroydevicememmap) to destroy a buffer after use.| 66| [OH_Usb_DestroyDeviceMemMap](#oh_usb_destroydevicememmap) ([UsbDeviceMemMap](_usb_device_mem_map.md) \*devMmap) | Destroys a buffer. To avoid resource leakage, destroy a buffer in time after use.| 67 68#### Description of deviceId 69 70You can call **queryDevices()** to obtain the device ID, that is, **deviceId**. 71For details, see [Peripheral Management Development](../../device/externaldevice-guidelines.md). 72 73## Enum Description 74 75 76### UsbDdkErrCode 77 78 79``` 80enum UsbDdkErrCode 81``` 82 83**Description** 84 85USB DDK error code definitions. 86 87| Value| Description| 88| -------- | -------- | 89| USB_DDK_SUCCESS | Operation successful.| 90| USB_DDK_FAILED | Operation failed.| 91| USB_DDK_INVALID_PARAMETER | Invalid parameter.| 92| USB_DDK_MEMORY_ERROR | Memory-related error, for example, insufficient memory, memory data copy failure, or memory application failure.| 93| USB_DDK_INVALID_OPERATION | Invalid operation.| 94| USB_DDK_NULL_PTR | Null pointer.| 95| USB_DDK_DEVICE_BUSY | Device busy.| 96| USB_DDK_TIMEOUT | Transfer timed out.| 97 98 99## Function Description 100 101 102### OH_Usb_ClaimInterface() 103 104 105``` 106int32_t OH_Usb_ClaimInterface (uint64_t deviceId, uint8_t interfaceIndex, uint64_t * interfaceHandle ) 107``` 108 109**Description** 110 111Declares a USB interface. 112 113**Required permissions**: ohos.permission.ACCESS_DDK_USB 114 115**Parameters** 116 117| Name| Description| 118| -------- | -------- | 119| deviceId | Device ID.| 120| interfaceIndex | Interface index, which corresponds to [bInterfaceNumber](_usb_interface_descriptor.md#binterfacenumber) in the USB protocol.| 121| interfaceHandle | Interface operation handle. After the interface is claimed successfully, a value will be assigned to this parameter.| 122 123**Returns** 124 125**0** if the operation is successful; a negative value otherwise. 126 127 128### OH_Usb_CreateDeviceMemMap() 129 130 131``` 132int32_t OH_Usb_CreateDeviceMemMap (uint64_t deviceId, size_t size, UsbDeviceMemMap ** devMmap ) 133``` 134 135**Description** 136 137Creates a buffer. To avoid memory leakage, use [OH_Usb_DestroyDeviceMemMap()](#oh_usb_destroydevicememmap) to destroy a buffer after use. 138 139**Required permissions**: ohos.permission.ACCESS_DDK_USB 140 141**Parameters** 142 143| Name| Description| 144| -------- | -------- | 145| deviceId | Device ID.| 146| size | Buffer size.| 147| devMmap | Data memory map, through which the created buffer is returned to the caller.| 148 149**Returns** 150 151**0** if the operation is successful; a negative value otherwise. 152 153 154### OH_Usb_DestroyDeviceMemMap() 155 156 157``` 158void OH_Usb_DestroyDeviceMemMap (UsbDeviceMemMap * devMmap) 159``` 160 161**Description** 162 163Destroys a buffer. To avoid resource leakage, destroy a buffer in time after use. 164 165**Required permissions**: ohos.permission.ACCESS_DDK_USB 166 167**Parameters** 168 169| Name| Description| 170| -------- | -------- | 171| devMmap | Destroys the buffer created by [OH_Usb_CreateDeviceMemMap()](#oh_usb_createdevicememmap).| 172 173 174### OH_Usb_FreeConfigDescriptor() 175 176 177``` 178void OH_Usb_FreeConfigDescriptor (struct UsbDdkConfigDescriptor *const config) 179``` 180 181**Description** 182 183Releases the configuration descriptor. To avoid memory leakage, use **OH_Usb_FreeConfigDescriptor** to release a descriptor after use. 184 185**Required permissions**: ohos.permission.ACCESS_DDK_USB 186 187**Parameters** 188 189| Name| Description| 190| -------- | -------- | 191| config | Configuration descriptor obtained by calling [OH_Usb_GetConfigDescriptor()](#oh_usb_getconfigdescriptor).| 192 193 194### OH_Usb_GetConfigDescriptor() 195 196 197``` 198int32_t OH_Usb_GetConfigDescriptor (uint64_t deviceId, uint8_t configIndex, struct UsbDdkConfigDescriptor **const config ) 199``` 200 201**Description** 202 203Obtains the configuration descriptor. To avoid memory leakage, use **OH_Usb_FreeConfigDescriptor** to release a descriptor after use. 204 205**Required permissions**: ohos.permission.ACCESS_DDK_USB 206 207**Parameters** 208 209| Name| Description| 210| -------- | -------- | 211| deviceId | Device ID.| 212| configIndex | Configuration ID, which corresponds to [bConfigurationValue](_usb_config_descriptor.md#bconfigurationvalue) in the USB protocol.| 213| config | Configuration descriptor, which includes the standard configuration descriptor defined in the USB protocol and the associated interface descriptor and endpoint descriptor.| 214 215**Returns** 216 217**0** if the operation is successful; a negative value otherwise. 218 219 220### OH_Usb_GetCurrentInterfaceSetting() 221 222 223``` 224int32_t OH_Usb_GetCurrentInterfaceSetting (uint64_t interfaceHandle, uint8_t * settingIndex ) 225``` 226 227**Description** 228 229Obtains the activated alternate setting of a USB interface. 230 231**Required permissions**: ohos.permission.ACCESS_DDK_USB 232 233**Parameters** 234 235| Name| Description| 236| -------- | -------- | 237| interfaceHandle | Interface operation handle.| 238| settingIndex | Index of the alternate setting, which corresponds to [bAlternateSetting](_usb_interface_descriptor.md#balternatesetting) in the USB protocol.| 239 240**Returns** 241 242**0** if the operation is successful; a negative value otherwise. 243 244 245### OH_Usb_GetDeviceDescriptor() 246 247 248``` 249int32_t OH_Usb_GetDeviceDescriptor (uint64_t deviceId, struct UsbDeviceDescriptor * desc ) 250``` 251 252**Description** 253 254Obtains the device descriptor. 255 256**Required permissions**: ohos.permission.ACCESS_DDK_USB 257 258**Parameters** 259 260| Name| Description| 261| -------- | -------- | 262| deviceId | Device ID.| 263| desc | Device descriptor. For details, see [UsbDeviceDescriptor](_usb_device_descriptor.md).| 264 265**Returns** 266 267**0** if the operation is successful; a negative value otherwise. 268 269 270### OH_Usb_Init() 271 272 273``` 274int32_t OH_Usb_Init (void ) 275``` 276 277**Description** 278 279Initializes the DDK. 280 281**Required permissions**: ohos.permission.ACCESS_DDK_USB 282 283**Returns** 284 285**0** if the operation is successful; a negative value otherwise. 286 287 288### OH_Usb_Release() 289 290 291``` 292void OH_Usb_Release (void ) 293``` 294 295**Description** 296 297Releases the DDK. 298 299**Required permissions**: ohos.permission.ACCESS_DDK_USB 300 301 302### OH_Usb_ReleaseInterface() 303 304 305``` 306int32_t OH_Usb_ReleaseInterface (uint64_t interfaceHandle) 307``` 308 309**Description** 310 311Releases a USB interface. 312 313**Required permissions**: ohos.permission.ACCESS_DDK_USB 314 315**Parameters** 316 317| Name| Description| 318| -------- | -------- | 319| interfaceHandle | Interface operation handle.| 320 321**Returns** 322 323**0** if the operation is successful; a negative value otherwise. 324 325 326### OH_Usb_SelectInterfaceSetting() 327 328 329``` 330int32_t OH_Usb_SelectInterfaceSetting (uint64_t interfaceHandle, uint8_t settingIndex ) 331``` 332 333**Description** 334 335Activates the alternate setting of a USB interface. 336 337**Required permissions**: ohos.permission.ACCESS_DDK_USB 338 339**Parameters** 340 341| Name| Description| 342| -------- | -------- | 343| interfaceHandle | Interface operation handle.| 344| settingIndex | Index of the alternate setting, which corresponds to [bAlternateSetting](_usb_interface_descriptor.md#balternatesetting) in the USB protocol.| 345 346**Returns** 347 348**0** if the operation is successful; a negative value otherwise. 349 350 351### OH_Usb_SendControlReadRequest() 352 353 354``` 355int32_t OH_Usb_SendControlReadRequest (uint64_t interfaceHandle, const struct UsbControlRequestSetup * setup, uint32_t timeout, uint8_t * data, uint32_t * dataLen ) 356``` 357 358**Description** 359 360Sends a control read transfer request. This API works in a synchronous manner. 361 362**Required permissions**: ohos.permission.ACCESS_DDK_USB 363 364**Parameters** 365 366| Name| Description| 367| -------- | -------- | 368| interfaceHandle | Interface operation handle.| 369| setup | Request parameters. For details, see [UsbControlRequestSetup](_usb_control_request_setup.md).| 370| timeout | Timeout duration, in milliseconds.| 371| data | Data to be transferred.| 372| dataLen | Data length. The return value indicates the length of the actually read data.| 373 374**Returns** 375 376**0** if the operation is successful; a negative value otherwise. 377 378 379### OH_Usb_SendControlWriteRequest() 380 381 382``` 383int32_t OH_Usb_SendControlWriteRequest (uint64_t interfaceHandle, const struct UsbControlRequestSetup * setup, uint32_t timeout, const uint8_t * data, uint32_t dataLen ) 384``` 385 386**Description** 387 388Sends a control write transfer request. This API works in a synchronous manner. 389 390**Required permissions**: ohos.permission.ACCESS_DDK_USB 391 392**Parameters** 393 394| Name| Description| 395| -------- | -------- | 396| interfaceHandle | Interface operation handle.| 397| setup | Request parameters. For details, see [UsbControlRequestSetup](_usb_control_request_setup.md).| 398| timeout | Timeout duration, in milliseconds.| 399| data | Data to be transferred.| 400| dataLen | Data length.| 401 402**Returns** 403 404**0** if the operation is successful; a negative value otherwise. 405 406 407### OH_Usb_SendPipeRequest() 408 409 410``` 411int32_t OH_Usb_SendPipeRequest (const struct UsbRequestPipe * pipe, UsbDeviceMemMap * devMmap ) 412``` 413 414**Description** 415 416Sends a pipe request. This API works in a synchronous manner. It applies to interrupt transfer and bulk transfer. 417 418**Required permissions**: ohos.permission.ACCESS_DDK_USB 419 420**Parameters** 421 422| Name| Description| 423| -------- | -------- | 424| pipe | Pipe used to transfer data.| 425| devMmap | Device memory map, which can be obtained by calling [OH_Usb_CreateDeviceMemMap()](#oh_usb_createdevicememmap).| 426 427**Returns** 428 429**0** if the operation is successful; a negative value otherwise. 430