USB DDK
概述
提供USB DDK接口，包括主机侧打开和关闭接口、管道同步异步读写通信、控制传输、中断传输等。
系统能力： SystemCapability.Driver.USB.Extension
起始版本：
10
汇总
文件
| 名称 | 描述 |
|---|---|
| usb_ddk_api.h | 声明用于主机侧访问设备的USB DDK接口。 引用文件：<usb/usb_ddk_api.h> 库： libusb_ndk.z.so |
| usb_ddk_types.h | 提供USB DDK中的枚举变量、结构体定义与宏定义。 引用文件：<usb/usb_ddk_types.h> 库： libusb_ndk.z.so |
结构体
| 名称 | 描述 |
|---|---|
| UsbControlRequestSetup | 控制传输setup包，对应USB协议中的Setup Data。 |
| UsbDeviceDescriptor | 标准设备描述符，对应USB协议中Standard Device Descriptor。 |
| UsbConfigDescriptor | 标准配置描述符，对应USB协议中Standard Configuration Descriptor。 |
| UsbInterfaceDescriptor | 标准接口描述符，对应USB协议中Standard Interface Descriptor。 |
| UsbEndpointDescriptor | 标准端点描述符，对应USB协议中Standard Endpoint Descriptor。 |
| UsbDdkEndpointDescriptor | 端点描述符。 |
| UsbDdkInterfaceDescriptor | 接口描述符。 |
| UsbDdkInterface | USB接口，是特定接口下备用设置的集合。 |
| UsbDdkConfigDescriptor | 配置描述符。 |
| UsbRequestPipe | 请求管道。 |
| UsbDeviceMemMap | 设备内存映射，通过OH_Usb_CreateDeviceMemMap()创建设备内存映射，使用内存映射后的缓冲区，获得更好的性能。 |
枚举
| 名称 | 描述 |
|---|---|
| UsbDdkErrCode { USB_DDK_SUCCESS = 0, USB_DDK_FAILED = -1, USB_DDK_INVALID_PARAMETER = -2, USB_DDK_MEMORY_ERROR = -3, USB_DDK_INVALID_OPERATION = -4, USB_DDK_NULL_PTR = -5, USB_DDK_DEVICE_BUSY = -6, USB_DDK_TIMEOUT = -7 } |
USB DDK 错误码定义。 |
函数
| 名称 | 描述 |
|---|---|
| OH_Usb_Init (void) | 初始化DDK。 |
| OH_Usb_Release (void) | 释放DDK。 |
| OH_Usb_GetDeviceDescriptor (uint64_t deviceId, struct UsbDeviceDescriptor *desc) | 获取设备描述符。 |
| OH_Usb_GetConfigDescriptor (uint64_t deviceId, uint8_t configIndex, struct UsbDdkConfigDescriptor **const config) | 获取配置描述符。请在描述符使用完后使用OH_Usb_FreeConfigDescriptor()释放描述符，否则会造成内存泄露。 |
| OH_Usb_FreeConfigDescriptor (const struct UsbDdkConfigDescriptor *const config) | 释放配置描述符，请在描述符使用完后释放描述符，否则会造成内存泄露。 |
| OH_Usb_ClaimInterface (uint64_t deviceId, uint8_t interfaceIndex, uint64_t *interfaceHandle) | 声明接口。 |
| OH_Usb_ReleaseInterface (uint64_t interfaceHandle) | 释放接口。 |
| OH_Usb_SelectInterfaceSetting (uint64_t interfaceHandle, uint8_t settingIndex) | 激活接口的备用设置。 |
| OH_Usb_GetCurrentInterfaceSetting (uint64_t interfaceHandle, uint8_t *settingIndex) | 获取接口当前激活的备用设置。 |
| OH_Usb_SendControlReadRequest (uint64_t interfaceHandle, const struct UsbControlRequestSetup *setup, uint32_t timeout, uint8_t *data, uint32_t *dataLen) | 发送控制读请求，该接口为同步接口。 |
| OH_Usb_SendControlWriteRequest (uint64_t interfaceHandle, const struct UsbControlRequestSetup *setup, uint32_t timeout, const uint8_t *data, uint32_t dataLen) | 发送控制写请求，该接口为同步接口。 |
| OH_Usb_SendPipeRequest (const struct UsbRequestPipe *pipe, UsbDeviceMemMap *devMmap) | 发送管道请求，该接口为同步接口。中断传输和批量传输都使用该接口发送请求。 |
| OH_Usb_CreateDeviceMemMap (uint64_t deviceId, size_t size, UsbDeviceMemMap **devMmap) | 创建缓冲区。请在缓冲区使用完后，调用OH_Usb_DestroyDeviceMemMap()销毁缓冲区，否则会造成资源泄露。 |
| OH_Usb_DestroyDeviceMemMap (UsbDeviceMemMap *devMmap) | 销毁缓冲区。请在缓冲区使用完后及时销毁缓冲区，否则会造成资源泄露。 |
函数参数deviceId说明
设备ID（deviceId）的获取可通过外设查询接口queryDevices()查询。 具体请查阅扩展外设管理开发指导。
函数参数deviceId转换指导
通过外设查询接口queryDevices()获取到的deviceId，还需要通过数据转换，才能得到OH_Usb_GetDeviceDescriptor 等函数的入参deviceId。
转换原理：提取queryDevices()获取到的deviceId的前32位作为C_API的deviceId。
以下代码仅供参考：
uint64_t JsDeviceIdToNative(uint64_t deviceId)
{
uint32_t busNum = (uint32_t)(deviceId >> 48);
uint32_t devNum = (uint32_t)((deviceId & 0x0000FFFF00000000) >> 32);
return (((static_cast<uint64_t>(busNum)) << 32) | devNum);
}
枚举类型说明
UsbDdkErrCode
enum UsbDdkErrCode
描述:
USB DDK 错误码定义。
| 枚举值 | 描述 |
|---|---|
| USB_DDK_SUCCESS | 操作成功。 |
| USB_DDK_FAILED | 操作失败。 |
| USB_DDK_INVALID_PARAMETER | 非法参数。 |
| USB_DDK_MEMORY_ERROR | 内存相关的错误，包括：内存不足、内存数据拷贝失败、内存申请失败等。 |
| USB_DDK_INVALID_OPERATION | 非法操作。 |
| USB_DDK_NULL_PTR | 空指针异常。 |
| USB_DDK_DEVICE_BUSY | 设备忙。 |
| USB_DDK_TIMEOUT | 传输超时。 |
函数说明
OH_Usb_ClaimInterface()
int32_t OH_Usb_ClaimInterface (uint64_t deviceId, uint8_t interfaceIndex, uint64_t * interfaceHandle )
描述:
声明接口。
需要权限：ohos.permission.ACCESS_DDK_USB
参数:
| 名称 | 描述 |
|---|---|
| deviceId | 设备ID，代表要操作的设备。 |
| interfaceIndex | 接口索引，对应USB协议中的bInterfaceNumber。 |
| interfaceHandle | 接口操作句柄，接口声明成功后，该参数将会被赋值。 |
返回:
成功返回0，否则返回负数。
OH_Usb_CreateDeviceMemMap()
int32_t OH_Usb_CreateDeviceMemMap (uint64_t deviceId, size_t size, UsbDeviceMemMap ** devMmap )
描述:
创建缓冲区。请在缓冲区使用完后，调用OH_Usb_DestroyDeviceMemMap()销毁缓冲区，否则会造成资源泄露。
需要权限：ohos.permission.ACCESS_DDK_USB
参数:
| 名称 | 描述 |
|---|---|
| deviceId | 设备ID，代表要创建缓冲区的设备。 |
| size | 缓冲区的大小。 |
| devMmap | 创建的缓冲区通过该参数返回给调用者。 |
返回:
成功返回0，否则返回负数。
OH_Usb_DestroyDeviceMemMap()
void OH_Usb_DestroyDeviceMemMap (UsbDeviceMemMap * devMmap)
描述:
销毁缓冲区。请在缓冲区使用完后及时销毁缓冲区，否则会造成资源泄露。
需要权限：ohos.permission.ACCESS_DDK_USB
参数:
| 名称 | 描述 |
|---|---|
| devMmap | 销毁由OH_Usb_CreateDeviceMemMap()创建的缓冲区。 |
OH_Usb_FreeConfigDescriptor()
void OH_Usb_FreeConfigDescriptor (struct UsbDdkConfigDescriptor *const config)
描述:
释放配置描述符，请在描述符使用完后释放描述符，否则会造成内存泄露。
需要权限：ohos.permission.ACCESS_DDK_USB
参数:
| 名称 | 描述 |
|---|---|
| config | 配置描述符，通过OH_Usb_GetConfigDescriptor()获得的配置描述符。 |
OH_Usb_GetConfigDescriptor()
int32_t OH_Usb_GetConfigDescriptor (uint64_t deviceId, uint8_t configIndex, struct UsbDdkConfigDescriptor **const config )
描述:
获取配置描述符。请在描述符使用完后使用OH_Usb_FreeConfigDescriptor()释放描述符，否则会造成内存泄露。
需要权限：ohos.permission.ACCESS_DDK_USB
参数:
| 名称 | 描述 |
|---|---|
| deviceId | 设备ID，代表要获取配置描述符的设备。 |
| configIndex | 配置id，对应USB协议中的bConfigurationValue。 |
| config | 配置描述符，包含USB协议中定义的标准配置描述符，以及与其关联的接口描述符和端点描述符。 |
返回:
成功返回0，否则返回负数。
OH_Usb_GetCurrentInterfaceSetting()
int32_t OH_Usb_GetCurrentInterfaceSetting (uint64_t interfaceHandle, uint8_t * settingIndex )
描述:
获取接口当前激活的备用设置。
需要权限：ohos.permission.ACCESS_DDK_USB
参数:
| 名称 | 描述 |
|---|---|
| interfaceHandle | 接口操作句柄，代表要操作的接口。 |
| settingIndex | 备用设置索引，对应USB协议中的bAlternateSetting。 |
返回:
成功返回0，否则返回负数。
OH_Usb_GetDeviceDescriptor()
int32_t OH_Usb_GetDeviceDescriptor (uint64_t deviceId, struct UsbDeviceDescriptor * desc )
描述:
获取设备描述符。
需要权限：ohos.permission.ACCESS_DDK_USB
参数:
| 名称 | 描述 |
|---|---|
| deviceId | 设备ID，代表要获取描述符的设备。 |
| desc | 设备描述符，详细定义请参考UsbDeviceDescriptor。 |
返回:
成功返回0，否则返回负数。
OH_Usb_Init()
int32_t OH_Usb_Init (void )
描述:
初始化DDK。
需要权限：ohos.permission.ACCESS_DDK_USB
返回:
成功返回0，否则返回负数。
OH_Usb_Release()
void OH_Usb_Release (void )
描述:
释放DDK。
需要权限：ohos.permission.ACCESS_DDK_USB
OH_Usb_ReleaseInterface()
int32_t OH_Usb_ReleaseInterface (uint64_t interfaceHandle)
描述:
释放接口。
需要权限：ohos.permission.ACCESS_DDK_USB
参数:
| 名称 | 描述 |
|---|---|
| interfaceHandle | 接口操作句柄，代表要释放的接口。 |
返回:
成功返回0，否则返回负数。
OH_Usb_SelectInterfaceSetting()
int32_t OH_Usb_SelectInterfaceSetting (uint64_t interfaceHandle, uint8_t settingIndex )
描述:
激活接口的备用设置。
需要权限：ohos.permission.ACCESS_DDK_USB
参数:
| 名称 | 描述 |
|---|---|
| interfaceHandle | 接口操作句柄，代表要操作的接口。 |
| settingIndex | 备用设置索引，对应USB协议中的bAlternateSetting。 |
返回:
成功返回0，否则返回负数。
OH_Usb_SendControlReadRequest()
int32_t OH_Usb_SendControlReadRequest (uint64_t interfaceHandle, const struct UsbControlRequestSetup * setup, uint32_t timeout, uint8_t * data, uint32_t * dataLen )
描述:
发送控制读请求，该接口为同步接口。
需要权限：ohos.permission.ACCESS_DDK_USB
参数:
| 名称 | 描述 |
|---|---|
| interfaceHandle | 接口操作句柄，代表要操作的接口。 |
| setup | 请求相关的参数，详细定义请参考 UsbControlRequestSetup。 |
| timeout | 超时时间，单位为毫秒。 |
| data | 要传输的数据。 |
| dataLen | 表示data的数据长度，在函数返回后，表示实际读取到的数据的长度。 |
返回:
成功返回0，否则返回负数。
OH_Usb_SendControlWriteRequest()
int32_t OH_Usb_SendControlWriteRequest (uint64_t interfaceHandle, const struct UsbControlRequestSetup * setup, uint32_t timeout, const uint8_t * data, uint32_t dataLen )
描述:
发送控制写请求，该接口为同步接口。
需要权限：ohos.permission.ACCESS_DDK_USB
参数:
| 名称 | 描述 |
|---|---|
| interfaceHandle | 接口操作句柄，代表要操作的接口。 |
| setup | 请求相关的参数，详细定义请参考 UsbControlRequestSetup。 |
| timeout | 超时时间，单位为毫秒。 |
| data | 要传输的数据。 |
| dataLen | 表示data的数据长度。 |
返回:
成功返回0，否则返回负数。
OH_Usb_SendPipeRequest()
int32_t OH_Usb_SendPipeRequest (const struct UsbRequestPipe * pipe, UsbDeviceMemMap * devMmap )
描述:
发送管道请求，该接口为同步接口。中断传输和批量传输都使用该接口发送请求。
需要权限：ohos.permission.ACCESS_DDK_USB
参数:
| 名称 | 描述 |
|---|---|
| pipe | 要传输数据的管道信息。 |
| devMmap | 数据缓冲区，可以通过OH_Usb_CreateDeviceMemMap()获得。 |
返回:
成功返回0，否则返回负数。