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