harmony 鸿蒙USB DDK

2025-06-12 浏览 (1)

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接口描述符。
UsbDdkInterfaceUSB接口，是特定接口下备用设置的集合。
UsbDdkConfigDescriptor配置描述符。
UsbRequestPipe请求管道。
UsbDeviceMemMap设备内存映射，通过OH_Usb_CreateDeviceMemMap()创建设备内存映射，使用内存映射后的缓冲区，获得更好的性能。
Usb_DeviceArray设备ID清单，用于存放OH_Usb_GetDevices()接口获取到的设备ID列表和设备数量。

枚举

名称描述
UsbDdkErrCode {
USB_DDK_SUCCESS = 0, USB_DDK_NO_PERM = 201, USB_DDK_INVALID_PARAMETER = 401, USB_DDK_MEMORY_ERROR = 27400001,
USB_DDK_INVALID_OPERATION = 27400002, USB_DDK_IO_FAILED = 27400003, USB_DDK_TIMEOUT = 27400004
}		USB DDK 错误码定义。

函数

名称描述
OH_Usb_Init (void)初始化DDK。
OH_Usb_Release (void)释放DDK。
OH_Usb_ReleaseResource (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_SendPipeRequestWithAshmem (const struct UsbRequestPipe *pipe, DDK_Ashmem *ashmem)发送共享内存管道请求，该接口为同步接口。中断传输和批量传输都使用该接口发送请求。
OH_Usb_CreateDeviceMemMap (uint64_t deviceId, size_t size, UsbDeviceMemMap **devMmap)创建缓冲区。请在缓冲区使用完后，调用OH_Usb_DestroyDeviceMemMap()销毁缓冲区，否则会造成资源泄露。
OH_Usb_DestroyDeviceMemMap (UsbDeviceMemMap *devMmap)销毁缓冲区。请在缓冲区使用完后及时销毁缓冲区，否则会造成资源泄露。
OH_Usb_GetDevices (Usb_DeviceArray *devices)获取USB设备ID列表。请保证传入的指针参数是有效的，申请设备的数量不要超过128个，在使用完结构之后，释放成员内存，否则造成资源泄露。获取到的USB设备ID，已通过驱动配置信息中的vid进行筛选过滤。

函数参数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

枚举定义值描述
USB_DDK_SUCCESS0操作成功。
USB_DDK_NO_PERM201操作失败。
USB_DDK_INVALID_PARAMETER401非法参数。
USB_DDK_MEMORY_ERROR27400001内存相关的错误，包括：内存不足、内存数据拷贝失败、内存申请失败等。
USB_DDK_INVALID_OPERATION27400002非法操作。
USB_DDK_IO_FAILED27400003设备I/O操作失败。
USB_DDK_TIMEOUT27400004传输超时。

函数说明

OH_Usb_ClaimInterface()

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

描述:

声明接口。

需要权限：ohos.permission.ACCESS_DDK_USB

起始版本： 10

参数:

名称描述
deviceId设备ID，代表要操作的设备。
interfaceIndex接口索引，对应USB协议中的bInterfaceNumber。
interfaceHandle接口操作句柄，接口声明成功后，该参数将会被赋值。

返回:

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

参数:

名称描述
deviceId设备ID，代表要创建缓冲区的设备。
size缓冲区的大小。
devMmap创建的缓冲区通过该参数返回给调用者。

返回:

OH_Usb_DestroyDeviceMemMap()

void OH_Usb_DestroyDeviceMemMap (UsbDeviceMemMap * devMmap)

描述:

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

需要权限：ohos.permission.ACCESS_DDK_USB

起始版本： 10

参数:

名称描述
devMmap销毁由OH_Usb_CreateDeviceMemMap()创建的缓冲区。

OH_Usb_FreeConfigDescriptor()

void OH_Usb_FreeConfigDescriptor (struct UsbDdkConfigDescriptor *const config)

描述:

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

需要权限：ohos.permission.ACCESS_DDK_USB

起始版本： 10

参数:

名称描述
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

起始版本： 10

参数:

名称描述
deviceId设备ID，代表要获取配置描述符的设备。
configIndex配置id，对应USB协议中的bConfigurationValue。
config配置描述符，包含USB协议中定义的标准配置描述符，以及与其关联的接口描述符和端点描述符。

返回:

OH_Usb_GetCurrentInterfaceSetting()

int32_t OH_Usb_GetCurrentInterfaceSetting (uint64_t interfaceHandle, uint8_t * settingIndex)

描述:

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

需要权限：ohos.permission.ACCESS_DDK_USB

起始版本： 10

参数:

名称描述
interfaceHandle接口操作句柄，代表要操作的接口。
settingIndex备用设置索引，对应USB协议中的bAlternateSetting。

返回:

OH_Usb_GetDeviceDescriptor()

int32_t OH_Usb_GetDeviceDescriptor (uint64_t deviceId, struct UsbDeviceDescriptor * desc)

描述:

获取设备描述符。

需要权限：ohos.permission.ACCESS_DDK_USB

起始版本： 10

参数:

名称描述
deviceId设备ID，代表要获取描述符的设备。
desc设备描述符，详细定义请参考UsbDeviceDescriptor。

返回:

OH_Usb_Init()

int32_t OH_Usb_Init (void )

描述:

初始化DDK。

需要权限：ohos.permission.ACCESS_DDK_USB

起始版本： 10

返回:

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

返回:

OH_Usb_ReleaseInterface()

int32_t OH_Usb_ReleaseInterface (uint64_t interfaceHandle)

描述:

释放接口。

需要权限：ohos.permission.ACCESS_DDK_USB

起始版本：10

参数:

名称描述
interfaceHandle接口操作句柄，代表要释放的接口。

返回:

OH_Usb_SelectInterfaceSetting()

int32_t OH_Usb_SelectInterfaceSetting (uint64_t interfaceHandle, uint8_t settingIndex)

描述:

激活接口的备用设置。

需要权限：ohos.permission.ACCESS_DDK_USB

起始版本：10

参数:

名称描述
interfaceHandle接口操作句柄，代表要操作的接口。
settingIndex备用设置索引，对应USB协议中的bAlternateSetting。

返回:

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

参数:

名称描述
interfaceHandle接口操作句柄，代表要操作的接口。
setup请求相关的参数，详细定义请参考 UsbControlRequestSetup。
timeout超时时间，单位为毫秒。
data要传输的数据。
dataLen表示data的数据长度，在函数返回后，表示实际读取到的数据的长度。

返回:

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

参数:

名称描述
interfaceHandle接口操作句柄，代表要操作的接口。
setup请求相关的参数，详细定义请参考 UsbControlRequestSetup。
timeout超时时间，单位为毫秒。
data要传输的数据。
dataLen表示data的数据长度。

返回:

OH_Usb_SendPipeRequest()

int32_t OH_Usb_SendPipeRequest (const struct UsbRequestPipe * pipe, UsbDeviceMemMap * devMmap)

描述:

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

需要权限：ohos.permission.ACCESS_DDK_USB

起始版本：10

参数:

名称描述
pipe要传输数据的管道信息。
devMmap数据缓冲区，可以通过OH_Usb_CreateDeviceMemMap()获得。

返回:

OH_Usb_SendPipeRequestWithAshmem()

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

描述:

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

需要权限：ohos.permission.ACCESS_DDK_USB

起始版本：12

参数:

名称描述
pipe要传输数据的管道信息。
ashmem共享内存，可以通过OH_DDK_CreateAshmem()获得。

返回:

OH_Usb_GetDevices()

int32_t OH_Usb_GetDevices(struct Usb_DeviceArray *devices)

描述:

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

需要权限：ohos.permission.ACCESS_DDK_USB

起始版本：18

参数:

名称描述
devices已申请好的设备内存地址，用于存放获取到的设备ID列表及数量。

返回:

你可能感兴趣的鸿蒙文章

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

  • 所属分类： 后端技术
  • 本文标签： 软件 鸿蒙
  • 版权声明： 本文链接 https://seaxiang.com/blog/XMMsqP