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 43### Types 44 45| Name| Description| 46| -------- | -------- | 47| [UsbDdkEndpointDescriptor](#usbddkendpointdescriptor) | Endpoint descriptor.| 48| [UsbDdkInterfaceDescriptor](#usbddkinterfacedescriptor) | Interface descriptor.| 49| [UsbDdkInterface](#usbddkinterface) | USB DDK interface, which is a collection of alternate settings for a particular USB interface.| 50| [UsbDdkConfigDescriptor](#usbddkconfigdescriptor) | Configuration descriptor.| 51| [UsbDeviceMemMap](#usbdevicememmap) | Device memory map created by calling [OH_Usb_CreateDeviceMemMap()](#oh_usb_createdevicememmap). A buffer using the device memory map can provide better performance.| 52 53 54### Enums 55 56| Name| Description| 57| -------- | -------- | 58| [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.| 59 60 61### Functions 62 63| Name| Description| 64| -------- | -------- | 65| [OH_Usb_Init](#oh_usb_init) (void) | Initializes the DDK.| 66| [OH_Usb_Release](#oh_usb_release) (void) | Releases the DDK.| 67| [OH_Usb_GetDeviceDescriptor](#oh_usb_getdevicedescriptor) (uint64_t deviceId, struct [UsbDeviceDescriptor](_usb_device_descriptor.md) \*desc) | Obtains the device descriptor.| 68| [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.| 69| [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.| 70| [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.| 71| [OH_Usb_ReleaseInterface](#oh_usb_releaseinterface) (uint64_t [interfaceHandle](usb__ddk__types_8h.md#interfacehandle)) | Releases a USB interface.| 72| [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.| 73| [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.| 74| [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.| 75| [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.| 76| [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.| 77| [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.| 78| [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.| 79 80 81## Type Description 82 83 84### UsbDdkConfigDescriptor 85 86 87``` 88typedef struct UsbDdkConfigDescriptor UsbDdkConfigDescriptor 89``` 90 91**Description** 92 93Configuration descriptor. 94 95 96### UsbDdkEndpointDescriptor 97 98 99``` 100typedef struct UsbDdkEndpointDescriptor UsbDdkEndpointDescriptor 101``` 102 103**Description** 104 105Endpoint descriptor. 106 107 108### UsbDdkInterface 109 110 111``` 112typedef struct UsbDdkInterface UsbDdkInterface 113``` 114 115**Description** 116 117USB DDK interface, which is a collection of alternate settings for a particular USB interface. 118 119 120### UsbDdkInterfaceDescriptor 121 122 123``` 124typedef struct UsbDdkInterfaceDescriptor UsbDdkInterfaceDescriptor 125``` 126 127**Description** 128 129Interface descriptor. 130 131 132### UsbDeviceMemMap 133 134 135``` 136typedef struct UsbDeviceMemMap UsbDeviceMemMap 137``` 138 139**Description** 140 141Device memory map created by calling [OH_Usb_CreateDeviceMemMap()](#oh_usb_createdevicememmap). A buffer using the device memory map can provide better performance. 142 143 144## Enum Description 145 146 147### UsbDdkErrCode 148 149 150``` 151enum UsbDdkErrCode 152``` 153 154**Description** 155 156USB DDK error code definitions. 157 158| Value| Description| 159| -------- | -------- | 160| USB_DDK_SUCCESS | Operation successful.| 161| USB_DDK_FAILED | Operation failed.| 162| USB_DDK_INVALID_PARAMETER | Invalid parameter.| 163| USB_DDK_MEMORY_ERROR | Memory-related error, for example, insufficient memory, memory data copy failure, or memory application failure.| 164| USB_DDK_INVALID_OPERATION | Invalid operation.| 165| USB_DDK_NULL_PTR | Null pointer.| 166| USB_DDK_DEVICE_BUSY | Device busy.| 167| USB_DDK_TIMEOUT | Transfer timed out.| 168 169 170## Function Description 171 172 173### OH_Usb_ClaimInterface() 174 175 176``` 177int32_t OH_Usb_ClaimInterface (uint64_t deviceId, uint8_t interfaceIndex, uint64_t * interfaceHandle ) 178``` 179 180**Description** 181 182Declares a USB interface. 183 184**Required permissions**: ohos.permission.ACCESS_DDK_USB 185 186**Parameters** 187 188| Name| Description| 189| -------- | -------- | 190| deviceId | Device ID.| 191| interfaceIndex | Interface index, which corresponds to [bInterfaceNumber](_usb_interface_descriptor.md#binterfacenumber) in the USB protocol.| 192| interfaceHandle | Interface operation handle. After the interface is claimed successfully, a value will be assigned to this parameter.| 193 194**Returns** 195 196**0** if the operation is successful; a negative value otherwise. 197 198 199### OH_Usb_CreateDeviceMemMap() 200 201 202``` 203int32_t OH_Usb_CreateDeviceMemMap (uint64_t deviceId, size_t size, UsbDeviceMemMap ** devMmap ) 204``` 205 206**Description** 207 208Creates a buffer. To avoid memory leakage, use [OH_Usb_DestroyDeviceMemMap()](#oh_usb_destroydevicememmap) to destroy a buffer after use. 209 210**Required permissions**: ohos.permission.ACCESS_DDK_USB 211 212**Parameters** 213 214| Name| Description| 215| -------- | -------- | 216| deviceId | Device ID.| 217| size | Buffer size.| 218| devMmap | Data memory map, through which the created buffer is returned to the caller.| 219 220**Returns** 221 222**0** if the operation is successful; a negative value otherwise. 223 224 225### OH_Usb_DestroyDeviceMemMap() 226 227 228``` 229void OH_Usb_DestroyDeviceMemMap (UsbDeviceMemMap * devMmap) 230``` 231 232**Description** 233 234Destroys a buffer. To avoid resource leakage, destroy a buffer in time after use. 235 236**Required permissions**: ohos.permission.ACCESS_DDK_USB 237 238**Parameters** 239 240| Name| Description| 241| -------- | -------- | 242| devMmap | Destroys the buffer created by [OH_Usb_CreateDeviceMemMap()](#oh_usb_createdevicememmap).| 243 244 245### OH_Usb_FreeConfigDescriptor() 246 247 248``` 249void OH_Usb_FreeConfigDescriptor (const struct UsbDdkConfigDescriptor *const config) 250``` 251 252**Description** 253 254Releases the configuration descriptor. To avoid memory leakage, use **OH_Usb_FreeConfigDescriptor** to release a descriptor after use. 255 256**Required permissions**: ohos.permission.ACCESS_DDK_USB 257 258**Parameters** 259 260| Name| Description| 261| -------- | -------- | 262| config | Configuration descriptor obtained by calling [OH_Usb_GetConfigDescriptor()](#oh_usb_getconfigdescriptor).| 263 264 265### OH_Usb_GetConfigDescriptor() 266 267 268``` 269int32_t OH_Usb_GetConfigDescriptor (uint64_t deviceId, uint8_t configIndex, struct UsbDdkConfigDescriptor **const config ) 270``` 271 272**Description** 273 274Obtains the configuration descriptor. To avoid memory leakage, use **OH_Usb_FreeConfigDescriptor** to release a descriptor after use. 275 276**Required permissions**: ohos.permission.ACCESS_DDK_USB 277 278**Parameters** 279 280| Name| Description| 281| -------- | -------- | 282| deviceId | Device ID.| 283| configIndex | Configuration ID, which corresponds to [bConfigurationValue](_usb_config_descriptor.md#bconfigurationvalue) in the USB protocol.| 284| config | Configuration descriptor, which includes the standard configuration descriptor defined in the USB protocol and the associated interface descriptor and endpoint descriptor.| 285 286**Returns** 287 288**0** if the operation is successful; a negative value otherwise. 289 290 291### OH_Usb_GetCurrentInterfaceSetting() 292 293 294``` 295int32_t OH_Usb_GetCurrentInterfaceSetting (uint64_t interfaceHandle, uint8_t * settingIndex ) 296``` 297 298**Description** 299 300Obtains the activated alternate setting of a USB interface. 301 302**Required permissions**: ohos.permission.ACCESS_DDK_USB 303 304**Parameters** 305 306| Name| Description| 307| -------- | -------- | 308| interfaceHandle | Interface operation handle.| 309| settingIndex | Index of the alternate setting, which corresponds to [bAlternateSetting](_usb_interface_descriptor.md#balternatesetting) in the USB protocol.| 310 311**Returns** 312 313**0** if the operation is successful; a negative value otherwise. 314 315 316### OH_Usb_GetDeviceDescriptor() 317 318 319``` 320int32_t OH_Usb_GetDeviceDescriptor (uint64_t deviceId, struct UsbDeviceDescriptor * desc ) 321``` 322 323**Description** 324 325Obtains the device descriptor. 326 327**Required permissions**: ohos.permission.ACCESS_DDK_USB 328 329**Parameters** 330 331| Name| Description| 332| -------- | -------- | 333| deviceId | Device ID.| 334| desc | Device descriptor. For details, see [UsbDeviceDescriptor](_usb_device_descriptor.md).| 335 336**Returns** 337 338**0** if the operation is successful; a negative value otherwise. 339 340 341### OH_Usb_Init() 342 343 344``` 345int32_t OH_Usb_Init (void ) 346``` 347 348**Description** 349 350Initializes the DDK. 351 352**Required permissions**: ohos.permission.ACCESS_DDK_USB 353 354**Returns** 355 356**0** if the operation is successful; a negative value otherwise. 357 358 359### OH_Usb_Release() 360 361 362``` 363void OH_Usb_Release (void ) 364``` 365 366**Description** 367 368Releases the DDK. 369 370**Required permissions**: ohos.permission.ACCESS_DDK_USB 371 372 373### OH_Usb_ReleaseInterface() 374 375 376``` 377int32_t OH_Usb_ReleaseInterface (uint64_t interfaceHandle) 378``` 379 380**Description** 381 382Releases a USB interface. 383 384**Required permissions**: ohos.permission.ACCESS_DDK_USB 385 386**Parameters** 387 388| Name| Description| 389| -------- | -------- | 390| interfaceHandle | Interface operation handle.| 391 392**Returns** 393 394**0** if the operation is successful; a negative value otherwise. 395 396 397### OH_Usb_SelectInterfaceSetting() 398 399 400``` 401int32_t OH_Usb_SelectInterfaceSetting (uint64_t interfaceHandle, uint8_t settingIndex ) 402``` 403 404**Description** 405 406Activates the alternate setting of a USB interface. 407 408**Required permissions**: ohos.permission.ACCESS_DDK_USB 409 410**Parameters** 411 412| Name| Description| 413| -------- | -------- | 414| interfaceHandle | Interface operation handle.| 415| settingIndex | Index of the alternate setting, which corresponds to [bAlternateSetting](_usb_interface_descriptor.md#balternatesetting) in the USB protocol.| 416 417**Returns** 418 419**0** if the operation is successful; a negative value otherwise. 420 421 422### OH_Usb_SendControlReadRequest() 423 424 425``` 426int32_t OH_Usb_SendControlReadRequest (uint64_t interfaceHandle, const struct UsbControlRequestSetup * setup, uint32_t timeout, uint8_t * data, uint32_t * dataLen ) 427``` 428 429**Description** 430 431Sends a control read transfer request. This API works in a synchronous manner. 432 433**Required permissions**: ohos.permission.ACCESS_DDK_USB 434 435**Parameters** 436 437| Name| Description| 438| -------- | -------- | 439| interfaceHandle | Interface operation handle.| 440| setup | Request parameters. For details, see [UsbControlRequestSetup](_usb_control_request_setup.md).| 441| timeout | Timeout duration, in milliseconds.| 442| data | Data to be transferred.| 443| dataLen | Data length. The return value indicates the length of the actually read data.| 444 445**Returns** 446 447**0** if the operation is successful; a negative value otherwise. 448 449 450### OH_Usb_SendControlWriteRequest() 451 452 453``` 454int32_t OH_Usb_SendControlWriteRequest (uint64_t interfaceHandle, const struct UsbControlRequestSetup * setup, uint32_t timeout, const uint8_t * data, uint32_t dataLen ) 455``` 456 457**Description** 458 459Sends a control write transfer request. This API works in a synchronous manner. 460 461**Required permissions**: ohos.permission.ACCESS_DDK_USB 462 463**Parameters** 464 465| Name| Description| 466| -------- | -------- | 467| interfaceHandle | Interface operation handle.| 468| setup | Request parameters. For details, see [UsbControlRequestSetup](_usb_control_request_setup.md).| 469| timeout | Timeout duration, in milliseconds.| 470| data | Data to be transferred.| 471| dataLen | Data length.| 472 473**Returns** 474 475**0** if the operation is successful; a negative value otherwise. 476 477 478### OH_Usb_SendPipeRequest() 479 480 481``` 482int32_t OH_Usb_SendPipeRequest (const struct UsbRequestPipe * pipe, UsbDeviceMemMap * devMmap ) 483``` 484 485**Description** 486 487Sends a pipe request. This API works in a synchronous manner. It applies to interrupt transfer and bulk transfer. 488 489**Required permissions**: ohos.permission.ACCESS_DDK_USB 490 491**Parameters** 492 493| Name| Description| 494| -------- | -------- | 495| pipe | Pipe used to transfer data.| 496| devMmap | Device memory map, which can be obtained by calling [OH_Usb_CreateDeviceMemMap()](#oh_usb_createdevicememmap).| 497 498**Returns** 499 500**0** if the operation is successful; a negative value otherwise. 501