From ea3ef5d528b0e7cb6fce7b6bf4bbac66450bf204 Mon Sep 17 00:00:00 2001 From: shawn_he Date: Fri, 21 Jan 2022 17:54:34 +0800 Subject: [PATCH] update docs Signed-off-by: shawn_he --- en/device-dev/apis/usb/usbd_client.h | 139 +++++++++++++++------------ 1 file changed, 79 insertions(+), 60 deletions(-) diff --git a/en/device-dev/apis/usb/usbd_client.h b/en/device-dev/apis/usb/usbd_client.h index ffb834ee398..cfafd29c3d9 100644 --- a/en/device-dev/apis/usb/usbd_client.h +++ b/en/device-dev/apis/usb/usbd_client.h @@ -27,7 +27,7 @@ /** * @file usbd_client.h * - * @brief Defines the usbd interface. + * @brief Defines usbd APIs. * * @since 3.0 * @version 1.0 @@ -43,6 +43,8 @@ namespace OHOS { namespace USB { class UsbdClient { public: + static UsbdClient &GetInstance(); + /* * * @brief Opens a USB device to set up a connection. * @@ -51,7 +53,7 @@ public: * @return Returns 0 if the operation is successful; returns a non-0 value if the operation fails. * @since 3.0 */ - static int32_t OpenDevice(const UsbDev &dev); + int32_t OpenDevice(const UsbDev &dev); /* * * @brief Closes a USB device to release all system resources related to the device. @@ -61,7 +63,7 @@ public: * @return Returns 0 if the operation is successful; returns a non-0 value if the operation fails. * @since 3.0 */ - static int32_t CloseDevice(const UsbDev &dev); + int32_t CloseDevice(const UsbDev &dev); /* * * @brief Obtains the USB device descriptor. @@ -72,19 +74,19 @@ public: * @return Returns 0 if the operation is successful; returns a non-0 value if the operation fails. * @since 3.0 */ - static int32_t GetDeviceDescriptor(const UsbDev &dev, std::vector &decriptor); + int32_t GetDeviceDescriptor(const UsbDev &dev, std::vector &decriptor); /* * * @brief Obtains the string descriptor of a USB device based on the specified string ID. * * @param dev Indicates the USB device address. * @param descId Indicates string descriptor ID. - * @param descriptor Indicates the string descriptor of the USB device. + * @param descriptor Indicates the configuration descriptor of the USB device. * * @return Returns 0 if the operation is successful; returns a non-0 value if the operation fails. * @since 3.0 */ - static int32_t GetStringDescriptor(const UsbDev &dev, uint8_t descId, std::vector &decriptor); + int32_t GetStringDescriptor(const UsbDev &dev, uint8_t descId, std::vector &decriptor); /* * * @brief Obtains the configuration descriptor of a USB device based on the specified config ID. @@ -96,7 +98,7 @@ public: * @return Returns 0 if the operation is successful; returns a non-0 value if the operation fails. * @since 3.0 */ - static int32_t GetConfigDescriptor(const UsbDev &dev, uint8_t descId, std::vector &decriptor); + int32_t GetConfigDescriptor(const UsbDev &dev, uint8_t descId, std::vector &decriptor); /* * * @brief Obtains the raw descriptor. @@ -107,7 +109,18 @@ public: * @return Returns 0 if the operation is successful; returns a non-0 value if the operation fails. * @since 3.0 */ - static int32_t GetRawDescriptor(const UsbDev &dev, std::vector &decriptor); + int32_t GetRawDescriptor(const UsbDev &dev, std::vector &decriptor); + + /* * + * @brief Obtains the file descriptor. + * + * @param dev Indicates the USB device address. + * @param fd USB device file descriptor + * + * @return Returns 0 if the operation is successful; returns a non-0 value if the operation fails. + * @since 3.0 + */ + int32_t GetFileDescriptor(const UsbDev &dev, int32_t &fd); /* * * @brief Sets the configuration information of a USB device. @@ -118,7 +131,7 @@ public: * @return Returns 0 if the operation is successful; returns a non-0 value if the operation fails. * @since 3.0 */ - static int32_t SetConfig(const UsbDev &dev, uint8_t configIndex); + int32_t SetConfig(const UsbDev &dev, uint8_t configIndex); /* * * @brief Obtains the configuration information of a USB device. @@ -129,18 +142,19 @@ public: * @return Returns 0 if the operation is successful; returns a non-0 value if the operation fails. * @since 3.0 */ - static int32_t GetConfig(const UsbDev &dev, uint8_t &configIndex); + int32_t GetConfig(const UsbDev &dev, uint8_t &configIndex); /* * * @brief Claims a USB interface exclusively. This must be done before data transfer. * * @param dev Indicates the USB device address. * @param interfaceid Indicates the interface ID of the USB device. + * @param force Indicates whether to enable the force mode. The value 1 indicates that the force mode is enabled, and value 0 indicates the opposite. * * @return Returns 0 if the operation is successful; returns a non-0 value if the operation fails. * @since 3.0 */ - static int32_t ClaimInterface(const UsbDev &dev, uint8_t interfaceid); + int32_t ClaimInterface(const UsbDev &dev, uint8_t interfaceid, uint8_t force); /* * * @brief Releases a USB interface. This is usually done after data transfer. @@ -151,7 +165,7 @@ public: * @return Returns 0 if the operation is successful; returns a non-0 value if the operation fails. * @since 3.0 */ - static int32_t ReleaseInterface(const UsbDev &dev, uint8_t interfaceid); + int32_t ReleaseInterface(const UsbDev &dev, uint8_t interfaceid); /* * * @brief Sets the alternate settings for the specified USB interface. This allows you to switch between two interfaces with the same ID but different alternate settings. @@ -163,7 +177,7 @@ public: * @return Returns 0 if the operation is successful; returns a non-0 value if the operation fails. * @since 3.0 */ - static int32_t SetInterface(const UsbDev &dev, uint8_t interfaceid, uint8_t altIndex); + int32_t SetInterface(const UsbDev &dev, uint8_t interfaceid, uint8_t altIndex); /* * * @brief Reads data on a specified endpoint during bulk transfer. The endpoint must be in the data reading direction. You can specify a timeout duration if needed. @@ -176,8 +190,7 @@ public: * @return Returns 0 if the operation is successful; returns a non-0 value if the operation fails. * @since 3.0 */ - static int32_t - BulkTransferRead(const UsbDev &dev, const UsbPipe &pipe, int32_t timeout, std::vector &data); + int32_t BulkTransferRead(const UsbDev &dev, const UsbPipe &pipe, int32_t timeout, std::vector &data); /* * * @brief Writes data on a specified endpoint during bulk transfer. The endpoint must be in the data writing direction. @@ -190,21 +203,21 @@ public: * @return Returns 0 if the operation is successful; returns a non-0 value if the operation fails. * @since 3.0 */ - static int32_t - BulkTransferWrite(const UsbDev &dev, const UsbPipe &pipe, int32_t timeout, const std::vector &data); + int32_t BulkTransferWrite(const UsbDev &dev, const UsbPipe &pipe, int32_t timeout, + const std::vector &data); /* * * @brief Performs control transfer for endpoint 0 of the device. The data transfer direction is determined by the request type. If the result of requestType& - * USB_ENDPOINT_DIR_MASK is USB_DIR_OUT, the endpoint is in the data writing direction; if the result is USB_DIR_IN, the endpoint is in the data reading direction. + * USB_ENDPOINT_DIR_MASK is USB_DIR_OUT, the endpoint is in the data writing direction; if the result is USB_DIR_IN, the endpoint is in the data reading direction. * * @param dev Indicates the USB device address. * @param ctrl Indicates the control data packet structure. - * @param data Indicates the read data or written. + * @param data Indicates the read or written data. * * @return Returns 0 if the operation is successful; returns a non-0 value if the operation fails. * @since 3.0 */ - static int32_t ControlTransfer(const UsbDev &dev, const UsbCtrlTransfer &ctrl, std::vector &data); + int32_t ControlTransfer(const UsbDev &dev, const UsbCtrlTransfer &ctrl, std::vector &data); /* * * @brief Reads data on a specified endpoint during interrupt transfer. The endpoint must be in the data reading direction. @@ -217,8 +230,7 @@ public: * @return Returns 0 if the operation is successful; returns a non-0 value if the operation fails. * @since 3.0 */ - static int32_t - InterruptTransferRead(const UsbDev &dev, const UsbPipe &pipe, int32_t timeout, std::vector &data); + int32_t InterruptTransferRead(const UsbDev &dev, const UsbPipe &pipe, int32_t timeout, std::vector &data); /* * * @brief Writes data on a specified endpoint during interrupt transfer. The endpoint must be in the data writing direction. @@ -231,8 +243,7 @@ public: * @return Returns 0 if the operation is successful; returns a non-0 value if the operation fails. * @since 3.0 */ - static int32_t - InterruptTransferWrite(const UsbDev &dev, const UsbPipe &pipe, int32_t timeout, std::vector &data); + int32_t InterruptTransferWrite(const UsbDev &dev, const UsbPipe &pipe, int32_t timeout, std::vector &data); /* * * @brief Reads data on a specified endpoint during isochronous transfer. The endpoint must be in the data reading direction. @@ -245,7 +256,7 @@ public: * @return Returns 0 if the operation is successful; returns a non-0 value if the operation fails. * @since 3.0 */ - static int32_t IsoTransferRead(const UsbDev &dev, const UsbPipe &pipe, int32_t timeout, std::vector &data); + int32_t IsoTransferRead(const UsbDev &dev, const UsbPipe &pipe, int32_t timeout, std::vector &data); /* * * @brief Writes data on a specified endpoint during isochronous transfer. The endpoint must be in the data writing direction. @@ -253,13 +264,12 @@ public: * @param dev Indicates the USB device address. * @param pipe Indicates the pipe of the USB device. * @param timeout Indicates the timeout duration. - * @param data Indicates the written data. + * @param data Indicates the read data. * * @return Returns 0 if the operation is successful; returns a non-0 value if the operation fails. * @since 3.0 */ - static int32_t - IsoTransferWrite(const UsbDev &dev, const UsbPipe &pipe, int32_t timeout, std::vector &data); + int32_t IsoTransferWrite(const UsbDev &dev, const UsbPipe &pipe, int32_t timeout, std::vector &data); /* * * @brief Sends or receives requests for isochronous transfer on a specified endpoint. The data transfer direction is determined by the endpoint direction. @@ -272,13 +282,11 @@ public: * @return Returns 0 if the operation is successful; returns a non-0 value if the operation fails. * @since 3.0 */ - static int32_t RequestQueue(const UsbDev &dev, - const UsbPipe &pipe, - const std::vector &clientData, - const std::vector &buffer); + int32_t RequestQueue(const UsbDev &dev, const UsbPipe &pipe, const std::vector &clientData, + const std::vector &buffer); /* * - * @brief Waits for the operation result of the requests for isochronous transfer in RequestQueue. + * @brief Waits for the operation result of the isochronous transfer request in RequestQueue. * * @param dev Indicates the USB device address. * @param clientData Indicates the client data. @@ -288,8 +296,8 @@ public: * @return Returns 0 if the operation is successful; returns a non-0 value if the operation fails. * @since 3.0 */ - static int32_t - RequestWait(const UsbDev &dev, std::vector &clientData, std::vector &buffer, int32_t timeout); + int32_t RequestWait(const UsbDev &dev, std::vector &clientData, std::vector &buffer, + int32_t timeout); /* * * @brief Cancels the data transfer requests to be processed. @@ -300,7 +308,7 @@ public: * @return Returns 0 if the operation is successful; returns a non-0 value if the operation fails. * @since 3.0 */ - static int32_t RequestCancel(const UsbDev &dev, const UsbPipe &pipe); + int32_t RequestCancel(const UsbDev &dev, const UsbPipe &pipe); /* * * @brief Obtains the list of functions (represented by bit field) supported by the current device. @@ -310,7 +318,7 @@ public: * @return Returns 0 if the operation is successful; returns a non-0 value if the operation fails. * @since 3.0 */ - static int32_t GetCurrentFunctions(int32_t &funcs); + int32_t GetCurrentFunctions(int32_t &funcs); /* * * @brief Sets the list of functions (represented by bit field) supported by the current device. @@ -320,7 +328,7 @@ public: * @return Returns 0 if the operation is successful; returns a non-0 value if the operation fails. * @since 3.0 */ - static int32_t SetCurrentFunctions(int32_t funcs); + int32_t SetCurrentFunctions(int32_t funcs); /* * * @brief Closes a USB device to release all system resources related to the device. @@ -332,7 +340,7 @@ public: * @return Returns 0 if the operation is successful; returns a non-0 value if the operation fails. * @since 3.0 */ - static int32_t SetPortRole(int32_t portId, int32_t powerRole, int32_t dataRole); + int32_t SetPortRole(int32_t portId, int32_t powerRole, int32_t dataRole); /* * * @brief Queries the current settings of a port. @@ -345,7 +353,7 @@ public: * @return Returns 0 if the operation is successful; returns a non-0 value if the operation fails. * @since 3.0 */ - static int32_t QueryPort(int32_t &portId, int32_t &powerRole, int32_t &dataRole, int32_t &mode); + int32_t QueryPort(int32_t &portId, int32_t &powerRole, int32_t &dataRole, int32_t &mode); /* * * @brief Binds a subscriber. @@ -355,71 +363,82 @@ public: * @return Returns 0 if the operation is successful; returns a non-0 value if the operation fails. * @since 3.0 */ - static ErrCode BindUsbdSubscriber(const sptr &subscriber); + int32_t BindUsbdSubscriber(const sptr &subscriber); /* * * @brief Unbinds a subscriber. * + * @param subscriber Indicates the subscriber. + * * @return Returns 0 if the operation is successful; returns a non-0 value if the operation fails. * @since 3.0 */ - static ErrCode UnbindUsbdSubscriber(); + int32_t UnbindUsbdSubscriber(const sptr &subscriber); /* * - * @brief Reads bulk data during isochronous transfer. This method is applicable to transfer of a huge amount of data. + * @brief Registers a callback for isochronous bulk transfer. * * @param dev Indicates the USB device address. * @param pipe Indicates the pipe of the USB device. - * @param length Indicates the length of the data to read. + * @param cb Indicates the reference to the callback. * * @return Returns 0 if the operation is successful; returns a non-0 value if the operation fails. * @since 3.0 */ - static int32_t BulkRequstDataSize(const UsbDev &dev, const UsbPipe &pipe, uint32_t &length); + int32_t RegBulkCallback(const UsbDev &dev, const UsbPipe &pipe, const sptr &cb); /* * - * @brief Obtains the data reading result. Use this method together with BulkRequstDataSize. + * @brief Unregisters the callback for isochronous bulk transfer. * * @param dev Indicates the USB device address. * @param pipe Indicates the pipe of the USB device. - * @param data Indicates the read data. * * @return Returns 0 if the operation is successful; returns a non-0 value if the operation fails. * @since 3.0 */ - static int32_t BulkReadData(const UsbDev &dev, const UsbPipe &pipe, std::vector &data); + int32_t UnRegBulkCallback(const UsbDev &dev, const UsbPipe &pipe); /* * - * @brief Writes bulk data during isochronous transfer. This method is applicable to transfer of a huge amount of data. + * @brief Reads data during isochronous bulk transfer. * * @param dev Indicates the USB device address. * @param pipe Indicates the pipe of the USB device. - * @param data Indicates the written data. + * @param ashmem Indicates the shared memory, which is used to store the read data. + * + * @return Returns 0 if the operation is successful; returns a non-0 value if the operation fails. + * @since 3.0 + */ + int32_t BulkRead(const UsbDev &dev, const UsbPipe &pipe, sptr &ashmem); + + /* * + * @brief Writes data during isochronous bulk transfer. + * + * @param dev Indicates the USB device address. + * @param pipe Indicates the pipe of the USB device. + * @param ashmem Indicates the shared memory, which is used to store the written data. * * @return Returns 0 if the operation is successful; returns a non-0 value if the operation fails. * @since 3.0 */ - static int32_t BulkWriteData(const UsbDev &dev, const UsbPipe &pipe, const std::vector &data); + int32_t BulkWrite(const UsbDev &dev, const UsbPipe &pipe, sptr &ashmem); /* * - * @brief Obtains the data writing status based on length. Use this method together with BulkWriteData. + * @brief Cancels the isochronous bulk transfer. The read and write operations on the current USB interface will be cancelled. * * @param dev Indicates the USB device address. * @param pipe Indicates the pipe of the USB device. - * @param length Indicates the length of the written data. * * @return Returns 0 if the operation is successful; returns a non-0 value if the operation fails. * @since 3.0 */ - static int32_t BulkGetWriteCompleteLength(const UsbDev &dev, const UsbPipe &pipe, uint32_t &length); + int32_t BulkCancel(const UsbDev &dev, const UsbPipe &pipe); private: - static void PrintBuffer(const char *title, const uint8_t *buffer, uint32_t length); - static int32_t SetDeviceMessage(MessageParcel &data, const UsbDev &dev); - static int32_t SetBufferMessage(MessageParcel &data, const std::vector &tdata); - static int32_t GetBufferMessage(MessageParcel &data, std::vector &tdata); - static sptr GetUsbdService(); - static ErrCode DoDispatch(uint32_t cmd, MessageParcel &data, MessageParcel &reply); + int32_t SetDeviceMessage(MessageParcel &data, const UsbDev &dev); + int32_t SetBufferMessage(MessageParcel &data, const std::vector &bufferData); + int32_t GetBufferMessage(MessageParcel &data, std::vector &bufferData); + sptr GetUsbdService(); + int32_t DoDispatch(uint32_t cmd, MessageParcel &data, MessageParcel &reply); }; } // namespace USB } // namespace OHOS -- Gitee