!929 【usb 服务子系统】开发指南，HDI接口说明

Merge pull request !929 from 吴成文/master

zh-cn/device-dev/apis/usb/usbd_client.h

+/*
+ * Copyright (c) 2021 Huawei Device Co., Ltd.
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+/**
+ * @addtogroup USB
+ * @{
+ *
+ * @brief Declares USB-related APIs, including the custom data types and functions
+ * used to obtain descriptors, interface objects, and request objects, and to submit requests.
+ *
+ * @since 3.0
+ * @version 1.0
+ */
+
+/**
+ * @file usbd_client.h
+ *
+ * @brief Defines the usbd Interface.
+ *
+ * @since 3.0
+ * @version 1.0
+ */
+
+#ifndef USBD_CLIENT_H
+#define USBD_CLIENT_H
+
+#include "usb_param.h"
+#include "usbd_subscriber.h"
+
+namespace OHOS {
+namespace USB {
+class UsbdClient {
+public:
+    /* *
+     * @brief 打开设备，建立连接
+     *
+     * @param dev usb设备地址信息
+     *
+     * @return 0 表示成功，其他返回值表示失败
+     * @since 3.0
+     */
+    static int32_t OpenDevice(const UsbDev &dev);
+
+    /* *
+     * @brief 关闭设备，释放与设备相关的所有系统资源
+     *
+     * @param dev usb设备地址信息
+     *
+     * @return 0 表示成功，其他返回值表示失败
+     * @since 3.0
+     */
+    static int32_t CloseDevice(const UsbDev &dev);
+
+    /* *
+     * @brief 获取设备描述符device
+     *
+     * @param dev usb设备地址信息
+     * @param decriptor usb设备描述符信息
+     *
+     * @return 0 表示成功，其他返回值表示失败
+     * @since 3.0
+     */
+    static int32_t GetDeviceDescriptor(const UsbDev &dev, std::vector<uint8_t> &decriptor);
+
+    /* *
+     * @brief 根据String ID获取设备的字符串描述符string
+     *
+     * @param dev usb设备地址信息
+     * @param descId usb的string ID
+     * @param decriptor 获取usb设备config信息
+     *
+     * @return 0 表示成功，其他返回值表示失败
+     * @since 3.0
+     */
+    static int32_t GetStringDescriptor(const UsbDev &dev, uint8_t descId, std::vector<uint8_t> &decriptor);
+
+    /* *
+     * @brief 根据config ID获取设备的配置描述符config
+     *
+     * @param dev usb设备地址信息
+     * @param descId usb的config ID
+     * @param decriptor 获取usb设备config信息
+     *
+     * @return 0 表示成功，其他返回值表示失败
+     * @since 3.0
+     */
+    static int32_t GetConfigDescriptor(const UsbDev &dev, uint8_t descId, std::vector<uint8_t> &decriptor);
+
+    /* *
+     * @brief 获取原始描述符
+     *
+     * @param dev usb设备地址信息
+     * @param decriptor usb设备原始描述符
+     *
+     * @return 0 表示成功，其他返回值表示失败
+     * @since 3.0
+     */
+    static int32_t GetRawDescriptor(const UsbDev &dev, std::vector<uint8_t> &decriptor);
+
+    /* *
+     * @brief 设置当前的config信息
+     *
+     * @param dev usb设备地址信息
+     * @param configIndex usb设备config信息
+     *
+     * @return 0 表示成功，其他返回值表示失败
+     * @since 3.0
+     */
+    static int32_t SetConfig(const UsbDev &dev, uint8_t configIndex);
+
+    /* *
+     * @brief 获取当前的config信息
+     *
+     * @param dev usb设备地址信息
+     * @param configIndex usb设备config信息
+     *
+     * @return 0 表示成功，其他返回值表示失败
+     * @since 3.0
+     */
+    static int32_t GetConfig(const UsbDev &dev, uint8_t &configIndex);
+
+    /* *
+     * @brief 打开接口，并申明独占接口，必须在数据传输前执行
+     *
+     * @param dev usb设备地址信息
+     * @param interfaceid usb设备interface ID
+     *
+     * @return 0 表示成功，其他返回值表示失败
+     * @since 3.0
+     */
+    static int32_t ClaimInterface(const UsbDev &dev, uint8_t interfaceid);
+
+    /* *
+     * @brief 关闭接口，释放接口的占用，在停止数据传输后执行
+     *
+     * @param dev usb设备地址信息
+     * @param interfaceid usb设备interface ID
+     *
+     * @return 0 表示成功，其他返回值表示失败
+     * @since 3.0
+     */
+    static int32_t ReleaseInterface(const UsbDev &dev, uint8_t interfaceid);
+
+    /* *
+     * @brief 设置指定接口的备选设置，用于在具有相同ID但不同备用设置的两个接口之间进行选择
+     *
+     * @param dev usb设备地址信息
+     * @param interfaceid usb设备interface ID
+     * @param altIndex interface 的 AlternateSetting 信息
+     *
+     * @return 0 表示成功，其他返回值表示失败
+     * @since 3.0
+     */
+    static int32_t SetInterface(const UsbDev &dev, uint8_t interfaceid, uint8_t altIndex);
+
+    /* *
+     * @brief 在给定端点上执行批量数据读取，返回读取的数据和长度，端点方向必须为数据读取可以设置超时时间
+     *
+     * @param dev usb设备地址信息
+     * @param pipe usb设备pipe信息
+     * @param timeout 超时时间
+     * @param data 获取写入的数据
+     *
+     * @return 0 表示成功，其他返回值表示失败
+     * @since 3.0
+     */
+    static int32_t
+        BulkTransferRead(const UsbDev &dev, const UsbPipe &pipe, int32_t timeout, std::vector<uint8_t> &data);
+
+    /* *
+     * @brief 在给定端点上执行批量数据写入，返回读取的数据和长度，端点方向必须为数据写入
+     *
+     * @param dev usb设备地址信息
+     * @param pipe usb设备pipe信息
+     * @param timeout 超时时间
+     * @param data 写入的数据
+     *
+     * @return 0 表示成功，其他返回值表示失败
+     * @since 3.0
+     */
+    static int32_t
+        BulkTransferWrite(const UsbDev &dev, const UsbPipe &pipe, int32_t timeout, const std::vector<uint8_t> &data);
+
+    /* *
+     * @brief 对此设备执行端点零的控制事务，传输方向由请求类型决定。如果requestType＆
+     * USB_ENDPOINT_DIR_MASK是USB_DIR_OUT，则传输是写入，如果是USB_DIR_IN，则传输是读取。
+     *
+     * @param dev usb设备地址信息
+     * @param ctrl usb设备控制数据包结构
+     * @param data 读取/写入 的数据
+     *
+     * @return 0 表示成功，其他返回值表示失败
+     * @since 3.0
+     */
+    static int32_t ControlTransfer(const UsbDev &dev, const UsbCtrlTransfer &ctrl, std::vector<uint8_t> &data);
+
+    /* *
+     * @brief 在给定端点上执行中断数据读取，返回读取的数据和长度，端点方向必须为数据读取
+     *
+     * @param dev usb设备地址信息
+     * @param pipe usb设备pipe信息
+     * @param timeout 超时时间
+     * @param data 读取的数据
+     *
+     * @return 0 表示成功，其他返回值表示失败
+     * @since 3.0
+     */
+    static int32_t
+        InterruptTransferRead(const UsbDev &dev, const UsbPipe &pipe, int32_t timeout, std::vector<uint8_t> &data);
+
+    /* *
+     * @brief 在给定端点上执行中断数据写入，返回读取的数据和长度，端点方向必须为数据写入
+     *
+     * @param dev usb设备地址信息
+     * @param pipe usb设备pipe信息
+     * @param timeout 超时时间
+     * @param data 读取的数据
+     *
+     * @return 0 表示成功，其他返回值表示失败
+     * @since 3.0
+     */
+    static int32_t
+        InterruptTransferWrite(const UsbDev &dev, const UsbPipe &pipe, int32_t timeout, std::vector<uint8_t> &data);
+
+    /* *
+     * @brief 在给定端点上执行等时数据读取，返回读取的数据和长度，端点方向必须为数据读取
+     *
+     * @param dev usb设备地址信息
+     * @param pipe usb设备pipe信息
+     * @param timeout 超时时间
+     * @param data 读取的数据
+     *
+     * @return 0 表示成功，其他返回值表示失败
+     * @since 3.0
+     */
+    static int32_t IsoTransferRead(const UsbDev &dev, const UsbPipe &pipe, int32_t timeout, std::vector<uint8_t> &data);
+
+    /* *
+     * @brief 在给定端点上执行等时数据写入，返回读取的数据和长度，端点方向必须为数据写入
+     *
+     * @param dev usb设备地址信息
+     * @param pipe usb设备pipe信息
+     * @param timeout 超时时间
+     * @param data 读取的数据
+     *
+     * @return 0 表示成功，其他返回值表示失败
+     * @since 3.0
+     */
+    static int32_t
+        IsoTransferWrite(const UsbDev &dev, const UsbPipe &pipe, int32_t timeout, std::vector<uint8_t> &data);
+
+    /* *
+     * @brief 将指定的端点进行异步数据发送或者接收请求，数据传输方向由端点方向决定
+     *
+     * @param dev usb设备地址信息
+     * @param pipe usb设备pipe信息
+     * @param clientData 用户数据
+     * @param buffer 传输数据
+     *
+     * @return 0 表示成功，其他返回值表示失败
+     * @since 3.0
+     */
+    static int32_t RequestQueue(const UsbDev &dev,
+                                const UsbPipe &pipe,
+                                const std::vector<uint8_t> &clientData,
+                                const std::vector<uint8_t> &buffer);
+
+    /* *
+     * @brief 等待RequestQueue异步请求的操作结果
+     *
+     * @param dev usb设备地址信息
+     * @param clientData 用户数据
+     * @param buffer 传输数据
+     * @param timeout 超时时间
+     *
+     * @return 0 表示成功，其他返回值表示失败
+     * @since 3.0
+     */
+    static int32_t
+        RequestWait(const UsbDev &dev, std::vector<uint8_t> &clientData, std::vector<uint8_t> &buffer, int32_t timeout);
+
+    /* *
+     * @brief 取消待处理的数据请求
+     *
+     * @param dev usb设备地址信息
+     * @param pipe usb设备pipe信息
+     *
+     * @return 0 表示成功，其他返回值表示失败
+     * @since 3.0
+     */
+    static int32_t RequestCancel(const UsbDev &dev, const UsbPipe &pipe);
+
+    /* *
+     * @brief 获取从设备支持的功能列表（按位域表示）（从设备）
+     *
+     * @param funcs 获取当前设备的function的值
+     *
+     * @return 0 表示成功，其他返回值表示失败
+     * @since 3.0
+     */
+    static int32_t GetCurrentFunctions(int32_t &funcs);
+
+    /* *
+     * @brief 设置从设备支持的功能列表（按位域表示）（从设备）
+     *
+     * @param funcs 传入设备支持的function的值
+     *
+     * @return 0 表示成功，其他返回值表示失败
+     * @since 3.0
+     */
+    static int32_t SetCurrentFunctions(int32_t funcs);
+
+    /* *
+     * @brief 关闭设备，释放与设备相关的所有系统资源
+     *
+     * @param portId port接口 ID
+     * @param powerRole 电源角色的值
+     * @param dataRole 数据角色的值
+     *
+     * @return 0 表示成功，其他返回值表示失败
+     * @since 3.0
+     */
+    static int32_t SetPortRole(int32_t portId, int32_t powerRole, int32_t dataRole);
+
+    /* *
+     * @brief 查询port端口的当前设置
+     *
+     * @param portId port接口 ID
+     * @param powerRole 电源角色的值
+     * @param dataRole 数据角色的值
+     * @param mode 模式的值
+     *
+     * @return 0 表示成功，其他返回值表示失败
+     * @since 3.0
+     */
+    static int32_t QueryPort(int32_t &portId, int32_t &powerRole, int32_t &dataRole, int32_t &mode);
+
+    /* *
+     * @brief 绑定订阅者
+     *
+     * @param subscriber 订阅者信息
+     *
+     * @return 0 表示成功，其他返回值表示失败
+     * @since 3.0
+     */
+    static ErrCode BindUsbdSubscriber(const sptr<UsbdSubscriber> &subscriber);
+
+    /* *
+     * @brief 解绑订阅者
+     *
+     * @return 0 表示成功，其他返回值表示失败
+     * @since 3.0
+     */
+    static ErrCode UnbindUsbdSubscriber();
+
+    /* *
+     * @brief 异步批量读取数据，传输大量数据时使用
+     *
+     * @param dev usb设备地址信息
+     * @param pipe usb设备pipe信息
+     * @param length 打算以什么长度读取数据
+     *
+     * @return 0 表示成功，其他返回值表示失败
+     * @since 3.0
+     */
+    static int32_t BulkRequstDataSize(const UsbDev &dev, const UsbPipe &pipe, uint32_t &length);
+
+    /* *
+     * @brief 与BulkRequstDataSize配合使用，获取读取结果
+     *
+     * @param dev usb设备地址信息
+     * @param pipe usb设备pipe信息
+     * @param data 读取到的数据
+     *
+     * @return 0 表示成功，其他返回值表示失败
+     * @since 3.0
+     */
+    static int32_t BulkReadData(const UsbDev &dev, const UsbPipe &pipe, std::vector<uint8_t> &data);
+
+    /* *
+     * @brief 异步批量写数据，传输大量数据时使用
+     *
+     * @param dev usb设备地址信息
+     * @param pipe usb设备pipe信息
+     * @param data 要写入的数据
+     *
+     * @return 0 表示成功，其他返回值表示失败
+     * @since 3.0
+     */
+    static int32_t BulkWriteData(const UsbDev &dev, const UsbPipe &pipe, const std::vector<uint8_t> &data);
+
+    /* *
+     * @brief 与BulkWriteData配合使用，获取写入状态，由length描述
+     *
+     * @param dev usb设备地址信息
+     * @param pipe usb设备pipe信息
+     * @param length 已经写入的数据长度
+     *
+     * @return 0 表示成功，其他返回值表示失败
+     * @since 3.0
+     */
+    static int32_t BulkGetWriteCompleteLength(const UsbDev &dev, const UsbPipe &pipe, uint32_t &length);
+
+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<uint8_t> &tdata);
+    static int32_t GetBufferMessage(MessageParcel &data, std::vector<uint8_t> &tdata);
+    static sptr<IRemoteObject> GetUsbdService();
+    static ErrCode DoDispatch(uint32_t cmd, MessageParcel &data, MessageParcel &reply);
+};
+} // namespace USB
+} // namespace OHOS
+#endif // USBD_CLIENT_H

