harmony 鸿蒙UsbDDK

  • 2023-06-24
  • 浏览 (702)

UsbDDK

概述

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

\@syscap 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) 销毁缓冲区。请在缓冲区使用完后及时销毁缓冲区,否则会造成资源泄露。

枚举类型说明

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,否则返回负数。

你可能感兴趣的鸿蒙文章

harmony 鸿蒙Native API

harmony 鸿蒙AVCapability

harmony 鸿蒙AVDemuxer

harmony 鸿蒙AVMuxer

harmony 鸿蒙AVScreenCapture

harmony 鸿蒙AVSource

harmony 鸿蒙AudioDecoder

harmony 鸿蒙AudioEncoder

harmony 鸿蒙CodecBase

harmony 鸿蒙Core

0  赞