USB DDK

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.

System capability: SystemCapability.Driver.USB.Extension

Since

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.
Usb_DeviceArray	Defines the device ID list, which is used to store the device IDs and device quantity obtained using OH_Usb_GetDevices().

Enums

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

Functions

Name	Description
OH_Usb_Init (void)	Initializes the DDK.
OH_Usb_Release (void)	Releases the DDK.
OH_Usb_ReleaseResource (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_SendPipeRequestWithAshmem (const struct UsbRequestPipe pipe, DDK_Ashmem ashmem)	Sends a pipe request for the shared memory. This API returns the result synchronously. 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.
OH_Usb_GetDevices (Usb_DeviceArray *devices)	Obtains the USB device ID list. Ensure that the input pointer is valid and the number of devices does not exceed 128. To prevent resource leakage, release the member memory after usage. Besides, make sure that the obtained USB device ID has been filtered by vid in the driver configuration information.

deviceId Description

You can call queryDevices() to obtain the device ID, that is, deviceId. For details, see Peripheral Management Development.

deviceId Conversion

The deviceId obtained through queryDevices() cannot be directly used as the input parameter for functions such as OH_Usb_GetDeviceDescriptor.

Specifically, you need to extract its first 32 bits as the input parameter **deviceId** for C APIs.

The following code is for reference only:

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);
}

Type Description

UsbDdkEndpointDescriptor

typedef struct UsbDdkEndpointDescriptor UsbDdkEndpointDescriptor

Description

Endpoint descriptor.

Since: 10

UsbDdkInterfaceDescriptor

typedef struct UsbDdkInterfaceDescriptor UsbDdkInterfaceDescriptor

Description

Interface descriptor.

Since: 10

UsbDdkInterface

typedef struct UsbDdkInterface UsbDdkInterface

Description

USB API.

Since: 10

UsbDdkConfigDescriptor

typedef struct UsbDdkConfigDescriptor UsbDdkConfigDescriptor

Description

Configuration descriptor.

Since: 10

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.

Since: 10

Usb_DeviceArray

typedef struct Usb_DeviceArray usb_DeviceArray

Description

Defines the device ID list, which is used to store the device IDs and device quantity obtained using OH_Usb_GetDevices().

Since: 10

Enum Description

UsbDdkErrCode

enum UsbDdkErrCode

Description

USB DDK error code definitions.

Enum	Value	Description
USB_DDK_SUCCESS	0	Operation successful.
USB_DDK_NO_PERM	201	Operation failed.
USB_DDK_INVALID_PARAMETER	401	Invalid parameter.
USB_DDK_MEMORY_ERROR	27400001	Memory-related error, for example, insufficient memory, memory data copy failure, or memory application failure.
USB_DDK_INVALID_OPERATION	27400002	Invalid operation.
USB_DDK_IO_FAILED	27400003	The device I/O operation fails.
USB_DDK_TIMEOUT	27400004	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

