1# USB服务组件<a name="ZH-CN_TOPIC_0000001124094823"></a> 2 3- [简介](#section11660541593) 4- [目录](#section19472752217) 5- [接口](#section19472752218) 6- [开发示例](#section19472752219) 7- [相关仓](#section63151229062) 8 9## 简介<a name="section11660541593"></a> 10USB服务框架如下图所示： 11 12**图 1** USB服务框架架图<a name="fig15658513184019"></a> 13 14 15架构及功能介绍： 161. USB API：提供USB的基础API，主要包含查询USB设备的列表、设备插拔通知、USB HOST/DEVICE 功能切换、批量数据传输、控制命令传输、USB设备打开的权限控制及USB device模式下的function功能切换等。 172. USB Service：主要实现HAL层数据接收、解析、分发，前后台的策略管控，对该设备USB的管理，USB权限管控等。 183. USB HAL层：提供给用户态可直接调用的驱动能力接口，按照功能分类三大类：DDK初始化类、对interface对象操作类、对request对象操作类，可以提供DDK初始化、interface绑定和释放，打开和关闭操作，request的申请和释放，同步和异步传输等。HAL层代码位于[drivers\_peripheral](https://gitee.com/openharmony/drivers_peripheral/blob/master/README_zh.md) 19 20## 目录<a name="section19472752217"></a> 21``` 22base/usb/usb_manager 23├── interfaces # 接口层 24│ ├── innerkits # 内部接口 25│ └── kits # 外部接口 26├── sa_profile # SA配置文件 27└── services # 服务层 28│ ├── native # native层 29│ └── zidl # zidl接口层 30└── test # 测试用例 31└── utils # 工具和通用层 32``` 33## 接口<a name="section19472752218"></a> 34### [外部接口](https://gitee.com/openharmony/usb_manager/blob/master/interfaces/kits/js/@ohos.usb.d.ts) 35 36### 内部接口 37#### Host 功能接口 38 39| **内部接口申明** | **接口描述** | 40| --- | --- | 41| int32_t OpenDevice(const UsbDevice &device, USBDevicePipe &pip); | 打开设备，建立连接 | 42| bool Close(const USBDevicePipe &pip); | 关闭设备，释放与设备相关的所有系统资源 | 43| int32_t GetDevices(std::vector &deviceList); | 获取设备列表 | 44| int32_t SetConfiguration(USBDevicePipe &pip, const USBConfig &config); | 设置设备当前使用的配置，通过配置值进行指定 | 45| int32_t ClaimInterface(USBDevicePipe &pip, const UsbInterface &interface, bool force); | 打开接口，并申明独占接口，必须在数据传输前执行 | 46| int32_t ReleaseInterface(USBDevicePipe &pip, const UsbInterface &interface); | 关闭接口，释放接口的占用，在停止数据传输后执行 | 47| int32_t SetInterface(USBDevicePipe &pipe, const UsbInterface &interface); | 设置指定接口的备选设置，用于在具有相同ID但不同备用设置的两个接口之间进行选择 | 48| int32_t BulkTransfer(USBDevicePipe &pip, const USBEndpoint &endpoint, std::vector<uint8_t> &vdata, int32_t timeout); | 在给定端点上执行批量数据读写， 返回读取的数据和长度 | 49| int32_t ControlTransfer(USBDevicePipe &pip, const UsbCtrlTransfer &ctrl, std::vector<uint8_t> &vdata); | 对此设备执行端点零的控制事务，传输方向由请求类型决定。 如果requestType＆ USB_ENDPOINT_DIR_MASK是USB_DIR_OUT ，则传输是写入，如果是USB_DIR_IN ，则传输是读取。 | 50| int32_t RequestInitialize(UsbRequest &request); | 初始化请求 | 51| int32_t RequestQueue(UsbRequest &request); | 进行异步数据发送或者接收请求，数据传输方向由端点方向决定 | 52| int32_t PipeRequestWait(USBDevicePipe &pip, int64_t timeout, UsbRequest &req); | 等待RequestQueue异步请求的操作结果 | 53| int32_t RequestAbort(UsbRequest &request); | 取消待处理的数据请求 | 54| int32_t RequestFree(UsbRequest &request); | 释放数据请求 | 55| bool HasRight(std::string deviceName); | 判断设备是否有权限 | 56| int32_t RequestRight(std::string deviceName); | 给指定设备申请权限 | 57 58#### Device 功能接口 59| **内部接口申明** | **接口描述** | 60| --- | --- | 61| int32_t GetCurrentFunctions(int32_t &funcs); | 获取从设备支持的功能列表（按位域表示） | 62| int32_t SetCurrentFunctions(int32_t funcs); | 设置从设备支持的功能列表（按位域表示） | 63| int32_t UsbFunctionsFromString(std::string funcs); | 将给定的功能列表描述字符串转换为功能列表的数字组合掩码 | 64| std::string UsbFunctionsToString(int32_t funcs); | 将给定的功能列表的数字组合掩码转换为功能列表描述字符串 | 65 66#### Port 功能接口 67| **内部接口申明** | **接口描述** | 68| --- | --- | 69| int32_t GetPorts(std::vector &usbPorts); | 获取port列表 | 70| int32_t SetPortRole(int32_t portId, int32_t powerRole, int32_t dataRole); | 设置端口工作模式 | 71| int32_t GetSupportedModes(int32_t portId, int32_t &supportedModes); | 获取指定的端口支持的模式列表的组合掩码 | 72 73## 开发示例<a name="section19472752219"></a> 74主要接口调用示例如下，详细业务流程代码可以参考测试用例代码 [js_unittest](test/native/js_unittest) 75#### Host功能开发 76Usb设备作为host设备连接device设备进行数据传输。 771. 获取设备列表 78```JS 79// 导入usb接口api包 80import usb from '@ohos.usb'; 81// 获取设备列表 82var deviceList = usb.getDevices(); 83``` 842. 获取设备操作权限 85```JS 86// device name 87var deviceName = deviceList[0].name; 88// 申请操作指定的device的操作权限 89usb.requestRight(deviceName).then(hasRight => { 90 console.info("usb device request right result: " + hasRight); 91}).catch(error => { 92 console.info("usb device request right failed : " + error); 93}); 94``` 953. 打开USB设备 96```JS 97// 打开设备，获取数据传输通道 98var pipe = usb.connectDevice(deviceList[0]); 99// 打开对应接口 100usb.claimInterface(pipe , interface, true); // interface为device中需要操作的interface，选取合适的interface进行对应操作 101``` 1024. 数据传输 103```JS 104// 读取数据，在device信息中选取对应数据接收的endpoint来做数据传（endpoint.direction == 0x80）；dataUint8Array要发送的数据 105usb.bulkTransfer(pipe, inEndpoint, dataUint8Array, 15000).then(dataLength => { 106if (dataLength >= 0) { 107 console.info("usb readData result Length : " + dataLength); 108 var resultStr = this.ab2str(dataUint8Array); // uint8数据转string 109 console.info("usb readData buffer : " + resultStr); 110} else { 111 console.info("usb readData failed : " + dataLength); 112} 113}).catch(error => { 114console.info("usb readData error : " + JSON.stringify(error)); 115}); 116// 发送数据，在device信息中选取对应数据发送的endpoint来做数据传（endpoint.direction == 0） 117usb.bulkTransfer(this.pip, this.outEndpoint, dataUint8Array, 15000).then(dataLength => { 118 if (dataLength >= 0) { 119 console.info("usb writeData result write length : " + dataLength); 120 } else { 121 console.info("writeData failed"); 122 } 123}).catch(error => { 124 console.info("usb writeData error : " + JSON.stringify(error)); 125}); 126``` 1275. 释放接口、关闭设备 128```JS 129usb.releaseInterface(pipe, interface); 130usb.closePipe(pipe); 131``` 132#### Device功能开发 133Usb设备作为device设备，设置ACM、ECM、HDC等功能。 1341. 设置USB function功能 135```JS 136usb.setCurrentFunctions(funType).then(data => { 137 console.info("usb setCurrentFunctions : " + data); 138}).catch(error => { 139 console.info("usb setCurrentFunctions error : " + error); 140}); 141``` 142 143## 相关仓<a name="section63151229062"></a> 144 145[驱动子系统](https://gitee.com/openharmony/docs/blob/master/zh-cn/readme/%E9%A9%B1%E5%8A%A8%E5%AD%90%E7%B3%BB%E7%BB%9F.md) 146 147[drivers\_peripheral](https://gitee.com/openharmony/drivers_peripheral/blob/master/README_zh.md) 148 149[drivers\_framework](https://gitee.com/openharmony/drivers_framework/blob/master/README_zh.md) 150 151[drivers\_adapter](https://gitee.com/openharmony/drivers_adapter/blob/master/README_zh.md) 152 153[drivers\_adapter\_khdf\_linux](https://gitee.com/openharmony/drivers_adapter_khdf_linux/blob/master/README_zh.md) 154
