harmony 鸿蒙UsbDDK

  • 2023-10-30
  • 浏览 (367)

UsbDDK

Overview

Provides USB DDK APIs to open and close USB interfaces, perform non-isochronous and isochronous data transfer over USB pipes, and implement control transfer and interrupt transfer, etc.

\@syscap SystemCapability.Driver.USB.Extension

Since

10

Summary

File

Name Description
usb_ddk_api.h Declares the USB DDK APIs used by the USB host to access USB devices.
File to include: <usb/usb_ddk_api.h>
Library: libusb_ndk.z.so
usb_ddk_types.h Provides the enumerated variables, structures, and macros used in USB DDK APIs.
File to include: <usb/usb_ddk_types.h>
Library: libusb_ndk.z.so

Structs

Name Description
UsbControlRequestSetup Setup data for control transfer. It corresponds to Setup Data in the USB protocol.
UsbDeviceDescriptor Standard device descriptor, corresponding to Standard Device Descriptor in the USB protocol.
UsbConfigDescriptor Standard configuration descriptor, corresponding to Standard Configuration Descriptor in the USB protocol.
UsbInterfaceDescriptor Standard interface descriptor, corresponding to Standard Interface Descriptor in the USB protocol.
UsbEndpointDescriptor Standard endpoint descriptor, corresponding to Standard Endpoint Descriptor in the USB protocol.
UsbDdkEndpointDescriptor Endpoint descriptor.
UsbDdkInterfaceDescriptor Interface descriptor.
UsbDdkInterface USB DDK interface, which is a collection of alternate settings for a particular USB interface.
UsbDdkConfigDescriptor Configuration descriptor.
UsbRequestPipe Request pipe.
UsbDeviceMemMap Device memory map created by calling OH_Usb_CreateDeviceMemMap(). A buffer using the device memory map can provide better performance.

Types

Name Description
UsbDdkEndpointDescriptor Endpoint descriptor.
UsbDdkInterfaceDescriptor Interface descriptor.
UsbDdkInterface USB DDK interface, which is a collection of alternate settings for a particular USB interface.
UsbDdkConfigDescriptor Configuration descriptor.
UsbDeviceMemMap Device memory map created by calling OH_Usb_CreateDeviceMemMap(). A buffer using the device memory map can provide better performance.

Enums

Name Description
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 error code definitions.

Functions

Name Description
OH_Usb_Init (void) Initializes the DDK.
OH_Usb_Release (void) Releases the DDK.
OH_Usb_GetDeviceDescriptor (uint64_t deviceId, struct UsbDeviceDescriptor *desc) Obtains the device descriptor.
OH_Usb_GetConfigDescriptor (uint64_t deviceId, uint8_t configIndex, struct UsbDdkConfigDescriptor **const config) Obtains the configuration descriptor. To avoid memory leakage, use OH_Usb_FreeConfigDescriptor to release a descriptor after use.
OH_Usb_FreeConfigDescriptor (const struct UsbDdkConfigDescriptor *const config) Releases the configuration descriptor. To avoid memory leakage, release a descriptor after use.
OH_Usb_ClaimInterface (uint64_t deviceId, uint8_t interfaceIndex, uint64_t *interfaceHandle) Declares a USB interface.
OH_Usb_ReleaseInterface (uint64_t interfaceHandle) Releases a USB interface.
OH_Usb_SelectInterfaceSetting (uint64_t interfaceHandle, uint8_t settingIndex) Activates the alternate setting of a USB interface.
OH_Usb_GetCurrentInterfaceSetting (uint64_t interfaceHandle, uint8_t *settingIndex) Obtains the activated alternate setting of a USB interface.
OH_Usb_SendControlReadRequest (uint64_t interfaceHandle, const struct UsbControlRequestSetup *setup, uint32_t timeout, uint8_t *data, uint32_t *dataLen) Sends a control read transfer request. This API works in a synchronous manner.
OH_Usb_SendControlWriteRequest (uint64_t interfaceHandle, const struct UsbControlRequestSetup *setup, uint32_t timeout, const uint8_t *data, uint32_t dataLen) Sends a control write transfer request. This API works in a synchronous manner.
OH_Usb_SendPipeRequest (const struct UsbRequestPipe *pipe, UsbDeviceMemMap *devMmap) Sends a pipe request. This API works in a synchronous manner. It applies to interrupt transfer and bulk transfer.
OH_Usb_CreateDeviceMemMap (uint64_t deviceId, size_t size, UsbDeviceMemMap **devMmap) Creates a buffer. To avoid memory leakage, use OH_Usb_DestroyDeviceMemMap() to destroy a buffer after use.
OH_Usb_DestroyDeviceMemMap (UsbDeviceMemMap *devMmap) Destroys a buffer. To avoid resource leakage, destroy a buffer in time after use.