[USB_DDK_SUCCESS] (#usbddkerrcode): The API call is successful.
USB_DDK_NO_PERM: The permission verification fails.
USB_DDK_INVALID_OPERATION: The usb_ddk service connection fails.
USB_DDK_INVALID_PARAMETER: The input interfaceHandle is a null pointer.

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

[USB_DDK_SUCCESS] (#usbddkerrcode): The API call is successful.
USB_DDK_NO_PERM: The permission verification fails.
USB_DDK_INVALID_PARAMETER: The input devMmap is a null pointer.
USB_DDK_MEMORY_ERROR: indicates that the mmap fails or the memory space of the devMmap fails to be applied for.

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 (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

[USB_DDK_SUCCESS] (#usbddkerrcode): The API call is successful.
USB_DDK_NO_PERM: The permission verification fails.
USB_DDK_INVALID_OPERATION: The usb_ddk service connection fails.
USB_DDK_INVALID_PARAMETER: The input config is a null pointer.
USB_DDK_IO_FAILED: The device I/O operation fails.

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

[USB_DDK_SUCCESS] (#usbddkerrcode): The API call is successful.
USB_DDK_NO_PERM: The permission verification fails.
USB_DDK_INVALID_OPERATION: The usb_ddk service connection fails.
USB_DDK_INVALID_PARAMETER: The input settingIndex is a null pointer.

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

[USB_DDK_SUCCESS] (#usbddkerrcode): The API call is successful.
USB_DDK_NO_PERM: The permission verification fails.
USB_DDK_INVALID_OPERATION: The usb_ddk service connection fails.
USB_DDK_INVALID_PARAMETER: The input desc is a null pointer.

OH_Usb_Init()

int32_t OH_Usb_Init (void )

Description

Initializes the DDK.

Required permissions: ohos.permission.ACCESS_DDK_USB

Returns

[USB_DDK_SUCCESS] (#usbddkerrcode): The API call is successful.
USB_DDK_NO_PERM: The permission verification fails.
USB_DDK_INVALID_OPERATION: The usb_ddk service connection fails.

OH_Usb_Release()

void OH_Usb_Release (void)

Description

Releases the DDK.

Required permissions: ohos.permission.ACCESS_DDK_USB

OH_Usb_ReleaseResource()¹⁴⁺

int32_t OH_Usb_ReleaseResource (void)

Description

Releases the DDK.

Required permissions: ohos.permission.ACCESS_DDK_USB

Returns

[USB_DDK_SUCCESS] (#usbddkerrcode): The API call is successful.
USB_DDK_NO_PERM: The permission verification fails.
USB_DDK_INVALID_OPERATION: The usb_ddk service connection fails.

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

[USB_DDK_SUCCESS] (#usbddkerrcode): The API call is successful.
USB_DDK_NO_PERM: The permission verification fails.
USB_DDK_INVALID_OPERATION: The usb_ddk service connection fails.

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

[USB_DDK_SUCCESS] (#usbddkerrcode): The API call is successful.
USB_DDK_NO_PERM: The permission verification fails.
USB_DDK_INVALID_OPERATION: The usb_ddk service connection fails.

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

[USB_DDK_SUCCESS] (#usbddkerrcode): The API call is successful.
USB_DDK_NO_PERM: The permission verification fails.
USB_DDK_INVALID_OPERATION: The usb_ddk service connection fails.
USB_DDK_INVALID_PARAMETER: The input setup, data, or dataLen is a null pointer, or the value of datalen is less than the length of the read data.
USB_DDK_MEMORY_ERROR: The attempt to copy the memory that stores the read data fails.
USB_DDK_IO_FAILED: The device I/O operation fails.
[USB_DDK_TIMEOUT] (#usbddkerrcode): The request times out.

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

[USB_DDK_SUCCESS] (#usbddkerrcode): The API call is successful.
USB_DDK_NO_PERM: The permission verification fails.
USB_DDK_INVALID_OPERATION: The usb_ddk service connection fails.
USB_DDK_INVALID_PARAMETER: The input setup or data is a null pointer.
USB_DDK_IO_FAILED: The device I/O operation fails.
[USB_DDK_TIMEOUT] (#usbddkerrcode): The request times out.

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

[USB_DDK_SUCCESS] (#usbddkerrcode): The API call is successful.
USB_DDK_NO_PERM: The permission verification fails.
USB_DDK_INVALID_OPERATION: The usb_ddk service connection fails.
USB_DDK_INVALID_PARAMETER: The input pipe, devMmap, or devMmap address is a null pointer.
USB_DDK_IO_FAILED: The device I/O operation fails.
[USB_DDK_TIMEOUT] (#usbddkerrcode): The request times out.

OH_Usb_SendPipeRequestWithAshmem()¹²⁺

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

Description

Sends a pipe request for the shared memory. This API returns the result synchronously. It applies to interrupt transfer and bulk transfer.

Required permissions: ohos.permission.ACCESS_DDK_USB

Parameters

Name	Description
pipe	Pipe used to transfer data.
ashmem	Shared memory, which can be obtained through OH_DDK_CreateAshmem().

Returns

[USB_DDK_SUCCESS] (#usbddkerrcode): The API call is successful.
USB_DDK_NO_PERM: The permission verification fails.
USB_DDK_INVALID_OPERATION: The usb_ddk service connection fails.
USB_DDK_INVALID_PARAMETER: The input pipe, ashmem, or ashmem address is a null pointer.
USB_DDK_IO_FAILED: The device I/O operation fails.
[USB_DDK_TIMEOUT] (#usbddkerrcode): The request times out.

OH_Usb_GetDevices()¹⁶⁺

int32_t OH_Usb_GetDevices(struct Usb_DeviceArray *devices)

Description

Obtains the USB device ID list. Ensure that the input pointer is valid and the number of devices does not exceed 128. To prevent resource leakage, release the member memory after usage. Besides, make sure that the obtained USB device ID has been filtered by vid in the driver configuration information.

Required permissions: ohos.permission.ACCESS_DDK_USB

Parameters

Name	Description
devices	Device memory address, which is used to store the obtained device ID list and quantity.

Returns

[USB_DDK_SUCCESS] (#usbddkerrcode): The API call is successful.
USB_DDK_NO_PERM: The permission verification fails.
USB_DDK_INVALID_OPERATION: The usb_ddk service connection fails.
USB_DDK_INVALID_PARAMETER: The address of devices is a null pointer.

你可能感兴趣的鸿蒙文章

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

USB DDK

Overview

Summary

File

Structs

Enums

Functions

deviceId Description

deviceId Conversion

Type Description

UsbDdkEndpointDescriptor

UsbDdkInterfaceDescriptor

UsbDdkInterface

UsbDdkConfigDescriptor

UsbDeviceMemMap

Usb_DeviceArray

Enum Description

UsbDdkErrCode

Function Description

OH_Usb_ClaimInterface()

OH_Usb_CreateDeviceMemMap()

OH_Usb_DestroyDeviceMemMap()

OH_Usb_FreeConfigDescriptor()

OH_Usb_GetConfigDescriptor()

OH_Usb_GetCurrentInterfaceSetting()

OH_Usb_GetDeviceDescriptor()

OH_Usb_Init()

OH_Usb_Release()

OH_Usb_ReleaseResource()14+

OH_Usb_ReleaseInterface()

OH_Usb_SelectInterfaceSetting()

OH_Usb_SendControlReadRequest()

OH_Usb_SendControlWriteRequest()

OH_Usb_SendPipeRequest()

OH_Usb_SendPipeRequestWithAshmem()12+

OH_Usb_GetDevices()16+

你可能感兴趣的鸿蒙文章

标签云

最热博客

最新博客

OH_Usb_ReleaseResource()¹⁴⁺

OH_Usb_SendPipeRequestWithAshmem()¹²⁺

OH_Usb_GetDevices()¹⁶⁺