usb_ddk_api.h
概述
声明用于主机侧访问设备的USB DDK接口。
引用文件： <usb/usb_ddk_api.h>
库： libusb_ndk.z.so
系统能力： SystemCapability.Driver.USB.Extension
起始版本： 10
相关模块： UsbDdk
汇总
函数
函数说明
OH_Usb_Init()
int32_t OH_Usb_Init(void)
描述
初始化USB DDK。
需要权限： ohos.permission.ACCESS_DDK_USB
起始版本： 10
返回：
| 类型 | 说明 |
|---|---|
| int32_t | USB_DDK_SUCCESS 调用接口成功。 USB_DDK_INVALID_OPERATION 连接 USB DDK 服务失败或内部错误。 USB_DDK_NO_PERM 权限检查失败。 USB_DDK_MEMORY_ERROR 内存分配失败。 |
OH_Usb_Release()
void OH_Usb_Release(void)
描述
释放USB DDK。
需要权限： ohos.permission.ACCESS_DDK_USB
起始版本： 10
OH_Usb_ReleaseResource()
int32_t OH_Usb_ReleaseResource(void)
描述
释放USB DDK。
需要权限： ohos.permission.ACCESS_DDK_USB
起始版本： 18
返回：
| 类型 | 说明 |
|---|---|
| int32_t | USB_DDK_SUCCESS 调用接口成功。 USB_DDK_NO_PERM 权限检查失败。 USB_DDK_INVALID_OPERATION 连接 USB DDK 服务失败。 |
OH_Usb_GetDeviceDescriptor()
int32_t OH_Usb_GetDeviceDescriptor(uint64_t deviceId, struct UsbDeviceDescriptor *desc)
描述
获取设备描述符。
需要权限： ohos.permission.ACCESS_DDK_USB
起始版本： 10
参数：
| 参数项 | 描述 |
|---|---|
| uint64_t deviceId | 设备ID，代表要获取描述符的设备。 |
| struct UsbDeviceDescriptor *desc | 设备描述符，详细定义请参考UsbDeviceDescriptor。 |
返回：
| 类型 | 说明 |
|---|---|
| int32_t | USB_DDK_SUCCESS 调用接口成功。 USB_DDK_NO_PERM 权限检查失败。 USB_DDK_INVALID_OPERATION 连接usb_ddk服务失败。 USB_DDK_INVALID_PARAMETER 入参desc为空指针。 |
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
起始版本： 10
参数：
| 参数项 | 描述 |
|---|---|
| uint64_t deviceId | 设备ID，代表要获取配置描述符的设备。 |
| uint8_t configIndex | 配置id，对应USB协议配置描述符中的bConfigurationValue字段 |
| struct UsbDdkConfigDescriptor ** const config | 配置描述符，包含USB协议中定义的标准配置描述符，以及与其关联的接口描述符和端点描述符。 |
返回：
| 类型 | 说明 |
|---|---|
| int32_t | USB_DDK_SUCCESS 调用接口成功。 USB_DDK_NO_PERM 权限检查失败。 USB_DDK_INVALID_OPERATION 连接USB DDK服务失败。 USB_DDK_INVALID_PARAMETER 入参config为空指针。 USB_DDK_IO_FAILED 数据I/O异常。 USB_DDK_MEMORY_ERROR 内存分配失败。 |
OH_Usb_FreeConfigDescriptor()
void OH_Usb_FreeConfigDescriptor(struct UsbDdkConfigDescriptor * const config)
描述
释放配置描述符，请在描述符使用完后释放描述符，否则会造成内存泄漏。
需要权限： ohos.permission.ACCESS_DDK_USB
起始版本： 10
参数：
| 参数项 | 描述 |
|---|---|
| const struct UsbDdkConfigDescriptor * const config | 配置描述符，通过OH_Usb_GetConfigDescriptor获得的配置描述符。 |
OH_Usb_ClaimInterface()
int32_t OH_Usb_ClaimInterface(uint64_t deviceId, uint8_t interfaceIndex, uint64_t *interfaceHandle)
描述
声明接口。
需要权限： ohos.permission.ACCESS_DDK_USB
起始版本： 10
参数：
| 参数项 | 描述 |
|---|---|
| uint64_t deviceId | 设备ID，代表要操作的设备。 |
| uint8_t interfaceIndex | 接口索引，对应USB协议中的bInterfaceNumber。 |
| uint64_t *interfaceHandle | 接口操作句柄，接口声明成功后，该参数将会被赋值。 |
返回：
| 类型 | 说明 |
|---|---|
| int32_t | USB_DDK_SUCCESS 调用接口成功。 USB_DDK_NO_PERM 权限检查失败。 USB_DDK_INVALID_OPERATION 连接USB DDK服务失败。 USB_DDK_INVALID_PARAMETER 入参interfaceHandle为空指针。 USB_DDK_MEMORY_ERROR 内存超出限制。 |
OH_Usb_ReleaseInterface()
int32_t OH_Usb_ReleaseInterface(uint64_t interfaceHandle)
描述
释放接口。
需要权限： ohos.permission.ACCESS_DDK_USB
起始版本： 10
参数：
| 参数项 | 描述 |
|---|---|
| uint64_t interfaceHandle | 接口操作句柄，代表要释放的接口。 |
返回：
| 类型 | 说明 |
|---|---|
| int32_t | USB_DDK_SUCCESS 调用接口成功。 USB_DDK_NO_PERM 权限检查失败。 USB_DDK_INVALID_OPERATION 连接USB DDK服务失败。 USB_DDK_INVALID_PARAMETER 参数错误。 |
OH_Usb_SelectInterfaceSetting()
int32_t OH_Usb_SelectInterfaceSetting(uint64_t interfaceHandle, uint8_t settingIndex)
描述
激活接口的备用设置。
需要权限： ohos.permission.ACCESS_DDK_USB
起始版本： 10
参数：
| 参数项 | 描述 |
|---|---|
| uint64_t interfaceHandle | 接口操作句柄，代表要操作的接口。 |
| uint8_t settingIndex | 备用设置索引，对应USB协议中接口描述符的 bAlternateSetting字段。 |
返回：
| 类型 | 说明 |
|---|---|
| int32_t | USB_DDK_SUCCESS 调用接口成功。 USB_DDK_NO_PERM 权限检查失败。 USB_DDK_INVALID_OPERATION 连接USB DDK服务失败。 USB_DDK_INVALID_PARAMETER 参数错误。 |
OH_Usb_GetCurrentInterfaceSetting()
int32_t OH_Usb_GetCurrentInterfaceSetting(uint64_t interfaceHandle, uint8_t *settingIndex)
描述
获取接口当前激活的备用设置。
需要权限： ohos.permission.ACCESS_DDK_USB
起始版本： 10
参数：
| 参数项 | 描述 |
|---|---|
| uint64_t interfaceHandle | 接口操作句柄，代表要操作的接口。 |
| uint8_t *settingIndex | 备用设置索引，对应USB协议中接口描述符的 bAlternateSetting字段。 |
返回：
| 类型 | 说明 |
|---|---|
| int32_t | USB_DDK_SUCCESS 调用接口成功。 USB_DDK_NO_PERM 权限检查失败。 USB_DDK_INVALID_OPERATION 连接USB DDK服务失败。 USB_DDK_INVALID_PARAMETER 入参settingIndex为空指针。 |
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
起始版本： 10
参数：
| 参数项 | 描述 |
|---|---|
| uint64_t interfaceHandle | 接口操作句柄，代表要操作的接口。 |
| const struct UsbControlRequestSetup *setup | 请求相关的参数，详细定义请参考UsbControlRequestSetup。 |
| uint32_t timeout | 超时时间，单位为毫秒。 |
| uint8_t *data | 要传输的数据。 |
| uint32_t *dataLen | 表示data的数据长度，在函数返回后，表示实际读取到的数据的长度。 |
返回：
| 类型 | 说明 |
|---|---|
| int32_t | USB_DDK_SUCCESS 调用接口成功。 USB_DDK_NO_PERM 权限校验失败。 USB_DDK_INVALID_OPERATION 连接USB DDK服务失败。 USB_DDK_INVALID_PARAMETER 入参setup或者data或者dataLen为空指针，或者datalen小于读取到的数据长度。 USB_DDK_MEMORY_ERROR 拷贝读取数据的内存失败。 USB_DDK_IO_FAILED 数据I/O异常。 USB_DDK_TIMEOUT 接口调用超时。 |
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
起始版本： 10
参数：
| 参数项 | 描述 |
|---|---|
| uint64_t interfaceHandle | 接口操作句柄，代表要操作的接口。 |
| const struct UsbControlRequestSetup *setup | 请求相关的参数，详细定义请参考UsbControlRequestSetup。 |
| uint32_t timeout | 超时时间，单位为毫秒。 |
| const uint8_t *data | 要传输的数据。 |
| uint32_t dataLen | 表示data数据长度。 |
返回：
| 类型 | 说明 |
|---|---|
| int32_t | USB_DDK_SUCCESS 调用接口成功。 USB_DDK_NO_PERM 权限校验失败。 USB_DDK_INVALID_OPERATION 连接USB DDK服务失败。 USB_DDK_INVALID_PARAMETER 入参setup或者data为空指针。 USB_DDK_MEMORY_ERROR 内存拷贝失败。 USB_DDK_IO_FAILED 数据I/O异常。 USB_DDK_TIMEOUT 接口调用超时。 |
OH_Usb_SendPipeRequest()
int32_t OH_Usb_SendPipeRequest(const struct UsbRequestPipe *pipe, UsbDeviceMemMap *devMmap)
描述
发送管道请求，该接口为同步接口。中断传输和批量传输都使用该接口发送请求。
需要权限： ohos.permission.ACCESS_DDK_USB
起始版本： 10
参数：
| 参数项 | 描述 |
|---|---|
| const struct UsbRequestPipe *pipe | 要传输数据的管道信息。 |
| UsbDeviceMemMap *devMmap | 数据缓冲区，可以通过OH_Usb_CreateDeviceMemMap获得。 |
返回：
| 类型 | 说明 |
|---|---|
| int32_t | USB_DDK_SUCCESS 调用接口成功。 USB_DDK_NO_PERM 权限检查失败。 USB_DDK_INVALID_OPERATION 连接USB DDK服务失败。 USB_DDK_INVALID_PARAMETER 入参pipe为空指针或devMmap为空指针或devMmap的地址为空。 USB_DDK_MEMORY_ERROR 读取数据的内存拷贝失败。 USB_DDK_IO_FAILED 数据 IO 异常。 USB_DDK_TIMEOUT 接口超时。 |
OH_Usb_SendPipeRequestWithAshmem()
int32_t OH_Usb_SendPipeRequestWithAshmem(const struct UsbRequestPipe *pipe, DDK_Ashmem *ashmem)
描述
基于共享内存发送管道请求，该接口为同步接口。中断传输和批量传输都使用该接口发送请求。
需要权限： ohos.permission.ACCESS_DDK_USB
起始版本： 12
参数：
| 参数项 | 描述 |
|---|---|
| const struct UsbRequestPipe *pipe | 要传输数据的管道信息。 |
| DDK_Ashmem *ashmem | 共享内存，可以通过OH_DDK_CreateAshmem获得。 |
返回：
| 类型 | 说明 |
|---|---|
| int32_t | USB_DDK_SUCCESS 调用接口成功。 USB_DDK_NO_PERM 权限检查失败。 USB_DDK_INVALID_OPERATION 连接USB DDK服务失败。 USB_DDK_INVALID_PARAMETER 入参pipe为空指针或ashmem为空指针或ashmem的地址为空。 USB_DDK_MEMORY_ERROR 读取数据的内存拷贝失败。 USB_DDK_IO_FAILED 数据 IO 异常。 USB_DDK_TIMEOUT 接口超时。 |
OH_Usb_CreateDeviceMemMap()
int32_t OH_Usb_CreateDeviceMemMap(uint64_t deviceId, size_t size, UsbDeviceMemMap **devMmap)
描述
创建缓冲区。请在缓冲区使用完后，调用OH_Usb_DestroyDeviceMemMap销毁缓冲区，否则会造成资源泄漏。
需要权限： ohos.permission.ACCESS_DDK_USB
起始版本： 10
参数：
| 参数项 | 描述 |
|---|---|
| uint64_t deviceId | 设备ID，代表要创建缓冲区的设备。 |
| size_t size | 缓冲区的大小。 |
| UsbDeviceMemMap **devMmap | 创建的缓冲区通过该参数返回给调用者。 |
返回：
| 类型 | 说明 |
|---|---|
| int32_t | USB_DDK_SUCCESS 调用接口成功。 USB_DDK_NO_PERM 权限检查失败。 USB_DDK_INVALID_PARAMETER 入参devMmap为空指针或*devMmap为空指针。 USB_DDK_MEMORY_ERROR 内存映射失败或devMmap的内存分配失败。 |
OH_Usb_DestroyDeviceMemMap()
void OH_Usb_DestroyDeviceMemMap(UsbDeviceMemMap *devMmap)
描述
销毁缓冲区。请在缓冲区使用完后及时销毁缓冲区，否则会造成资源泄漏。
需要权限： ohos.permission.ACCESS_DDK_USB
起始版本： 10
参数：
| 参数项 | 描述 |
|---|---|
| UsbDeviceMemMap *devMmap | 销毁由OH_Usb_CreateDeviceMemMap创建的缓冲区。 |
OH_Usb_GetDevices()
int32_t OH_Usb_GetDevices(struct Usb_DeviceArray *devices)
描述
获取USB设备ID列表。请保证传入的指针参数是有效的，申请的设备ID数组的大小建议不超过128，以避免过度占用内存。在使用完结构体之后，需释放成员内存，否则会造成资源泄漏。获取到的USB设备ID，已通过驱动配置信息中的vid进行筛选过滤。
需要权限： ohos.permission.ACCESS_DDK_USB
起始版本： 18
参数：
| 参数项 | 描述 |
|---|---|
| struct Usb_DeviceArray *devices | 已申请好的设备内存地址，用于存放获取到的设备ID列表及数量。 |
返回：
| 类型 | 说明 |
|---|---|
| int32_t | USB_DDK_SUCCESS 调用接口成功。 USB_DDK_NO_PERM 权限检查失败。 USB_DDK_INVALID_OPERATION 连接USB DDK服务失败。 USB_DDK_INVALID_PARAMETER 入参devices为空指针。 |
OH_Usb_ControlTransfer()
int32_t OH_Usb_ControlTransfer(uint64_t deviceID, const struct UsbControlRequestSetup *setupPacket, uint8_t *data, uint32_t timeout)
描述
执行USB控制传输，该接口为同步接口。
需要权限： ohos.permission.ACCESS_DDK_USB
起始版本： 26.0.0
参数：
| 参数项 | 描述 |
|---|---|
| uint64_t deviceID | 设备ID，代表要进行通信的设备。 |
| const struct UsbControlRequestSetup *setupPacket | 控制传输请求的setup包配置参数，包含了传输方向、传输数据长度等信息。 |
| uint8_t *data | 已申请好的缓冲区，用于存放输入或输出数据。缓冲区大小应与setup包中的wLength字段一致，且最大不超过1024，否则会被截断。 |
| uint32_t timeout | 超时时间（单位为毫秒），在未收到响应时等待的最大时间。设置为0表示无限制等待。 |
返回：
| 类型 | 说明 |
|---|---|
| int32_t | 成功时返回实际传输的字节数（非负数）。 USB_DDK_NO_PERM 权限检查失败。 USB_DDK_INVALID_OPERATION DDK服务未初始化，请先调用OH_Usb_Init完成初始化。 USB_DDK_INVALID_PARAMETER setupPacket或data参数无效。 USB_DDK_TIMEOUT 控制传输超时。 USB_DDK_IO_FAILED 控制传输请求I/O异常。 |
OH_Usb_GetNonRootHubs()
int32_t OH_Usb_GetNonRootHubs(struct Usb_NonRootHubArray *nonRootHub)
描述
查询并返回非根集线器列表。请保证传入的指针参数是有效的，申请的非根集线器ID数组的大小建议不超过128，以避免过度占用内存。在使用完结构体之后，需释放成员内存，否则会造成资源泄漏。
需要权限： ohos.permission.ACCESS_DDK_USB
起始版本： 26.0.0
参数：
| 参数项 | 描述 |
|---|---|
| struct Usb_NonRootHubArray *nonRootHub | 已申请好的非根集线器内存地址，用于存放查询到的非根集线器ID列表及数量。 |
返回：
| 类型 | 说明 |
|---|---|
| int32_t | USB_DDK_SUCCESS 查询操作成功。 USB_DDK_NO_PERM 权限检查失败。 USB_DDK_INVALID_OPERATION DDK服务未初始化，请先调用OH_Usb_Init完成初始化。 USB_DDK_INVALID_PARAMETER 入参nonRootHub为空指针。 |