zh-cn/device-dev/subsystems/Readme-CN.md

@@ -48,6 +48,10 @@
   - [Sensor服务子系概述](subsys-sensor-overview.md)
   - [Sensor服务子系使用指导](subsys-sensor-guide.md)
   - [Sensor服务子系使用实例](subsys-sensor-demo.md)
+- [Usb服务子系统](subsys-usbservice.md)
+  - [USB服务子系统概述](subsys-usbservice-overview.md)
+  - [USB服务子系统使用指导](subsys-usbservice-guide.md)
+  - [USB服务子系统使用实例](subsys-usbservice-demo.md)
 - [用户程序框架](subsys-application-framework.md)
   - [概述](subsys-application-framework-overview.md)
   - [搭建环境](subsys-application-framework-envbuild.md)

zh-cn/device-dev/subsystems/subsys-usbservice-demo.md

+# USB服务子系使用实例<a name="ZH-CN_TOPIC_0000001092792986"></a>
+
+
+```
+#include <cstdio>
+#include <iostream>
+#include <map>
+#include <mutex>
+#include <sstream>
+#include <sys/time.h>
+#include "if_system_ability_manager.h"
+#include "ipc_skeleton.h"
+#include "iremote_object.h"
+#include "iservice_registry.h"
+#include "iusb_srv.h"
+#include "string_ex.h"
+#include "system_ability_definition.h"
+#include "usb_common.h"
+#include "usb_device.h"
+#include "usb_errors.h"
+#include "usb_request.h"
+#include "usb_server_proxy.h"
+#include "usb_srv_client.h"
+
+const int32_t REQUESTYPE = ((1 << 7) | (0 << 5) | (0 & 0x1f));
+const int32_t REQUESTCMD = 6;
+const int32_t VALUE = (2 << 8) + 0;
+const int32_t TIMEOUT = 5000;
+const int32_t ITFCLASS = 10;
+const int32_t PRAMATYPE = 2;
+const int32_t BUFFERLENGTH = 21;
+
+void GetType(OHOS::USB::USBEndpoint &tep, OHOS::USB::USBEndpoint &outEp, bool &outEpFlg)
+{
+    if ((tep.GetType() == PRAMATYPE)) {
+        if (tep.GetDirection() == 0) {
+            outEp = tep;
+            outEpFlg = true;
+        }
+    }
+}
+
+bool SelectEndpoint(OHOS::USB::USBConfig config,
+                    std::vector<OHOS::USB::UsbInterface> interfaces,
+                    OHOS::USB::UsbInterface &interface,
+                    OHOS::USB::USBEndpoint &outEp,
+                    bool &outEpFlg)
+{
+    for (int32_t i = 0; i < config.GetInterfaceCount(); ++i) {
+        OHOS::USB::UsbInterface tif = interfaces[i];
+        std::vector<OHOS::USB::USBEndpoint> mEndpoints = tif.GetEndpoints();
+        for (int32_t j = 0; j < tif.GetEndpointCount(); ++j) {
+            OHOS::USB::USBEndpoint tep = mEndpoints[j];
+            if ((tif.GetClass() == ITFCLASS) && (tif.GetSubClass() == 0) && (tif.GetProtocol() == PRAMATYPE)) {
+                GetType(tep, outEp, outEpFlg);
+            }
+        }
+        if (outEpFlg) {
+            interface = interfaces[i];
+            return true;
+        }
+        std::cout << std::endl;
+    }
+    return false;
+}
+
+int OpenDeviceTest(OHOS::USB::UsbSrvClient &Instran, OHOS::USB::UsbDevice device, OHOS::USB::USBDevicePipe &pip)
+{
+    int ret = Instran.RequestRight(device.GetName());
+    std::cout << "device RequestRight ret = " << ret << std::endl;
+    if (0 != ret) {
+        std::cout << "device RequestRight failed = " << ret << std::endl;
+    }
+    ret = Instran.OpenDevice(device, pip);
+    return ret;
+}
+
+int CtrTransferTest(OHOS::USB::UsbSrvClient &Instran, OHOS::USB::USBDevicePipe &pip)
+{
+    std::cout << "usb_device_test : << Control Transfer >> " << std::endl;
+    std::vector<uint8_t> vData;
+    const OHOS::USB::UsbCtrlTransfer tctrl = {REQUESTYPE, REQUESTCMD, VALUE, 0, TIMEOUT};
+    int ret = Instran.ControlTransfer(pip, tctrl, vData);
+    if (ret != 0) {
+        std::cout << "control message read failed width ret = " << ret << std::endl;
+    } else {
+    }
+        std::cout << "control message read success" << std::endl;
+
+    return ret;
+}
+
+int ClaimTest(OHOS::USB::UsbSrvClient &Instran,
+              OHOS::USB::USBDevicePipe &pip,
+              OHOS::USB::UsbInterface &interface,
+              bool interfaceFlg)
+{
+    if (interfaceFlg) {
+        std::cout << "ClaimInterface InterfaceInfo:" << interface.ToString() << std::endl;
+        int ret = Instran.ClaimInterface(pip, interface, true);
+        if (ret != 0) {
+            std::cout << "ClaimInterface failed width ret = " << ret << std::endl;
+        } else {
+            std::cout << "ClaimInterface success" << std::endl;
+        }
+    }
+    return 0;
+}
+
+int BulkTransferTest(OHOS::USB::UsbSrvClient &Instran,
+                     OHOS::USB::USBDevicePipe &pip,
+                     OHOS::USB::USBEndpoint &outEp,
+                     bool interfaceFlg,
+                     bool outEpFlg)
+{
+    if (interfaceFlg) {
+        std::cout << "usb_device_test : << Bulk transfer start >> " << std::endl;
+        if (outEpFlg) {
+            uint8_t buffer[50] = "hello world 123456789";
+            std::vector<uint8_t> vData(buffer, buffer + BUFFERLENGTH);
+            int ret = Instran.BulkTransfer(pip, outEp, vData, TIMEOUT);
+            if (ret != 0) {
+                std::cout << "Bulk transfer write failed width ret = " << ret << std::endl;
+            } else {
+                std::cout << "Bulk transfer write success" << std::endl;
+            }
+            return ret;
+        }
+    }
+    return 0;
+}
+
+int main(int argc, char **argv)
+{
+    std::cout << "usb_device_test " << std::endl;
+    static OHOS::USB::UsbSrvClient &Instran = OHOS::USB::UsbSrvClient::GetInstance();
+    // GetDevices
+    std::vector<OHOS::USB::UsbDevice> deviceList;
+    int32_t ret = Instran.GetDevices(deviceList);
+    if (ret != 0) {
+        return OHOS::USB::UEC_SERVICE_INVALID_VALUE;
+    }
+    if (deviceList.empty()) {
+        return OHOS::USB::UEC_SERVICE_INVALID_VALUE;
+    }
+
+    OHOS::USB::UsbDevice device = deviceList[0];
+    std::vector<OHOS::USB::USBConfig> configs = device.GetConfigs();
+    OHOS::USB::USBConfig config = configs[0];
+    std::vector<OHOS::USB::UsbInterface> interfaces = config.GetInterfaces();
+    OHOS::USB::UsbInterface interface;
+    OHOS::USB::USBEndpoint outEp;
+    bool interfaceFlg = false;
+    bool outEpFlg = false;
+    interfaceFlg = SelectEndpoint(config, interfaces, interface, outEp, outEpFlg);
+
+    // OpenDevice
+    std::cout << "usb_device_test : << OpenDevice >> test begin -> " << std::endl;
+    OHOS::USB::USBDevicePipe pip;
+    ret = OpenDeviceTest(Instran, device, pip);
+    if (ret != 0) {
+        return OHOS::USB::UEC_SERVICE_INVALID_VALUE;
+    }
+
+    // ControlTransfer
+    CtrTransferTest(Instran, pip);
+
+    // ClaimInterface
+    ClaimTest(Instran, pip, interface, interfaceFlg);
+
+    // BulkTransferWrite
+    BulkTransferTest(Instran, pip, outEp, interfaceFlg, outEpFlg);
+
+    // CloseDevice
+    std::cout << "usb_device_test : << Close Device >> " << std::endl;
+    ret = Instran.Close(pip);
+    if (ret == 0) {
+        std::cout << "Close device failed width ret = " << ret << std::endl;
+        return OHOS::USB::UEC_SERVICE_INVALID_VALUE;
+    } else {
+        std::cout << "Close Device success" << std::endl;
+    }
+    return 0;
+}
+```
+
+

