USB DDK

概述

提供USB DDK接口，包括主机侧打开和关闭接口、管道同步异步读写通信、控制传输、中断传输等。

系统能力： SystemCapability.Driver.USB.Extension

起始版本：

10

汇总

文件

结构体

枚举

函数

函数参数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);
}

类型定义说明

UsbDdkEndpointDescriptor

typedef struct UsbDdkEndpointDescriptor UsbDdkEndpointDescriptor

描述

端点描述符。

起始版本： 10

UsbDdkInterfaceDescriptor

typedef struct UsbDdkInterfaceDescriptor UsbDdkInterfaceDescriptor

描述

接口描述符。

起始版本： 10

UsbDdkInterface

typedef struct UsbDdkInterface UsbDdkInterface

描述

USB接口。

起始版本： 10

UsbDdkConfigDescriptor

typedef struct UsbDdkConfigDescriptor UsbDdkConfigDescriptor

描述

配置描述符。

起始版本： 10

UsbDeviceMemMap

typedef struct UsbDeviceMemMap UsbDeviceMemMap

描述

设备内存映射，通过OH_Usb_CreateDeviceMemMap()创建设备内存映射，使用内存映射后的缓冲区，获得更好的性能。

起始版本： 10

Usb_DeviceArray

typedef struct Usb_DeviceArray usb_DeviceArray

描述

设备ID清单，用于存放OH_Usb_GetDevices()接口获取到的设备ID列表和设备数量。

起始版本： 10

枚举类型说明

UsbDdkErrCode

enum UsbDdkErrCode

描述:

USB DDK 错误码定义。

起始版本： 10

函数说明

OH_Usb_ClaimInterface()

int32_t OH_Usb_ClaimInterface (uint64_t deviceId, uint8_t interfaceIndex, uint64_t * interfaceHandle)

描述:

声明接口。

需要权限：ohos.permission.ACCESS_DDK_USB

起始版本： 10

参数:

返回:

• USB_DDK_SUCCESS：表示调用接口成功。
• USB_DDK_NO_PERM：表示权限校验失败。
• USB_DDK_INVALID_OPERATION：表示连接usb_ddk服务失败。
• USB_DDK_INVALID_PARAMETER：表示入参interfaceHandle为空指针。
• USB_DDK_MEMORY_ERROR：表示内存超过限制。

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

参数:

返回:

• USB_DDK_SUCCESS：表示调用接口成功。
• USB_DDK_NO_PERM：表示权限校验失败。
• USB_DDK_INVALID_PARAMETER：表示入参devMmap为空指针。
• USB_DDK_MEMORY_ERROR：表示mmap失败或者申请devMmap的内存空间失败。

OH_Usb_DestroyDeviceMemMap()

void OH_Usb_DestroyDeviceMemMap (UsbDeviceMemMap * devMmap)

描述:

销毁缓冲区。请在缓冲区使用完后及时销毁缓冲区，否则会造成资源泄露。

需要权限：ohos.permission.ACCESS_DDK_USB

起始版本： 10

参数:

OH_Usb_FreeConfigDescriptor()

void OH_Usb_FreeConfigDescriptor (struct UsbDdkConfigDescriptor *const config)

描述:

释放配置描述符，请在描述符使用完后释放描述符，否则会造成内存泄露。

需要权限：ohos.permission.ACCESS_DDK_USB

起始版本： 10

参数:

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

参数:

返回:

• 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_GetCurrentInterfaceSetting()

int32_t OH_Usb_GetCurrentInterfaceSetting (uint64_t interfaceHandle, uint8_t * settingIndex)

描述:

获取接口当前激活的备用设置。

需要权限：ohos.permission.ACCESS_DDK_USB

起始版本： 10

参数:

返回:

• USB_DDK_SUCCESS：表示调用接口成功。
• USB_DDK_NO_PERM：表示权限校验失败。
• USB_DDK_INVALID_OPERATION：表示连接usb_ddk服务失败。
• USB_DDK_INVALID_PARAMETER：表示入参settingIndex为空指针。

OH_Usb_GetDeviceDescriptor()