Type Description

UsbDdkConfigDescriptor

typedef struct UsbDdkConfigDescriptor UsbDdkConfigDescriptor

Description

Configuration descriptor.

UsbDdkEndpointDescriptor

typedef struct UsbDdkEndpointDescriptor UsbDdkEndpointDescriptor

Description

Endpoint descriptor.

UsbDdkInterface

typedef struct UsbDdkInterface UsbDdkInterface

Description

USB DDK interface, which is a collection of alternate settings for a particular USB interface.

UsbDdkInterfaceDescriptor

typedef struct UsbDdkInterfaceDescriptor UsbDdkInterfaceDescriptor

Description

Interface descriptor.

UsbDeviceMemMap

typedef struct UsbDeviceMemMap UsbDeviceMemMap

Description

Device memory map created by calling OH_Usb_CreateDeviceMemMap(). A buffer using the device memory map can provide better performance.

Enum Description

UsbDdkErrCode

enum UsbDdkErrCode

Description

USB DDK error code definitions.

Value Description
USB_DDK_SUCCESS Operation successful.
USB_DDK_FAILED Operation failed.
USB_DDK_INVALID_PARAMETER Invalid parameter.
USB_DDK_MEMORY_ERROR Memory-related error, for example, insufficient memory, memory data copy failure, or memory application failure.
USB_DDK_INVALID_OPERATION Invalid operation.
USB_DDK_NULL_PTR Null pointer.
USB_DDK_DEVICE_BUSY Device busy.
USB_DDK_TIMEOUT Transfer timed out.

Function Description

OH_Usb_ClaimInterface()

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

Description

Declares a USB interface.

Required permissions: ohos.permission.ACCESS_DDK_USB

Parameters

Name Description
deviceId Device ID.
interfaceIndex Interface index, which corresponds to bInterfaceNumber in the USB protocol.
interfaceHandle Interface operation handle. After the interface is claimed successfully, a value will be assigned to this parameter.

Returns

0 if the operation is successful; a negative value otherwise.

OH_Usb_CreateDeviceMemMap()

int32_t OH_Usb_CreateDeviceMemMap (uint64_t deviceId, size_t size, UsbDeviceMemMap ** devMmap )

Description

Creates a buffer. To avoid memory leakage, use OH_Usb_DestroyDeviceMemMap() to destroy a buffer after use.

Required permissions: ohos.permission.ACCESS_DDK_USB

Parameters

Name Description
deviceId Device ID.
size Buffer size.
devMmap Data memory map, through which the created buffer is returned to the caller.

Returns

0 if the operation is successful; a negative value otherwise.

OH_Usb_DestroyDeviceMemMap()

void OH_Usb_DestroyDeviceMemMap (UsbDeviceMemMap * devMmap)

Description

Destroys a buffer. To avoid resource leakage, destroy a buffer in time after use.

Required permissions: ohos.permission.ACCESS_DDK_USB

Parameters

Name Description
devMmap Destroys the buffer created by OH_Usb_CreateDeviceMemMap().

OH_Usb_FreeConfigDescriptor()

void OH_Usb_FreeConfigDescriptor (const struct UsbDdkConfigDescriptor *const config)

Description

Releases the configuration descriptor. To avoid memory leakage, use OH_Usb_FreeConfigDescriptor to release a descriptor after use.

Required permissions: ohos.permission.ACCESS_DDK_USB

Parameters

Name Description
config Configuration descriptor obtained by calling OH_Usb_GetConfigDescriptor().

OH_Usb_GetConfigDescriptor()

int32_t OH_Usb_GetConfigDescriptor (uint64_t deviceId, uint8_t configIndex, struct UsbDdkConfigDescriptor **const config )

Description

Obtains the configuration descriptor. To avoid memory leakage, use OH_Usb_FreeConfigDescriptor to release a descriptor after use.

Required permissions: ohos.permission.ACCESS_DDK_USB

Parameters

Name Description
deviceId Device ID.
configIndex Configuration ID, which corresponds to bConfigurationValue in the USB protocol.
config Configuration descriptor, which includes the standard configuration descriptor defined in the USB protocol and the associated interface descriptor and endpoint descriptor.

