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| [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 错误码定义。 | 47 48 49### 函数 50 51| 名称 | 描述 | 52| -------- | -------- | 53| [OH_Usb_Init](#oh_usb_init) (void) | 初始化DDK。 | 54| [OH_Usb_Release](#oh_usb_release) (void) | 释放DDK。 | 55| [OH_Usb_GetDeviceDescriptor](#oh_usb_getdevicedescriptor) (uint64_t deviceId, struct [UsbDeviceDescriptor](_usb_device_descriptor.md) \*desc) | 获取设备描述符。 | 56| [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)释放描述符，否则会造成内存泄露。 | 57| [OH_Usb_FreeConfigDescriptor](#oh_usb_freeconfigdescriptor) (const struct [UsbDdkConfigDescriptor](_usb_ddk_config_descriptor.md) \*const config) | 释放配置描述符，请在描述符使用完后释放描述符，否则会造成内存泄露。 | 58| [OH_Usb_ClaimInterface](#oh_usb_claiminterface) (uint64_t deviceId, uint8_t interfaceIndex, uint64_t \*[interfaceHandle](usb__ddk__types_8h.md#interfacehandle)) | 声明接口。 | 59| [OH_Usb_ReleaseInterface](#oh_usb_releaseinterface) (uint64_t [interfaceHandle](usb__ddk__types_8h.md#interfacehandle)) | 释放接口。 | 60| [OH_Usb_SelectInterfaceSetting](#oh_usb_selectinterfacesetting) (uint64_t [interfaceHandle](usb__ddk__types_8h.md#interfacehandle), uint8_t settingIndex) | 激活接口的备用设置。 | 61| [OH_Usb_GetCurrentInterfaceSetting](#oh_usb_getcurrentinterfacesetting) (uint64_t [interfaceHandle](usb__ddk__types_8h.md#interfacehandle), uint8_t \*settingIndex) | 获取接口当前激活的备用设置。 | 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) | 发送控制读请求，该接口为同步接口。 | 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) | 发送控制写请求，该接口为同步接口。 | 64| [OH_Usb_SendPipeRequest](#oh_usb_sendpiperequest) (const struct [UsbRequestPipe](_usb_request_pipe.md) \*pipe, [UsbDeviceMemMap](_usb_device_mem_map.md) \*devMmap) | 发送管道请求，该接口为同步接口。中断传输和批量传输都使用该接口发送请求。 | 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/externaldevice-guidelines.md)。 72 73## 枚举类型说明 74 75 76### UsbDdkErrCode 77 78 79``` 80enum UsbDdkErrCode 81``` 82 83**描述:** 84 85USB DDK 错误码定义。 86 87| 枚举值 | 描述 | 88| -------- | -------- | 89| USB_DDK_SUCCESS | 操作成功。 | 90| USB_DDK_FAILED | 操作失败。 | 91| USB_DDK_INVALID_PARAMETER | 非法参数。 | 92| USB_DDK_MEMORY_ERROR | 内存相关的错误，包括：内存不足、内存数据拷贝失败、内存申请失败等。 | 93| USB_DDK_INVALID_OPERATION | 非法操作。 | 94| USB_DDK_NULL_PTR | 空指针异常。 | 95| USB_DDK_DEVICE_BUSY | 设备忙。 | 96| USB_DDK_TIMEOUT | 传输超时。 | 97 98 99## 函数说明 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**描述:** 110 111声明接口。 112 113**需要权限**：ohos.permission.ACCESS_DDK_USB 114 115**参数:** 116 117| 名称 | 描述 | 118| -------- | -------- | 119| deviceId | 设备ID，代表要操作的设备。 | 120| interfaceIndex | 接口索引，对应USB协议中的[bInterfaceNumber](_usb_interface_descriptor.md#binterfacenumber)。 | 121| interfaceHandle | 接口操作句柄，接口声明成功后，该参数将会被赋值。 | 122 123**返回:** 124 125成功返回0，否则返回负数。 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**描述:** 136 137创建缓冲区。请在缓冲区使用完后，调用[OH_Usb_DestroyDeviceMemMap()](#oh_usb_destroydevicememmap)销毁缓冲区，否则会造成资源泄露。 138 139**需要权限**：ohos.permission.ACCESS_DDK_USB 140 141**参数:** 142 143| 名称 | 描述 | 144| -------- | -------- | 145| deviceId | 设备ID，代表要创建缓冲区的设备。 | 146| size | 缓冲区的大小。 | 147| devMmap | 创建的缓冲区通过该参数返回给调用者。 | 148 149**返回:** 150 151成功返回0，否则返回负数。 152 153 154### OH_Usb_DestroyDeviceMemMap() 155 156 157``` 158void OH_Usb_DestroyDeviceMemMap (UsbDeviceMemMap * devMmap) 159``` 160 161**描述:** 162 163销毁缓冲区。请在缓冲区使用完后及时销毁缓冲区，否则会造成资源泄露。 164 165**需要权限**：ohos.permission.ACCESS_DDK_USB 166 167**参数:** 168 169| 名称 | 描述 | 170| -------- | -------- | 171| devMmap | 销毁由[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**描述:** 182 183释放配置描述符，请在描述符使用完后释放描述符，否则会造成内存泄露。 184 185**需要权限**：ohos.permission.ACCESS_DDK_USB 186 187**参数:** 188 189| 名称 | 描述 | 190| -------- | -------- | 191| config | 配置描述符，通过[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**描述:** 202 203获取配置描述符。请在描述符使用完后使用[OH_Usb_FreeConfigDescriptor()](#oh_usb_freeconfigdescriptor)释放描述符，否则会造成内存泄露。 204 205**需要权限**：ohos.permission.ACCESS_DDK_USB 206 207**参数:** 208 209| 名称 | 描述 | 210| -------- | -------- | 211| deviceId | 设备ID，代表要获取配置描述符的设备。 | 212| configIndex | 配置id，对应USB协议中的[bConfigurationValue](_usb_config_descriptor.md#bconfigurationvalue)。 | 213| config | 配置描述符，包含USB协议中定义的标准配置描述符，以及与其关联的接口描述符和端点描述符。 | 214 215**返回:** 216 217成功返回0，否则返回负数。 218 219 220### OH_Usb_GetCurrentInterfaceSetting() 221 222 223``` 224int32_t OH_Usb_GetCurrentInterfaceSetting (uint64_t interfaceHandle, uint8_t * settingIndex ) 225``` 226 227**描述:** 228 229获取接口当前激活的备用设置。 230 231**需要权限**：ohos.permission.ACCESS_DDK_USB 232 233**参数:** 234 235| 名称 | 描述 | 236| -------- | -------- | 237| interfaceHandle | 接口操作句柄，代表要操作的接口。 | 238| settingIndex | 备用设置索引，对应USB协议中的[bAlternateSetting](_usb_interface_descriptor.md#balternatesetting)。 | 239 240**返回:** 241 242成功返回0，否则返回负数。 243 244 245### OH_Usb_GetDeviceDescriptor() 246 247 248``` 249int32_t OH_Usb_GetDeviceDescriptor (uint64_t deviceId, struct UsbDeviceDescriptor * desc ) 250``` 251 252**描述:** 253 254获取设备描述符。 255 256**需要权限**：ohos.permission.ACCESS_DDK_USB 257 258**参数:** 259 260| 名称 | 描述 | 261| -------- | -------- | 262| deviceId | 设备ID，代表要获取描述符的设备。 | 263| desc | 设备描述符，详细定义请参考[UsbDeviceDescriptor](_usb_device_descriptor.md)。 | 264 265**返回:** 266 267成功返回0，否则返回负数。 268 269 270### OH_Usb_Init() 271 272 273``` 274int32_t OH_Usb_Init (void ) 275``` 276 277**描述:** 278 279初始化DDK。 280 281**需要权限**：ohos.permission.ACCESS_DDK_USB 282 283**返回:** 284 285成功返回0，否则返回负数。 286 287 288### OH_Usb_Release() 289 290 291``` 292void OH_Usb_Release (void ) 293``` 294 295**描述:** 296 297释放DDK。 298 299**需要权限**：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**描述:** 310 311释放接口。 312 313**需要权限**：ohos.permission.ACCESS_DDK_USB 314 315**参数:** 316 317| 名称 | 描述 | 318| -------- | -------- | 319| interfaceHandle | 接口操作句柄，代表要释放的接口。 | 320 321**返回:** 322 323成功返回0，否则返回负数。 324 325 326### OH_Usb_SelectInterfaceSetting() 327 328 329``` 330int32_t OH_Usb_SelectInterfaceSetting (uint64_t interfaceHandle, uint8_t settingIndex ) 331``` 332 333**描述:** 334 335激活接口的备用设置。 336 337**需要权限**：ohos.permission.ACCESS_DDK_USB 338 339**参数:** 340 341| 名称 | 描述 | 342| -------- | -------- | 343| interfaceHandle | 接口操作句柄，代表要操作的接口。 | 344| settingIndex | 备用设置索引，对应USB协议中的[bAlternateSetting](_usb_interface_descriptor.md#balternatesetting)。 | 345 346**返回:** 347 348成功返回0，否则返回负数。 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**描述:** 359 360发送控制读请求，该接口为同步接口。 361 362**需要权限**：ohos.permission.ACCESS_DDK_USB 363 364**参数:** 365 366| 名称 | 描述 | 367| -------- | -------- | 368| interfaceHandle | 接口操作句柄，代表要操作的接口。 | 369| setup | 请求相关的参数，详细定义请参考 [UsbControlRequestSetup](_usb_control_request_setup.md)。 | 370| timeout | 超时时间，单位为毫秒。 | 371| data | 要传输的数据。 | 372| dataLen | 表示data的数据长度，在函数返回后，表示实际读取到的数据的长度。 | 373 374**返回:** 375 376成功返回0，否则返回负数。 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**描述:** 387 388发送控制写请求，该接口为同步接口。 389 390**需要权限**：ohos.permission.ACCESS_DDK_USB 391 392**参数:** 393 394| 名称 | 描述 | 395| -------- | -------- | 396| interfaceHandle | 接口操作句柄，代表要操作的接口。 | 397| setup | 请求相关的参数，详细定义请参考 [UsbControlRequestSetup](_usb_control_request_setup.md)。 | 398| timeout | 超时时间，单位为毫秒。 | 399| data | 要传输的数据。 | 400| dataLen | 表示data的数据长度。 | 401 402**返回:** 403 404成功返回0，否则返回负数。 405 406 407### OH_Usb_SendPipeRequest() 408 409 410``` 411int32_t OH_Usb_SendPipeRequest (const struct UsbRequestPipe * pipe, UsbDeviceMemMap * devMmap ) 412``` 413 414**描述:** 415 416发送管道请求，该接口为同步接口。中断传输和批量传输都使用该接口发送请求。 417 418**需要权限**：ohos.permission.ACCESS_DDK_USB 419 420**参数:** 421 422| 名称 | 描述 | 423| -------- | -------- | 424| pipe | 要传输数据的管道信息。 | 425| devMmap | 数据缓冲区，可以通过[OH_Usb_CreateDeviceMemMap()](#oh_usb_createdevicememmap)获得。 | 426 427**返回:** 428 429成功返回0，否则返回负数。 430