int32_t OH_Usb_GetDeviceDescriptor (uint64_t deviceId, struct UsbDeviceDescriptor * desc)

描述:

获取设备描述符。

需要权限：ohos.permission.ACCESS_DDK_USB

起始版本： 10

参数:

返回:

• USB_DDK_SUCCESS：表示调用接口成功。
• USB_DDK_NO_PERM：表示权限校验失败。
• USB_DDK_INVALID_OPERATION：表示连接usb_ddk服务失败。
• USB_DDK_MEMORY_ERROR：内存分配失败。

OH_Usb_Init()

int32_t OH_Usb_Init (void )

描述:

初始化DDK。

需要权限：ohos.permission.ACCESS_DDK_USB

起始版本： 10

返回:

• USB_DDK_SUCCESS：表示调用接口成功。
• USB_DDK_NO_PERM：表示权限校验失败。
• USB_DDK_INVALID_OPERATION：表示连接usb_ddk服务失败。

OH_Usb_Release()

void OH_Usb_Release (void)

描述:

释放DDK。

需要权限：ohos.permission.ACCESS_DDK_USB

起始版本： 10

OH_Usb_ReleaseResource()

int32_t OH_Usb_ReleaseResource (void)

描述:

释放DDK。

需要权限：ohos.permission.ACCESS_DDK_USB

起始版本：18

返回:

• USB_DDK_SUCCESS：表示调用接口成功。
• USB_DDK_NO_PERM：表示权限校验失败。
• USB_DDK_INVALID_OPERATION：表示连接usb_ddk服务失败。

OH_Usb_ReleaseInterface()

int32_t OH_Usb_ReleaseInterface (uint64_t interfaceHandle)

描述:

释放接口。

需要权限：ohos.permission.ACCESS_DDK_USB

起始版本：10

参数:

返回:

• 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

参数:

返回:

• USB_DDK_SUCCESS：表示调用接口成功。
• USB_DDK_NO_PERM：表示权限校验失败。
• USB_DDK_INVALID_OPERATION：表示连接usb_ddk服务失败。
• USB_DDK_INVALID_PARAMETER：表示参数错误。

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

参数:

返回:

• 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

参数:

返回:

• 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

参数:

返回:

• 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：表示设备I/O操作失败。
• USB_DDK_TIMEOUT：表示请求超时。

OH_Usb_SendPipeRequestWithAshmem()

int32_t OH_Usb_SendPipeRequestWithAshmem(const struct UsbRequestPipe *pipe, DDK_Ashmem *ashmem)

描述:

发送共享内存的管道请求，该接口为同步接口。中断传输和批量传输都使用该接口发送请求。

需要权限：ohos.permission.ACCESS_DDK_USB

起始版本：12

参数:

返回:

• 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：表示设备I/O操作失败。
• USB_DDK_TIMEOUT：表示请求超时。

OH_Usb_GetDevices()

int32_t OH_Usb_GetDevices(struct Usb_DeviceArray *devices)

描述:

获取USB设备ID列表。请保证传入的指针参数是有效的，申请设备的数量不要超过128个，在使用完结构之后，释放成员内存，否则造成资源泄露。获取到的USB设备ID，已通过驱动配置信息中的vid进行筛选过滤。

需要权限：ohos.permission.ACCESS_DDK_USB

起始版本：18

参数:

返回:

• USB_DDK_SUCCESS：表示调用接口成功。
• USB_DDK_NO_PERM：表示权限校验失败。
• USB_DDK_INVALID_OPERATION：表示连接usb_ddk服务失败。
• USB_DDK_INVALID_PARAMETER：表示参数devices的地址为空指针。

你可能感兴趣的鸿蒙文章

harmony 鸿蒙Driver Development Kit（驱动开发服务）

harmony 鸿蒙Base DDK

harmony 鸿蒙DDK_Ashmem

harmony 鸿蒙Hid_AbsAxesArray

harmony 鸿蒙Hid_Device

harmony 鸿蒙Hid_EmitItem

harmony 鸿蒙Hid_EventProperties

harmony 鸿蒙Hid_EventTypeArray

harmony 鸿蒙Hid_KeyCodeArray

harmony 鸿蒙Hid_MscEventArray