Returns

0 if the operation is successful; a negative value otherwise.

OH_Usb_GetCurrentInterfaceSetting()

int32_t OH_Usb_GetCurrentInterfaceSetting (uint64_t interfaceHandle, uint8_t * settingIndex )

Description

Obtains the activated alternate setting of a USB interface.

Required permissions: ohos.permission.ACCESS_DDK_USB

Parameters

Name Description
interfaceHandle Interface operation handle.
settingIndex Index of the alternate setting, which corresponds to bAlternateSetting in the USB protocol.

Returns

0 if the operation is successful; a negative value otherwise.

OH_Usb_GetDeviceDescriptor()

int32_t OH_Usb_GetDeviceDescriptor (uint64_t deviceId, struct UsbDeviceDescriptor * desc )

Description

Obtains the device descriptor.

Required permissions: ohos.permission.ACCESS_DDK_USB

Parameters

Name Description
deviceId Device ID.
desc Device descriptor. For details, see UsbDeviceDescriptor.

Returns

0 if the operation is successful; a negative value otherwise.

OH_Usb_Init()

int32_t OH_Usb_Init (void )

Description

Initializes the DDK.

Required permissions: ohos.permission.ACCESS_DDK_USB

Returns

0 if the operation is successful; a negative value otherwise.

OH_Usb_Release()

void OH_Usb_Release (void )

Description

Releases the DDK.

Required permissions: ohos.permission.ACCESS_DDK_USB

OH_Usb_ReleaseInterface()

int32_t OH_Usb_ReleaseInterface (uint64_t interfaceHandle)

Description

Releases a USB interface.

Required permissions: ohos.permission.ACCESS_DDK_USB

Parameters

Name Description
interfaceHandle Interface operation handle.

Returns

0 if the operation is successful; a negative value otherwise.

OH_Usb_SelectInterfaceSetting()

int32_t OH_Usb_SelectInterfaceSetting (uint64_t interfaceHandle, uint8_t settingIndex )

Description

Activates the alternate setting of a USB interface.

Required permissions: ohos.permission.ACCESS_DDK_USB

Parameters

Name Description
interfaceHandle Interface operation handle.
settingIndex Index of the alternate setting, which corresponds to bAlternateSetting in the USB protocol.

Returns

0 if the operation is successful; a negative value otherwise.

OH_Usb_SendControlReadRequest()

int32_t OH_Usb_SendControlReadRequest (uint64_t interfaceHandle, const struct UsbControlRequestSetup * setup, uint32_t timeout, uint8_t * data, uint32_t * dataLen )

Description

Sends a control read transfer request. This API works in a synchronous manner.

Required permissions: ohos.permission.ACCESS_DDK_USB

Parameters

Name Description
interfaceHandle Interface operation handle.
setup Request parameters. For details, see UsbControlRequestSetup.
timeout Timeout duration, in milliseconds.
data Data to be transferred.
dataLen Data length. The return value indicates the length of the actually read data.

Returns

0 if the operation is successful; a negative value otherwise.

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 )

Description

Sends a control write transfer request. This API works in a synchronous manner.

Required permissions: ohos.permission.ACCESS_DDK_USB

Parameters

Name Description
interfaceHandle Interface operation handle.
setup Request parameters. For details, see UsbControlRequestSetup.
timeout Timeout duration, in milliseconds.
data Data to be transferred.
dataLen Data length.

Returns

0 if the operation is successful; a negative value otherwise.

OH_Usb_SendPipeRequest()

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

Description

Sends a pipe request. This API works in a synchronous manner. It applies to interrupt transfer and bulk transfer.

Required permissions: ohos.permission.ACCESS_DDK_USB

Parameters

Name Description
pipe Pipe used to transfer data.
devMmap Device memory map, which can be obtained by calling OH_Usb_CreateDeviceMemMap().

Returns

0 if the operation is successful; a negative value otherwise.

你可能感兴趣的鸿蒙文章

harmony 鸿蒙Native APIs

harmony 鸿蒙AVCapability

harmony 鸿蒙AVDemuxer

harmony 鸿蒙AVMuxer

harmony 鸿蒙AVScreenCapture

harmony 鸿蒙AVSource

harmony 鸿蒙AudioDecoder

harmony 鸿蒙AudioEncoder

harmony 鸿蒙CodecBase

harmony 鸿蒙Core

0  赞