1# USB DDK 2 3 4## 概述 5 6提供USB DDK接口，包括主机侧打开和关闭接口、管道同步异步读写通信、控制传输、中断传输等。 7 8**系统能力：** SystemCapability.Driver.USB.Extension 9 10**起始版本：** 11 1210 13 14## 汇总 15 16 17### 文件 18 19| 名称 | 描述 | 20| -------- | -------- | 21| [usb_ddk_api.h](usb__ddk__api_8h.md) | 声明用于主机侧访问设备的USB DDK接口。<br/>引用文件：<usb/usb_ddk_api.h> <br/>库： libusb_ndk.z.so| 22| [usb_ddk_types.h](usb__ddk__types_8h.md) | 提供USB DDK中的枚举变量、结构体定义与宏定义。<br/>引用文件：<usb/usb_ddk_types.h> <br/>库： libusb_ndk.z.so| 23 24 25### 结构体 26 27| 名称 | 描述 | 28| -------- | -------- | 29| [UsbControlRequestSetup](_usb_control_request_setup.md) | 控制传输setup包，对应USB协议中的Setup Data。 | 30| [UsbDeviceDescriptor](_usb_device_descriptor.md) | 标准设备描述符，对应USB协议中Standard Device Descriptor。 | 31| [UsbConfigDescriptor](_usb_config_descriptor.md) | 标准配置描述符，对应USB协议中Standard Configuration Descriptor。 | 32| [UsbInterfaceDescriptor](_usb_interface_descriptor.md) | 标准接口描述符，对应USB协议中Standard Interface Descriptor。 | 33| [UsbEndpointDescriptor](_usb_endpoint_descriptor.md) | 标准端点描述符，对应USB协议中Standard Endpoint Descriptor。 | 34| [UsbDdkEndpointDescriptor](_usb_ddk_endpoint_descriptor.md) | 端点描述符。 | 35| [UsbDdkInterfaceDescriptor](_usb_ddk_interface_descriptor.md) | 接口描述符。 | 36| [UsbDdkInterface](_usb_ddk_interface.md) | USB接口，是特定接口下备用设置的集合。 | 37| [UsbDdkConfigDescriptor](_usb_ddk_config_descriptor.md) | 配置描述符。 | 38| [UsbRequestPipe](_usb_request_pipe.md) | 请求管道。 | 39| [UsbDeviceMemMap](_usb_device_mem_map.md) | 设备内存映射，通过[OH_Usb_CreateDeviceMemMap()](#oh_usb_createdevicememmap)创建设备内存映射，使用内存映射后的缓冲区，获得更好的性能。 | 40 41### 枚举 42 43| 名称 | 描述 | 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 错误码定义。 | 46 47 48### 函数 49 50| 名称 | 描述 | 51| -------- | -------- | 52| [OH_Usb_Init](#oh_usb_init) (void) | 初始化DDK。 | 53| [OH_Usb_Release](#oh_usb_release) (void) | 释放DDK。 | 54| [OH_Usb_GetDeviceDescriptor](#oh_usb_getdevicedescriptor) (uint64_t deviceId, struct [UsbDeviceDescriptor](_usb_device_descriptor.md) \*desc) | 获取设备描述符。 | 55| [OH_Usb_GetConfigDescriptor](#oh_usb_getconfigdescriptor) (uint64_t deviceId, uint8_t configIndex, struct [UsbDdkConfigDescriptor](_usb_ddk_config_descriptor.md) \*\*const config) | 获取配置描述符。请在描述符使用完后使用[OH_Usb_FreeConfigDescriptor()](#oh_usb_freeconfigdescriptor)释放描述符，否则会造成内存泄露。 | 56| [OH_Usb_FreeConfigDescriptor](#oh_usb_freeconfigdescriptor) (const struct [UsbDdkConfigDescriptor](_usb_ddk_config_descriptor.md) \*const config) | 释放配置描述符，请在描述符使用完后释放描述符，否则会造成内存泄露。 | 57| [OH_Usb_ClaimInterface](#oh_usb_claiminterface) (uint64_t deviceId, uint8_t interfaceIndex, uint64_t \*[interfaceHandle](usb__ddk__types_8h.md#interfacehandle)) | 声明接口。 | 58| [OH_Usb_ReleaseInterface](#oh_usb_releaseinterface) (uint64_t [interfaceHandle](usb__ddk__types_8h.md#interfacehandle)) | 释放接口。 | 59| [OH_Usb_SelectInterfaceSetting](#oh_usb_selectinterfacesetting) (uint64_t [interfaceHandle](usb__ddk__types_8h.md#interfacehandle), uint8_t settingIndex) | 激活接口的备用设置。 | 60| [OH_Usb_GetCurrentInterfaceSetting](#oh_usb_getcurrentinterfacesetting) (uint64_t [interfaceHandle](usb__ddk__types_8h.md#interfacehandle), uint8_t \*settingIndex) | 获取接口当前激活的备用设置。 | 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) | 发送控制读请求，该接口为同步接口。 | 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) | 发送控制写请求，该接口为同步接口。 | 63| [OH_Usb_SendPipeRequest](#oh_usb_sendpiperequest) (const struct [UsbRequestPipe](_usb_request_pipe.md) \*pipe, [UsbDeviceMemMap](_usb_device_mem_map.md) \*devMmap) | 发送管道请求，该接口为同步接口。中断传输和批量传输都使用该接口发送请求。 | 64| [OH_Usb_SendPipeRequestWithAshmem](#oh_usb_sendpiperequestwithashmem) (const struct [UsbRequestPipe](_usb_request_pipe.md) \*pipe, [DDK_Ashmem](_ddk_ashmem.md) \*ashmem) | 发送共享内存管道请求，该接口为同步接口。中断传输和批量传输都使用该接口发送请求。 | 65| [OH_Usb_CreateDeviceMemMap](#oh_usb_createdevicememmap) (uint64_t deviceId, size_t size, [UsbDeviceMemMap](_usb_device_mem_map.md) \*\*devMmap) | 创建缓冲区。请在缓冲区使用完后，调用[OH_Usb_DestroyDeviceMemMap()](#oh_usb_destroydevicememmap)销毁缓冲区，否则会造成资源泄露。 | 66| [OH_Usb_DestroyDeviceMemMap](#oh_usb_destroydevicememmap) ([UsbDeviceMemMap](_usb_device_mem_map.md) \*devMmap) | 销毁缓冲区。请在缓冲区使用完后及时销毁缓冲区，否则会造成资源泄露。 | 67 68#### 函数参数deviceId说明 69 70设备ID（deviceId）的获取可通过外设查询接口queryDevices()查询。 71具体请查阅[扩展外设管理开发指导](../../device/driver/externaldevice-guidelines.md)。 72 73#### 函数参数deviceId转换指导 74 75通过外设查询接口queryDevices()获取到的deviceId，还需要通过数据转换，才能得到[OH_Usb_GetDeviceDescriptor](#oh_usb_getdevicedescriptor) 等函数的入参deviceId。 76<p>转换原理：提取queryDevices()获取到的deviceId的前32位作为C_API的deviceId。</p> 77<p>以下代码仅供参考：</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## 枚举类型说明 89 90 91### UsbDdkErrCode 92 93 94``` 95enum UsbDdkErrCode 96``` 97 98**描述:** 99 100USB DDK 错误码定义。 101 102| 枚举值 | 描述 | 103| -------- | -------- | 104| USB_DDK_SUCCESS | 操作成功。 | 105| USB_DDK_FAILED | 操作失败。 | 106| USB_DDK_INVALID_PARAMETER | 非法参数。 | 107| USB_DDK_MEMORY_ERROR | 内存相关的错误，包括：内存不足、内存数据拷贝失败、内存申请失败等。 | 108| USB_DDK_INVALID_OPERATION | 非法操作。 | 109| USB_DDK_NULL_PTR | 空指针异常。 | 110| USB_DDK_DEVICE_BUSY | 设备忙。 | 111| USB_DDK_TIMEOUT | 传输超时。 | 112 113 114## 函数说明 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**描述:** 125 126声明接口。 127 128**需要权限**：ohos.permission.ACCESS_DDK_USB 129 130**参数:** 131 132| 名称 | 描述 | 133| -------- | -------- | 134| deviceId | 设备ID，代表要操作的设备。 | 135| interfaceIndex | 接口索引，对应USB协议中的[bInterfaceNumber](_usb_interface_descriptor.md#binterfacenumber)。 | 136| interfaceHandle | 接口操作句柄，接口声明成功后，该参数将会被赋值。 | 137 138**返回:** 139 140- [USB_DDK_SUCCESS](#usbddkerrcode)：表示调用接口成功。 141- [USB_DDK_FAILED](#usbddkerrcode)：表示权限校验失败或者内部错误失败。 142- [USB_DDK_INVALID_OPERATION](#usbddkerrcode)：表示连接usb_ddk服务失败。 143- [USB_DDK_INVALID_PARAMETER](#usbddkerrcode)：表示入参interfaceHandle为空指针。 144 145 146### OH_Usb_CreateDeviceMemMap() 147 148 149``` 150int32_t OH_Usb_CreateDeviceMemMap (uint64_t deviceId, size_t size, UsbDeviceMemMap ** devMmap ) 151``` 152 153**描述:** 154 155创建缓冲区。请在缓冲区使用完后，调用[OH_Usb_DestroyDeviceMemMap()](#oh_usb_destroydevicememmap)销毁缓冲区，否则会造成资源泄露。 156 157**需要权限**：ohos.permission.ACCESS_DDK_USB 158 159**参数:** 160 161| 名称 | 描述 | 162| -------- | -------- | 163| deviceId | 设备ID，代表要创建缓冲区的设备。 | 164| size | 缓冲区的大小。 | 165| devMmap | 创建的缓冲区通过该参数返回给调用者。 | 166 167**返回:** 168 169- [USB_DDK_SUCCESS](#usbddkerrcode)：表示调用接口成功。 170- [USB_DDK_FAILED](#usbddkerrcode)：表示权限校验失败或者内部错误失败。 171- [USB_DDK_INVALID_PARAMETER](#usbddkerrcode)：表示入参devMmap为空指针。 172- [USB_DDK_MEMORY_ERROR](#usbddkerrcode)：表示mmap失败或者申请devMmap的内存空间失败。 173 174 175### OH_Usb_DestroyDeviceMemMap() 176 177 178``` 179void OH_Usb_DestroyDeviceMemMap (UsbDeviceMemMap * devMmap) 180``` 181 182**描述:** 183 184销毁缓冲区。请在缓冲区使用完后及时销毁缓冲区，否则会造成资源泄露。 185 186**需要权限**：ohos.permission.ACCESS_DDK_USB 187 188**参数:** 189 190| 名称 | 描述 | 191| -------- | -------- | 192| devMmap | 销毁由[OH_Usb_CreateDeviceMemMap()](#oh_usb_createdevicememmap)创建的缓冲区。 | 193 194 195### OH_Usb_FreeConfigDescriptor() 196 197 198``` 199void OH_Usb_FreeConfigDescriptor (struct UsbDdkConfigDescriptor *const config) 200``` 201 202**描述:** 203 204释放配置描述符，请在描述符使用完后释放描述符，否则会造成内存泄露。 205 206**需要权限**：ohos.permission.ACCESS_DDK_USB 207 208**参数:** 209 210| 名称 | 描述 | 211| -------- | -------- | 212| config | 配置描述符，通过[OH_Usb_GetConfigDescriptor()](#oh_usb_getconfigdescriptor)获得的配置描述符。 | 213 214 215### OH_Usb_GetConfigDescriptor() 216 217 218``` 219int32_t OH_Usb_GetConfigDescriptor (uint64_t deviceId, uint8_t configIndex, struct UsbDdkConfigDescriptor **const config ) 220``` 221 222**描述:** 223 224获取配置描述符。请在描述符使用完后使用[OH_Usb_FreeConfigDescriptor()](#oh_usb_freeconfigdescriptor)释放描述符，否则会造成内存泄露。 225 226**需要权限**：ohos.permission.ACCESS_DDK_USB 227 228**参数:** 229 230| 名称 | 描述 | 231| -------- | -------- | 232| deviceId | 设备ID，代表要获取配置描述符的设备。 | 233| configIndex | 配置id，对应USB协议中的[bConfigurationValue](_usb_config_descriptor.md#bconfigurationvalue)。 | 234| config | 配置描述符，包含USB协议中定义的标准配置描述符，以及与其关联的接口描述符和端点描述符。 | 235 236**返回:** 237 238- [USB_DDK_SUCCESS](#usbddkerrcode)：表示调用接口成功。 239- [USB_DDK_FAILED](#usbddkerrcode)：表示权限校验失败或者内部错误失败。 240- [USB_DDK_INVALID_OPERATION](#usbddkerrcode)：表示连接usb_ddk服务失败。 241- [USB_DDK_INVALID_PARAMETER](#usbddkerrcode)：表示入参config为空指针。 242 243 244### OH_Usb_GetCurrentInterfaceSetting() 245 246 247``` 248int32_t OH_Usb_GetCurrentInterfaceSetting (uint64_t interfaceHandle, uint8_t * settingIndex ) 249``` 250 251**描述:** 252 253获取接口当前激活的备用设置。 254 255**需要权限**：ohos.permission.ACCESS_DDK_USB 256 257**参数:** 258 259| 名称 | 描述 | 260| -------- | -------- | 261| interfaceHandle | 接口操作句柄，代表要操作的接口。 | 262| settingIndex | 备用设置索引，对应USB协议中的[bAlternateSetting](_usb_interface_descriptor.md#balternatesetting)。 | 263 264**返回:** 265 266- [USB_DDK_SUCCESS](#usbddkerrcode)：表示调用接口成功。 267- [USB_DDK_FAILED](#usbddkerrcode)：表示权限校验失败或者内部错误失败。 268- [USB_DDK_INVALID_OPERATION](#usbddkerrcode)：表示连接usb_ddk服务失败。 269- [USB_DDK_INVALID_PARAMETER](#usbddkerrcode)：表示入参settingIndex为空指针。 270 271 272### OH_Usb_GetDeviceDescriptor() 273 274 275``` 276int32_t OH_Usb_GetDeviceDescriptor (uint64_t deviceId, struct UsbDeviceDescriptor * desc ) 277``` 278 279**描述:** 280 281获取设备描述符。 282 283**需要权限**：ohos.permission.ACCESS_DDK_USB 284 285**参数:** 286 287| 名称 | 描述 | 288| -------- | -------- | 289| deviceId | 设备ID，代表要获取描述符的设备。 | 290| desc | 设备描述符，详细定义请参考[UsbDeviceDescriptor](_usb_device_descriptor.md)。 | 291 292**返回:** 293 294- [USB_DDK_SUCCESS](#usbddkerrcode)：表示调用接口成功。 295- [USB_DDK_FAILED](#usbddkerrcode)：表示权限校验失败或者内部错误失败。 296- [USB_DDK_INVALID_OPERATION](#usbddkerrcode)：表示连接usb_ddk服务失败。 297- [USB_DDK_INVALID_PARAMETER](#usbddkerrcode)：表示入参desc为空指针。 298 299### OH_Usb_Init() 300 301 302``` 303int32_t OH_Usb_Init (void ) 304``` 305 306**描述:** 307 308初始化DDK。 309 310**需要权限**：ohos.permission.ACCESS_DDK_USB 311 312**返回:** 313 314- [USB_DDK_SUCCESS](#usbddkerrcode)：表示调用接口成功。 315- [USB_DDK_FAILED](#usbddkerrcode)：表示权限校验失败、连接usb_ddk服务失败或者内部错误失败。 316 317### OH_Usb_Release() 318 319 320``` 321void OH_Usb_Release (void ) 322``` 323 324**描述:** 325 326释放DDK。 327 328**需要权限**：ohos.permission.ACCESS_DDK_USB 329 330 331### OH_Usb_ReleaseInterface() 332 333 334``` 335int32_t OH_Usb_ReleaseInterface (uint64_t interfaceHandle) 336``` 337 338**描述:** 339 340释放接口。 341 342**需要权限**：ohos.permission.ACCESS_DDK_USB 343 344**参数:** 345 346| 名称 | 描述 | 347| -------- | -------- | 348| interfaceHandle | 接口操作句柄，代表要释放的接口。 | 349 350**返回:** 351 352- [USB_DDK_SUCCESS](#usbddkerrcode)：表示调用接口成功。 353- [USB_DDK_FAILED](#usbddkerrcode)：表示权限校验失败或者内部错误失败。 354- [USB_DDK_INVALID_OPERATION](#usbddkerrcode)：表示连接usb_ddk服务失败。 355 356 357### OH_Usb_SelectInterfaceSetting() 358 359 360``` 361int32_t OH_Usb_SelectInterfaceSetting (uint64_t interfaceHandle, uint8_t settingIndex ) 362``` 363 364**描述:** 365 366激活接口的备用设置。 367 368**需要权限**：ohos.permission.ACCESS_DDK_USB 369 370**参数:** 371 372| 名称 | 描述 | 373| -------- | -------- | 374| interfaceHandle | 接口操作句柄，代表要操作的接口。 | 375| settingIndex | 备用设置索引，对应USB协议中的[bAlternateSetting](_usb_interface_descriptor.md#balternatesetting)。 | 376 377**返回:** 378 379- [USB_DDK_SUCCESS](#usbddkerrcode)：表示调用接口成功。 380- [USB_DDK_FAILED](#usbddkerrcode)：表示权限校验失败或者内部错误失败。 381- [USB_DDK_INVALID_OPERATION](#usbddkerrcode)：表示连接usb_ddk服务失败。 382 383 384### OH_Usb_SendControlReadRequest() 385 386 387``` 388int32_t OH_Usb_SendControlReadRequest (uint64_t interfaceHandle, const struct UsbControlRequestSetup * setup, uint32_t timeout, uint8_t * data, uint32_t * dataLen ) 389``` 390 391**描述:** 392 393发送控制读请求，该接口为同步接口。 394 395**需要权限**：ohos.permission.ACCESS_DDK_USB 396 397**参数:** 398 399| 名称 | 描述 | 400| -------- | -------- | 401| interfaceHandle | 接口操作句柄，代表要操作的接口。 | 402| setup | 请求相关的参数，详细定义请参考 [UsbControlRequestSetup](_usb_control_request_setup.md)。 | 403| timeout | 超时时间，单位为毫秒。 | 404| data | 要传输的数据。 | 405| dataLen | 表示data的数据长度，在函数返回后，表示实际读取到的数据的长度。 | 406 407**返回:** 408 409- [USB_DDK_SUCCESS](#usbddkerrcode)：表示调用接口成功。 410- [USB_DDK_FAILED](#usbddkerrcode)：表示权限校验失败或者内部错误失败。 411- [USB_DDK_INVALID_OPERATION](#usbddkerrcode)：表示连接usb_ddk服务失败。 412- [USB_DDK_INVALID_PARAMETER](#usbddkerrcode)：表示入参setup、data或者dataLen为空指针，亦或datalen小于读取到的数据长度。 413- [USB_DDK_MEMORY_ERROR](#usbddkerrcode)：表示拷贝读取数据的内存失败。 414 415 416### OH_Usb_SendControlWriteRequest() 417 418 419``` 420int32_t OH_Usb_SendControlWriteRequest (uint64_t interfaceHandle, const struct UsbControlRequestSetup * setup, uint32_t timeout, const uint8_t * data, uint32_t dataLen ) 421``` 422 423**描述:** 424 425发送控制写请求，该接口为同步接口。 426 427**需要权限**：ohos.permission.ACCESS_DDK_USB 428 429**参数:** 430 431| 名称 | 描述 | 432| -------- | -------- | 433| interfaceHandle | 接口操作句柄，代表要操作的接口。 | 434| setup | 请求相关的参数，详细定义请参考 [UsbControlRequestSetup](_usb_control_request_setup.md)。 | 435| timeout | 超时时间，单位为毫秒。 | 436| data | 要传输的数据。 | 437| dataLen | 表示data的数据长度。 | 438 439**返回:** 440 441- [USB_DDK_SUCCESS](#usbddkerrcode)：表示调用接口成功。 442- [USB_DDK_FAILED](#usbddkerrcode)：表示权限校验失败或者内部错误失败。 443- [USB_DDK_INVALID_OPERATION](#usbddkerrcode)：表示连接usb_ddk服务失败。 444- [USB_DDK_INVALID_PARAMETER](#usbddkerrcode)：表示入参setup或者data为空指针。 445 446 447### OH_Usb_SendPipeRequest() 448 449 450``` 451int32_t OH_Usb_SendPipeRequest (const struct UsbRequestPipe * pipe, UsbDeviceMemMap * devMmap ) 452``` 453 454**描述:** 455 456发送管道请求，该接口为同步接口。中断传输和批量传输都使用该接口发送请求。 457 458**需要权限**：ohos.permission.ACCESS_DDK_USB 459 460**参数:** 461 462| 名称 | 描述 | 463| -------- | -------- | 464| pipe | 要传输数据的管道信息。 | 465| devMmap | 数据缓冲区，可以通过[OH_Usb_CreateDeviceMemMap()](#oh_usb_createdevicememmap)获得。 | 466 467**返回:** 468 469- [USB_DDK_SUCCESS](#usbddkerrcode)：表示调用接口成功。 470- [USB_DDK_FAILED](#usbddkerrcode)：表示权限校验失败或者内部错误失败。 471- [USB_DDK_INVALID_OPERATION](#usbddkerrcode)：表示连接usb_ddk服务失败。 472- [USB_DDK_INVALID_PARAMETER](#usbddkerrcode)：表示入参pipe、devMmap或者devMmap的地址为空指针。 473 474 475### OH_Usb_SendPipeRequestWithAshmem() 476 477 478``` 479int32_t OH_Usb_SendPipeRequestWithAshmem(const struct UsbRequestPipe *pipe, DDK_Ashmem *ashmem); 480``` 481 482**描述:** 483 484发送共享内存的管道请求，该接口为同步接口。中断传输和批量传输都使用该接口发送请求。 485 486**需要权限**：ohos.permission.ACCESS_DDK_USB 487 488**参数:** 489 490| 名称 | 描述 | 491| -------- | -------- | 492| pipe | 要传输数据的管道信息。 | 493| ashmem | 共享内存，可以通过[OH_DDK_CreateAshmem()](_base_ddk.md#oh_ddk_createashmem)获得。 | 494 495**返回:** 496 497- [USB_DDK_SUCCESS](#usbddkerrcode)：表示调用接口成功。 498- [USB_DDK_FAILED](#usbddkerrcode)：表示权限校验失败或者内部错误失败。 499- [USB_DDK_INVALID_OPERATION](#usbddkerrcode)：表示连接usb_ddk服务失败。 500- [USB_DDK_INVALID_PARAMETER](#usbddkerrcode)：表示入参pipe、ashmem或者ashmem的地址为空指针。 501 502