zh-cn/device-dev/subsystems/subsys-usbservice-guide.md

+# USB服务子系统使用指导<a name="ZH-CN_TOPIC_0000001077367159"></a>
+
+-   [使用步骤](#section18816105182315)
+
+下面使用步骤以bulktransfer为例。
+
+## 使用步骤<a name="section18816105182315"></a>
+
+1.  获取usb service实例
+
+```
+static OHOS::USB::UsbSrvClient &g_usbClient = OHOS::USB::UsbSrvClient::GetInstance();
+```
+
+2.  获取usb设备列表
+
+```
+std::vector<OHOS::USB::UsbDevice> deviceList;
+int32_t ret = g_usbClient.GetDevices(deviceList);
+```
+
+3.  申请设备权限
+
+```
+int32_t ret = g_usbClient.RequestRight(device.GetName());
+```
+
+4.  打开设备
+
+```
+USBDevicePipe pip;
+int32_t et = g_usbClient.OpenDevice(device, pip);
+```
+
+5.  配置设备接口
+
+```
+ret = g_usbClient.ClaimInterface(pip, interface, true);
+interface为deviceList中device的interface。
+```
+
+6.  数据传输
+
+```
+srvClient.BulkTransfer(pipe, endpoint, vdata, timeout);
+```
+pipe为打开设备后的数据传输通道，endpoint为device中数据传输的端点，vdata是需要传输或读取的二进制数据块，timeout为传输超时时长.
+
+7.  关闭设备
+
+```
+ret = g_usbClient.Close(pip);
+```

zh-cn/device-dev/subsystems/subsys-usbservice-overview.md

+# USB服务子系统概述<a name="ZH-CN_TOPIC_0000001092893508"></a>
+
+-   [概述](#section175431838101617)
+-   [接口说明](#section83365421647)
+    -   [Host部分](#section83365421658)
+    -   [Device部分](#section83365421669)
+    -   [Port部分](#section83365421670)
+
+## 概述<a name="section175431838101617"></a>
+
+  USB设备分为Host设备（主机设备）和Device设备（从设备）。用户可通过Port Service来根据实际业务把运行OpenHarmony的设备切换为Host设备或者Device设备。目前在Host模式下，支持获取USB设备列表，USB设备权限管理，控制传输、批量传输的同异步数据传输等，在Device模式下，支持HDC（调试）、ACM（串口）、ECM（网口）等功能的切换。
+
+**图1**  USB服务架构图
+
+![](figure/USB服务架构图.png)
+
+-   USB FWK/API：基于USB Service服务，使用NAPI技术，向上提供JS接口。
+-   USB Service：使用C++代码实现，包含Host、Device、Port三个模块。基于HDI的接口，主要实现USB设备的列表管理、Function 管理、Port管理、USB设备权限管理等功能。
+-   USB HAL：使用C代码实现，基于Host SDK和Device SDK，封装了对USB设备的基本操作，向上提供C++接口，同时通过HDF框架接收内核上报的信息。
+
+## 接口说明<a name="section83365421647"></a>
+
+- ### Host部分<a name="section83365421658"></a>
+
+<a name="table1513255710559"></a>
+<table><thead align="left"><tr id="row171321857155517"><th class="cellrowborder" valign="top" width="10.721072107210723%" id="mcps1.2.4.1.1"><p id="p6132957115511"><a name="p6132957115511"></a><a name="p6132957115511"></a>头文件</p>
+</th>
+<th class="cellrowborder" valign="top" width="66.36663666366637%" id="mcps1.2.4.1.2"><p id="p14132125715552"><a name="p14132125715552"></a><a name="p14132125715552"></a>接口名称</p>
+</th>
+<th class="cellrowborder" valign="top" width="22.912291229122914%" id="mcps1.2.4.1.3"><p id="p18132205755516"><a name="p18132205755516"></a><a name="p18132205755516"></a>功能描述</p>
+</th>
+</tr>
+</thead>
+<tbody><tr id="row13132357165514"><td class="cellrowborder" rowspan="16" valign="top" width="10.721072107210723%" headers="mcps1.2.4.1.1 "><p id="p15132185775510"><a name="p15132185775510"></a><a name="p15132185775510"></a>usb_srv_client.h</p>
+<p id="p18132157175510"><a name="p18132157175510"></a><a name="p18132157175510"></a></p>
+<p id="p2133757135510"><a name="p2133757135510"></a><a name="p2133757135510"></a></p>
+</td>
+<td class="cellrowborder" valign="top" width="66.36663666366637%" headers="mcps1.2.4.1.1 "><p id="p1213365714550"><a name="p1213365714550"></a><a name="p1213365714550"></a>int32_t OpenDevice(const UsbDevice &device, USBDevicePipe &pip);</p>
+</td>
+<td class="cellrowborder" valign="top" headers="mcps1.2.4.1.2 "><p id="p201331557185512"><a name="p201331557185512"></a><a name="p201331557185512"></a>打开USB设备，建立连接</p>
+</td>
+</tr>
+<tr id="row171331657185514"><td class="cellrowborder" valign="top" headers="mcps1.2.4.1.1 "><p id="p913305715553"><a name="p913305715553"></a><a name="p913305715553"></a>int32_t HasRight(std::string deviceName);</p>
+</td>
+<td class="cellrowborder" valign="top" headers="mcps1.2.4.1.2 "><p id="p161332570553"><a name="p161332570553"></a><a name="p161332570553"></a>判断是否有权访问设备</p>
+</td>
+</tr>
+<tr id="row41331557165518"><td class="cellrowborder" valign="top" headers="mcps1.2.4.1.1 "><p id="p6133145713559"><a name="p6133145713559"></a><a name="p6133145713559"></a>int32_t RequestRight(std::string deviceName);</p>
+</td>
+<td class="cellrowborder" valign="top" headers="mcps1.2.4.1.2 "><p id="p131331557175510"><a name="p131331557175510"></a><a name="p131331557175510"></a>请求给定软件包的临时权限以访问设备</p>
+</td>
+</tr>
+<tr id="row77021769584"><td class="cellrowborder" valign="top" headers="mcps1.2.4.1.1 "><p id="p77031566584"><a name="p77031566584"></a><a name="p77031566584"></a>int32_t GetDevices(std::vector<UsbDevice> &deviceList);</p>
+</td>
+<td class="cellrowborder" valign="top" headers="mcps1.2.4.1.2 "><p id="p1470315695811"><a name="p1470315695811"></a><a name="p1470315695811"></a>获取USB设备列表</p>
+</td>
+</tr>
+<tr id="row71857914585"><td class="cellrowborder" valign="top" headers="mcps1.2.4.1.1 "><p id="p1318619155811"><a name="p1318619155811"></a><a name="p1318619155811"></a>int32_t ClaimInterface(USBDevicePipe &pip, const UsbInterface &interface, bool force);</p>
+</td>
+<td class="cellrowborder" valign="top" headers="mcps1.2.4.1.2 "><p id="p1186597589"><a name="p1186597589"></a><a name="p1186597589"></a>打开接口，并申明独占接口，必须在数据传输前执行</p>
+</td>
+</tr>
+<tr id="row18831119115815"><td class="cellrowborder" valign="top" headers="mcps1.2.4.1.1 "><p id="p48323975814"><a name="p48323975814"></a><a name="p48323975814"></a>int32_t ReleaseInterface(USBDevicePipe &pip, const UsbInterface &interface);</p>
+</td>
+<td class="cellrowborder" valign="top" headers="mcps1.2.4.1.2 "><p id="p15832129135813"><a name="p15832129135813"></a><a name="p15832129135813"></a>关闭接口，释放接口的占用，在停止数据传输后执行</p>
+</td>
+</tr>
+<tr id="row71857914585"><td class="cellrowborder" valign="top" headers="mcps1.2.4.1.1 "><p id="p1318619155811"><a name="p1318619155811"></a><a name="p1318619155811"></a>int32_t BulkTransfer(USBDevicePipe &pip, const USBEndpoint &endpoint, std::vector<uint8_t> &vdata, int32_t timeout);</p>
+</td>
+<td class="cellrowborder" valign="top" headers="mcps1.2.4.1.2 "><p id="p1186597589"><a name="p1186597589"></a><a name="p1186597589"></a>在给定端点上执行批量数据传输， 返回读取或发送的数据长度，通过端点方向确定读取或发送数据</p>
+</td>
+</tr>
+<tr id="row18831119115815"><td class="cellrowborder" valign="top" headers="mcps1.2.4.1.1 "><p id="p48323975814"><a name="p48323975814"></a><a name="p48323975814"></a>int32_t ControlTransfer(USBDevicePipe &pip, const UsbCtrlTransfer &ctrl, std::vector<uint8_t> &vdata);</p>
+</td>
+<td class="cellrowborder" valign="top" headers="mcps1.2.4.1.2 "><p id="p15832129135813"><a name="p15832129135813"></a><a name="p15832129135813"></a>对此设备执行端点零的控制事务，传输方向由请求类型决定</p>
+</td>
+</tr>
+<tr id="row71857914585"><td class="cellrowborder" valign="top" headers="mcps1.2.4.1.1 "><p id="p1318619155811"><a name="p1318619155811"></a><a name="p1318619155811"></a>int32_t SetConfiguration(USBDevicePipe &pip, const USBConfig &config);</p>
+</td>
+<td class="cellrowborder" valign="top" headers="mcps1.2.4.1.2 "><p id="p1186597589"><a name="p1186597589"></a><a name="p1186597589"></a>设置设备当前使用的配置，通过配置值进行指定</p>
+</td>
+</tr>
+<tr id="row18831119115815"><td class="cellrowborder" valign="top" headers="mcps1.2.4.1.1 "><p id="p48323975814"><a name="p48323975814"></a><a name="p48323975814"></a>int32_t SetInterface(USBDevicePipe &pipe, const UsbInterface &interface);</p>
+</td>
+<td class="cellrowborder" valign="top" headers="mcps1.2.4.1.2 "><p id="p15832129135813"><a name="p15832129135813"></a><a name="p15832129135813"></a>设置指定接口的备选设置，用于在具有相同ID但不同备用设置的两个接口之间进行选择</p>
+</td>
+</tr>
+<tr id="row71857914585"><td class="cellrowborder" valign="top" headers="mcps1.2.4.1.1 "><p id="p1318619155811"><a name="p1318619155811"></a><a name="p1318619155811"></a>int32_t GetRawDescriptors(std::vector<uint8_t> &vdata);</p>
+</td>
+<td class="cellrowborder" valign="top" headers="mcps1.2.4.1.2 "><p id="p1186597589"><a name="p1186597589"></a><a name="p1186597589"></a>获取原始的USB描述符</p>
+</td>
+</tr>
+<tr id="row18831119115815"><td class="cellrowborder" valign="top" headers="mcps1.2.4.1.1 "><p id="p48323975814"><a name="p48323975814"></a><a name="p48323975814"></a>int32_t GetFileDescriptor();</p>
+</td>
+<td class="cellrowborder" valign="top" headers="mcps1.2.4.1.2 "><p id="p15832129135813"><a name="p15832129135813"></a><a name="p15832129135813"></a>获取文件描述符</p>
+</td>
+</tr>
+<tr id="row71857914585"><td class="cellrowborder" valign="top" headers="mcps1.2.4.1.1 "><p id="p1318619155811"><a name="p1318619155811"></a><a name="p1318619155811"></a>bool Close(const USBDevicePipe &pip);</p>
+</td>
+<td class="cellrowborder" valign="top" headers="mcps1.2.4.1.2 "><p id="p1186597589"><a name="p1186597589"></a><a name="p1186597589"></a>关闭设备，释放与设备相关的所有系统资源</p>
+</td>
+</tr>
+<tr id="row18831119115815"><td class="cellrowborder" valign="top" headers="mcps1.2.4.1.1 "><p id="p48323975814"><a name="p48323975814"></a><a name="p48323975814"></a>int32_t PipeRequestWait(USBDevicePipe &pip, int64_t timeout, UsbRequest &req);</p>
+</td>
+<td class="cellrowborder" valign="top" headers="mcps1.2.4.1.2 "><p id="p15832129135813"><a name="p15832129135813"></a><a name="p15832129135813"></a>获取异步传输结果</p>
+</td>
+</tr>
+<tr id="row71857914585"><td class="cellrowborder" valign="top" headers="mcps1.2.4.1.1 "><p id="p1318619155811"><a name="p1318619155811"></a><a name="p1318619155811"></a>int32_t RequestInitialize(UsbRequest &request);</p>
+</td>
+<td class="cellrowborder" valign="top" headers="mcps1.2.4.1.2 "><p id="p1186597589"><a name="p1186597589"></a><a name="p1186597589"></a>初始化异步数据传输request</p>
+</td>
+</tr>
+<tr id="row18831119115815"><td class="cellrowborder" valign="top" headers="mcps1.2.4.1.1 "><p id="p48323975814"><a name="p48323975814"></a><a name="p48323975814"></a>int32_t RequestFree(UsbRequest &request);</p>
+</td>
+<td class="cellrowborder" valign="top" headers="mcps1.2.4.1.2 "><p id="p15832129135813"><a name="p15832129135813"></a><a name="p15832129135813"></a>释放异步数据传输request</p>
+</td>
+</tr>
+<tr id="row1513316577554"><td class="cellrowborder" rowspan="27" valign="top" headers="mcps1.2.4.1.1 ">
+<td class="cellrowborder" valign="top" width="66.36663666366637%" headers="mcps1.2.4.1.2 "><p id="p105259109581"><a name="p105259109581"></a><a name="p105259109581"></a>int32_t RequestAbort(UsbRequest &request);</p>
+</td>
+<td class="cellrowborder" valign="top" headers="mcps1.2.4.1.3 "><p id="p752531095814"><a name="p752531095814"></a><a name="p752531095814"></a>取消待处理的数据请求</p>
+</td>
+</tr>
+<tr id="row172902161193"><td class="cellrowborder" valign="top" headers="mcps1.2.4.1.1 "><p id="p16290141681918"><a name="p16290141681918"></a><a name="p16290141681918"></a>int32_t RequestQueue(UsbRequest &request);</p>
+</td>
+<td class="cellrowborder" valign="top" headers="mcps1.2.4.1.2 "><p id="p1929141611198"><a name="p1929141611198"></a><a name="p1929141611198"></a>将指定的端点进行异步数据发送或者接收请求，数据传输方向由端点方向决定</p>
+</td>
+</tr>
+<tr id="row172902161193"><td class="cellrowborder" valign="top" headers="mcps1.2.4.1.1 "><p id="p16290141681918"><a name="p16290141681918"></a><a name="p16290141681918"></a>int32_t BulkRequstDataSize(const UsbDev &dev, const UsbPipe &pipe, uint32_t &length);</p>
+</td>
+<td class="cellrowborder" valign="top" headers="mcps1.2.4.1.2 "><p id="p1929141611198"><a name="p1929141611198"></a><a name="p1929141611198"></a>异步批量读取数据，传输大量数据时使用</p>
+</td>
+</tr>
+<tr id="row172902161193"><td class="cellrowborder" valign="top" headers="mcps1.2.4.1.1 "><p id="p16290141681918"><a name="p16290141681918"></a><a name="p16290141681918"></a>int32_t BulkReadData(const UsbDev &dev, const UsbPipe &pipe, std::vector<uint8_t> &data);</p>
+</td>
+<td class="cellrowborder" valign="top" headers="mcps1.2.4.1.2 "><p id="p1929141611198"><a name="p1929141611198"></a><a name="p1929141611198"></a>与BulkReadData配合使用，获取读取结果</p>
+</td>
+</tr>
+<tr id="row172902161193"><td class="cellrowborder" valign="top" headers="mcps1.2.4.1.1 "><p id="p16290141681918"><a name="p16290141681918"></a><a name="p16290141681918"></a>int32_t BulkWriteData(const UsbDev &dev, const UsbPipe &pipe, const std::vector<uint8_t> &data);</p>
+</td>
+<td class="cellrowborder" valign="top" headers="mcps1.2.4.1.2 "><p id="p1929141611198"><a name="p1929141611198"></a><a name="p1929141611198"></a>异步批量写数据，传输大量数据时使用</p>
+</td>
+</tr>
+<tr id="row172902161193"><td class="cellrowborder" valign="top" headers="mcps1.2.4.1.1 "><p id="p16290141681918"><a name="p16290141681918"></a><a name="p16290141681918"></a>int32_t BulkGetWriteCompleteLength(const UsbDev &dev, const UsbPipe &pipe, uint32_t &length);</p>
+</td>
+<td class="cellrowborder" valign="top" headers="mcps1.2.4.1.2 "><p id="p1929141611198"><a name="p1929141611198"></a><a name="p1929141611198"></a>与BulkWriteData配合使用，获取写入状态，由length描述</p>
+</td>
+</tr>
+</tbody>
+</table>
+
+- ### Device部分<a name="section83365421669"></a>
+
+<a name="table1513255710559"></a>
+<table><thead align="left"><tr id="row171321857155517"><th class="cellrowborder" valign="top" width="10.721072107210723%" id="mcps1.2.4.1.1"><p id="p6132957115511"><a name="p6132957115511"></a><a name="p6132957115511"></a>头文件</p>
+</th>
+<th class="cellrowborder" valign="top" width="66.36663666366637%" id="mcps1.2.4.1.2"><p id="p14132125715552"><a name="p14132125715552"></a><a name="p14132125715552"></a>接口名称</p>
+</th>
+<th class="cellrowborder" valign="top" width="22.912291229122914%" id="mcps1.2.4.1.3"><p id="p18132205755516"><a name="p18132205755516"></a><a name="p18132205755516"></a>功能描述</p>
+</th>
+</tr>
+</thead>
+<tbody><tr id="row13132357165514"><td class="cellrowborder" rowspan="16" valign="top" width="10.721072107210723%" headers="mcps1.2.4.1.1 "><p id="p15132185775510"><a name="p15132185775510"></a><a name="p15132185775510"></a>usb_srv_client.h</p>
+<p id="p18132157175510"><a name="p18132157175510"></a><a name="p18132157175510"></a></p>
+<p id="p2133757135510"><a name="p2133757135510"></a><a name="p2133757135510"></a></p>
+</td>
+<td class="cellrowborder" valign="top" width="66.36663666366637%" headers="mcps1.2.4.1.1 "><p id="p1213365714550"><a name="p1213365714550"></a><a name="p1213365714550"></a>int32_t GetCurrentFunctions(int32_t &funcs);</p>
+</td>
+<td class="cellrowborder" valign="top" headers="mcps1.2.4.1.2 "><p id="p201331557185512"><a name="p201331557185512"></a><a name="p201331557185512"></a>获取设备模式下的当前USB功能列表的数字组合掩码</p>
+</td>
+</tr>
+<tr id="row171331657185514"><td class="cellrowborder" valign="top" headers="mcps1.2.4.1.1 "><p id="p913305715553"><a name="p913305715553"></a><a name="p913305715553"></a>int32_t SetCurrentFunctions(int32_t funcs);</p>
+</td>
+<td class="cellrowborder" valign="top" headers="mcps1.2.4.1.2 "><p id="p161332570553"><a name="p161332570553"></a><a name="p161332570553"></a>在设备模式下设置当前的USB功能列表</p>
+</td>
+</tr>
+<tr id="row41331557165518"><td class="cellrowborder" valign="top" headers="mcps1.2.4.1.1 "><p id="p6133145713559"><a name="p6133145713559"></a><a name="p6133145713559"></a>int32_t UsbFunctionsFromString(std::string funcs);</p>
+</td>
+<td class="cellrowborder" valign="top" headers="mcps1.2.4.1.2 "><p id="p131331557175510"><a name="p131331557175510"></a><a name="p131331557175510"></a>将给定的功能列表描述字符串转换为功能列表的数字组合掩码</p>
+</td>
+</tr>
+<tr id="row77021769584"><td class="cellrowborder" valign="top" headers="mcps1.2.4.1.1 "><p id="p77031566584"><a name="p77031566584"></a><a name="p77031566584"></a>std::string UsbFunctionsToString(int32_t funcs);</p>
+</td>
+<td class="cellrowborder" valign="top" headers="mcps1.2.4.1.2 "><p id="p1470315695811"><a name="p1470315695811"></a><a name="p1470315695811"></a>将给定的功能列表的数字组合掩码转换为功能列表描述字符串</p>
+</td>
+</tr>
+</tbody>
+</table>
+
+- ### Port部分<a name="section83365421670"></a>
+
+<a name="table1513255710559"></a>
+<table><thead align="left"><tr id="row171321857155517"><th class="cellrowborder" valign="top" width="10.721072107210723%" id="mcps1.2.4.1.1"><p id="p6132957115511"><a name="p6132957115511"></a><a name="p6132957115511"></a>头文件</p>
+</th>
+<th class="cellrowborder" valign="top" width="66.36663666366637%" id="mcps1.2.4.1.2"><p id="p14132125715552"><a name="p14132125715552"></a><a name="p14132125715552"></a>接口名称</p>
+</th>
+<th class="cellrowborder" valign="top" width="22.912291229122914%" id="mcps1.2.4.1.3"><p id="p18132205755516"><a name="p18132205755516"></a><a name="p18132205755516"></a>功能描述</p>
+</th>
+</tr>
+</thead>
+<tbody><tr id="row13132357165514"><td class="cellrowborder" rowspan="16" valign="top" width="10.721072107210723%" headers="mcps1.2.4.1.1 "><p id="p15132185775510"><a name="p15132185775510"></a><a name="p15132185775510"></a>usb_srv_client.h</p>
+<p id="p18132157175510"><a name="p18132157175510"></a><a name="p18132157175510"></a></p>
+<p id="p2133757135510"><a name="p2133757135510"></a><a name="p2133757135510"></a></p>
+</td>
+<td class="cellrowborder" valign="top" width="66.36663666366637%" headers="mcps1.2.4.1.1 "><p id="p1213365714550"><a name="p1213365714550"></a><a name="p1213365714550"></a>int32_t GetSupportedModes(int32_t portId, int32_t &supportedModes);</p>
+</td>
+<td class="cellrowborder" valign="top" headers="mcps1.2.4.1.2 "><p id="p201331557185512"><a name="p201331557185512"></a><a name="p201331557185512"></a>获取指定的端口支持的模式列表的组合掩码</p>
+</td>
+</tr>
+<tr id="row171331657185514"><td class="cellrowborder" valign="top" headers="mcps1.2.4.1.1 "><p id="p913305715553"><a name="p913305715553"></a><a name="p913305715553"></a>int32_t SetPortRole(int32_t portId, int32_t powerRole, int32_t dataRole);</p>
+</td>
+<td class="cellrowborder" valign="top" headers="mcps1.2.4.1.2 "><p id="p161332570553"><a name="p161332570553"></a><a name="p161332570553"></a>设置指定的端口支持的角色模式，包含充电角色、数据传输角色</p>
+</td>
+</tr>
+<tr id="row41331557165518"><td class="cellrowborder" valign="top" headers="mcps1.2.4.1.1 "><p id="p6133145713559"><a name="p6133145713559"></a><a name="p6133145713559"></a>int32_t GetPorts(std::vector<UsbPort> &usbPorts);</p>
+</td>
+<td class="cellrowborder" valign="top" headers="mcps1.2.4.1.2 "><p id="p131331557175510"><a name="p131331557175510"></a><a name="p131331557175510"></a>获取物理USB端口描述信息列表</p>
+</td>
+</tr>
+</tbody>
+</table>

zh-cn/device-dev/subsystems/subsys-usbservice.md

+# USB<a name="ZH-CN_TOPIC_0000001052857351"></a>
+
+-   **[USB服务子系统概述](subsys-usbservice-overview.md)**
+
+-   **[USB服务子系统使用指导](subsys-usbservice-guide.md)**
+
+-   **[USB服务子系统使用实例](subsys-usbservice-demo.md)**
\ No newline at end of file