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