1# @ohos.usb (USB管理)(系统接口)
2
3本模块主要提供管理USB设备的相关功能，包括查询USB设备列表、批量数据传输、控制命令传输、权限控制等。
4
5>  **说明：**
6>
7> 本模块首批接口从API version 8开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。
8>
9> 从API version 9开始，该接口不再维护，推荐使用新接口[`@ohos.usbManager`](js-apis-usbManager.md)。
10>
11> 当前页面仅包含本模块的系统接口，其他公开接口参见[@ohos.usb (USB管理)(已停止维护)](js-apis-usb-deprecated.md)。
12
13## 导入模块
14
15```js
16import usb from "@ohos.usb";
17import { BusinessError } from '@ohos.base';
18```
19
20## usb.usbFunctionsFromString<sup>9+</sup>
21
22usbFunctionsFromString(funcs: string): number
23
24在设备模式下，将字符串形式的USB功能列表转化为数字掩码。
25
26**系统接口：** 此接口为系统接口。
27
28**系统能力：**  SystemCapability.USB.USBManager
29
30**参数：**
31
32| 参数名 | 类型   | 必填 | 说明                   |
33| ------ | ------ | ---- | ---------------------- |
34| funcs  | string | 是   | 字符串形式的功能列表。 |
35
36**返回值：**
37
38| 类型   | 说明               |
39| ------ | ------------------ |
40| number | 转化后的数字掩码。 |
41
42**示例：**
43
44```js
45let funcs = "acm";
46let ret = usb.usbFunctionsFromString(funcs);
47```
48
49## usb.usbFunctionsToString<sup>9+</sup>
50
51usbFunctionsToString(funcs: FunctionType): string
52
53在设备模式下，将数字掩码形式的USB功能列表转化为字符串。
54
55**系统接口：** 此接口为系统接口。
56
57**系统能力：**  SystemCapability.USB.USBManager
58
59**参数：**
60
61| 参数名 | 类型                           | 必填 | 说明              |
62| ------ | ------------------------------ | ---- | ----------------- |
63| funcs  | [FunctionType](#functiontype9) | 是   | USB功能数字掩码。 |
64
65**返回值：**
66
67| 类型   | 说明                           |
68| ------ | ------------------------------ |
69| string | 转化后的字符串形式的功能列表。 |
70
71**示例：**
72
73```js
74let funcs = usb.FunctionType.ACM | usb.FunctionType.ECM;
75let ret = usb.usbFunctionsToString(funcs);
76```
77
78## usb.setCurrentFunctions<sup>9+</sup>
79
80setCurrentFunctions(funcs: FunctionType): Promise\<boolean\>
81
82在设备模式下，设置当前的USB功能列表。
83
84**系统接口：** 此接口为系统接口。
85
86**系统能力：**  SystemCapability.USB.USBManager
87
88**参数：**
89
90| 参数名 | 类型                           | 必填 | 说明              |
91| ------ | ------------------------------ | ---- | ----------------- |
92| funcs  | [FunctionType](#functiontype9) | 是   | USB功能数字掩码。 |
93
94**返回值：**
95
96| 类型               | 说明                                                         |
97| ------------------ | ------------------------------------------------------------ |
98| Promise\<boolean\> | Promise对象，返回设置成功与否的结果。true表示设置成功，false表示设置失败。 |
99
100**示例：**
101
102```js
103let funcs : number = usb.FunctionType.HDC;
104usb.setCurrentFunctions(funcs).then(() => {
105    console.info('usb setCurrentFunctions successfully.');
106}).catch((err : BusinessError) => {
107    console.error('usb setCurrentFunctions failed: ' + err.code + ' message: ' + err.message);
108});
109```
110
111## usb.getCurrentFunctions<sup>9+</sup>
112
113getCurrentFunctions(): FunctionType
114
115在设备模式下，获取当前的USB功能列表的数字组合掩码。
116
117**系统接口：** 此接口为系统接口。
118
119**系统能力：**  SystemCapability.USB.USBManager
120
121**返回值：**
122
123| 类型                           | 说明                              |
124| ------------------------------ | --------------------------------- |
125| [FunctionType](#functiontype9) | 当前的USB功能列表的数字组合掩码。 |
126
127**示例：**
128
129```js
130let ret = usb.getCurrentFunctions();
131```
132
133## usb.getPorts<sup>9+</sup>
134
135getPorts(): Array\<USBPort\>
136
137获取所有物理USB端口描述信息。
138
139**系统接口：** 此接口为系统接口。
140
141**系统能力：**  SystemCapability.USB.USBManager
142
143**返回值：**
144
145| 类型                          | 说明                  |
146| ----------------------------- | --------------------- |
147| [Array\<USBPort\>](#usbport9) | USB端口描述信息列表。 |
148
149**示例：**
150
151```js
152let ret = usb.getPorts();
153```
154
155## usb.getSupportedModes<sup>9+</sup>
156
157getSupportedModes(portId: number): PortModeType
158
159获取指定的端口支持的模式列表的组合掩码。
160
161**系统接口：** 此接口为系统接口。
162
163**系统能力：**  SystemCapability.USB.USBManager
164
165**参数：**
166
167| 参数名 | 类型   | 必填 | 说明     |
168| ------ | ------ | ---- | -------- |
169| portId | number | 是   | 端口号。 |
170
171**返回值：**
172
173| 类型                           | 说明                       |
174| ------------------------------ | -------------------------- |
175| [PortModeType](#portmodetype9) | 支持的模式列表的组合掩码。 |
176
177**示例：**
178
179```js
180let ret = usb.getSupportedModes(0);
181```
182
183## usb.setPortRoles<sup>9+</sup>
184
185setPortRoles(portId: number, powerRole: PowerRoleType, dataRole: DataRoleType): Promise\<boolean\>
186
187设置指定的端口支持的角色模式，包含充电角色、数据传输角色。
188
189**系统接口：** 此接口为系统接口。
190
191**系统能力：**  SystemCapability.USB.USBManager
192
193**参数：**
194
195| 参数名    | 类型                             | 必填 | 说明             |
196| --------- | -------------------------------- | ---- | ---------------- |
197| portId    | number                           | 是   | 端口号。         |
198| powerRole | [PowerRoleType](#powerroletype9) | 是   | 充电的角色。     |
199| dataRole  | [DataRoleType](#dataroletype9)   | 是   | 数据传输的角色。 |
200
201**返回值：**
202
203| 类型               | 说明                                                         |
204| ------------------ | ------------------------------------------------------------ |
205| Promise\<boolean\> | Promise对象，返回设置成功与否的结果。true表示设置成功，false表示设置失败。 |
206
207**示例：**
208
209```js
210let portId = 1;
211usb.setPortRoles(portId, usb.PowerRoleType.SOURCE, usb.DataRoleType.HOST).then(() => {
212    console.info('usb setPortRoles successfully.');
213}).catch((err : BusinessError) => {
214    console.error('usb setPortRoles failed: ' + err.code + ' message: ' + err.message);
215});
216```
217
218## USBPort<sup>9+</sup>
219
220USB设备端口。
221
222**系统接口：** 此接口为系统接口。
223
224**系统能力：** SystemCapability.USB.USBManager
225
226| 名称           | 类型                         | 必填 |说明                                |
227| -------------- | -------------------------------- | -------------- |----------------------------------- |
228| id             | number                           | 是   |USB端口唯一标识。                   |
229| supportedModes | [PortModeType](#portmodetype9)   | 是   |USB端口所支持的模式的数字组合掩码。 |
230| status         | [USBPortStatus](#usbportstatus9) | 是   |USB端口角色。                       |
231
232## USBPortStatus<sup>9+</sup>
233
234USB设备端口角色信息。
235
236**系统接口：** 此接口为系统接口。
237
238**系统能力：** SystemCapability.USB.USBManager
239
240| 名称             | 类型 | 必填 |说明                   |
241| ---------------- | -------- | ----------- |---------------------- |
242| currentMode      | number   | 是   |当前的USB模式。        |
243| currentPowerRole | number   | 是   |当前设备充电模式。     |
244| currentDataRole  | number   | 是   |当前设备数据传输模式。 |
245
246## FunctionType<sup>9+</sup>
247
248USB设备侧功能。
249
250**系统接口：** 此接口为系统接口。
251
252**系统能力：** SystemCapability.USB.USBManager
253
254| 名称         | 值   | 说明       |
255| ------------ | ---- | ---------- |
256| NONE         | 0    | 没有功能。 |
257| ACM          | 1    | acm功能。  |
258| ECM          | 2    | ecm功能。  |
259| HDC          | 4    | hdc功能。  |
260| MTP          | 8    | 媒体传输。 |
261| PTP          | 16   | 图片传输。 |
262| RNDIS        | 32   | 网络共享。 |
263| MIDI         | 64   | midi功能。 |
264| AUDIO_SOURCE | 128  | 音频功能。 |
265| NCM          | 256  | ncm传输。  |
266
267## PortModeType<sup>9+</sup>
268
269USB端口模式类型。
270
271**系统接口：** 此接口为系统接口。
272
273**系统能力：** SystemCapability.USB.USBManager
274
275| 名称      | 值   | 说明                                                 |
276| --------- | ---- | ---------------------------------------------------- |
277| NONE      | 0    | 无。                                                 |
278| UFP       | 1    | 数据上行，需要外部供电。                             |
279| DFP       | 2    | 数据下行，对外提供电源。                             |
280| DRP       | 3    | 既可以做DFP(Host)，也可以做UFP(Device)，当前不支持。 |
281| NUM_MODES | 4    | 当前不支持。                                         |
282
283## PowerRoleType<sup>9+</sup>
284
285电源角色类型。
286
287**系统接口：** 此接口为系统接口。
288
289**系统能力：** SystemCapability.USB.USBManager
290
291| 名称   | 值   | 说明       |
292| ------ | ---- | ---------- |
293| NONE   | 0    | 无。       |
294| SOURCE | 1    | 外部供电。 |
295| SINK   | 2    | 内部供电。 |
296
297## DataRoleType<sup>9+</sup>
298
299数据角色类型。
300
301**系统接口：** 此接口为系统接口。
302
303**系统能力：** SystemCapability.USB.USBManager
304
305| 名称   | 值   | 说明         |
306| ------ | ---- | ------------ |
307| NONE   | 0    | 无。         |
308| HOST   | 1    | 主设备角色。 |
309| DEVICE | 2    | 从设备角色。 |
310
311