1# @ohos.usb (USB Manager) (System API)
2
3The **usb** module provides USB device management functions, including USB device list query, bulk data transfer, control transfer, and permission control.
4
5>  **NOTE**
6>
7> The initial APIs of this module are supported since API version 8. Newly added APIs will be marked with a superscript to indicate their earliest API version.
8>
9> The APIs provided by this module are no longer maintained since API version 9. You are advised to use [`@ohos.usbManager`](js-apis-usbManager.md).
10>
11> This topic describes only system APIs provided by the module. For details about its public APIs, see [@ohos.usb (USB Manager) (No Longer Maintained)](js-apis-usb-deprecated.md).
12
13## Modules to Import
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
24Converts the USB function list in the string format to a numeric mask in Device mode.
25
26**System API**: This is a system API.
27
28**System capability**: SystemCapability.USB.USBManager
29
30**Parameters**
31
32| Name| Type  | Mandatory| Description                  |
33| ------ | ------ | ---- | ---------------------- |
34| funcs  | string | Yes  | Function list in string format.|
35
36**Return value**
37
38| Type  | Description              |
39| ------ | ------------------ |
40| number | Function list in numeric mask format.|
41
42**Example**
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
53Converts the USB function list in the numeric mask format to a string in Device mode.
54
55**System API**: This is a system API.
56
57**System capability**: SystemCapability.USB.USBManager
58
59**Parameters**
60
61| Name| Type                          | Mandatory| Description             |
62| ------ | ------------------------------ | ---- | ----------------- |
63| funcs  | [FunctionType](#functiontype9) | Yes  | USB function list in numeric mask format.|
64
65**Return value**
66
67| Type  | Description                          |
68| ------ | ------------------------------ |
69| string | Function list in string format.|
70
71**Example**
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
82Sets the current USB function list in Device mode.
83
84**System API**: This is a system API.
85
86**System capability**: SystemCapability.USB.USBManager
87
88**Parameters**
89
90| Name| Type                          | Mandatory| Description             |
91| ------ | ------------------------------ | ---- | ----------------- |
92| funcs  | [FunctionType](#functiontype9) | Yes  | USB function list in numeric mask format.|
93
94**Return value**
95
96| Type              | Description                                                        |
97| ------------------ | ------------------------------------------------------------ |
98| Promise\<boolean\> | Promise used to return the result. The value **true** indicates that the operation is successful, and the value **false** indicates the opposite.|
99
100**Example**
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
115Obtains the numeric mask combination for the USB function list in Device mode.
116
117**System API**: This is a system API.
118
119**System capability**: SystemCapability.USB.USBManager
120
121**Return value**
122
123| Type                          | Description                             |
124| ------------------------------ | --------------------------------- |
125| [FunctionType](#functiontype9) | Numeric mask combination for the USB function list.|
126
127**Example**
128
129```js
130let ret = usb.getCurrentFunctions();
131```
132
133## usb.getPorts<sup>9+</sup>
134
135getPorts(): Array\<USBPort\>
136
137Obtains the list of all physical USB ports.
138
139**System API**: This is a system API.
140
141**System capability**: SystemCapability.USB.USBManager
142
143**Return value**
144
145| Type                         | Description                 |
146| ----------------------------- | --------------------- |
147| [Array\<USBPort\>](#usbport9) | List of physical USB ports.|
148
149**Example**
150
151```js
152let ret = usb.getPorts();
153```
154
155## usb.getSupportedModes<sup>9+</sup>
156
157getSupportedModes(portId: number): PortModeType
158
159Obtains the mask combination for the supported mode list of a given USB port.
160
161**System API**: This is a system API.
162
163**System capability**: SystemCapability.USB.USBManager
164
165**Parameters**
166
167| Name| Type  | Mandatory| Description    |
168| ------ | ------ | ---- | -------- |
169| portId | number | Yes  | Port number.|
170
171**Return value**
172
173| Type                          | Description                      |
174| ------------------------------ | -------------------------- |
175| [PortModeType](#portmodetype9) | Mask combination for the supported mode list.|
176
177**Example**
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
187Sets the role types supported by a specified port, which can be **powerRole** (for charging) and **dataRole** (for data transfer).
188
189**System API**: This is a system API.
190
191**System capability**: SystemCapability.USB.USBManager
192
193**Parameters**
194
195| Name   | Type                            | Mandatory| Description            |
196| --------- | -------------------------------- | ---- | ---------------- |
197| portId    | number                           | Yes  | Port number.        |
198| powerRole | [PowerRoleType](#powerroletype9) | Yes  | Role for charging.    |
199| dataRole  | [DataRoleType](#dataroletype9)   | Yes  | Role for data transfer.|
200
201**Return value**
202
203| Type              | Description                                                        |
204| ------------------ | ------------------------------------------------------------ |
205| Promise\<boolean\> | Promise used to return the result. The value **true** indicates that the operation is successful, and the value **false** indicates the opposite.|
206
207**Example**
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
220Represents a USB port.
221
222**System API**: This is a system API.
223
224**System capability**: SystemCapability.USB.USBManager
225
226| Name          | Type                        | Mandatory|Description                               |
227| -------------- | -------------------------------- | -------------- |----------------------------------- |
228| id             | number                           | Yes  |Unique identifier of a USB port.                  |
229| supportedModes | [PortModeType](#portmodetype9)   | Yes  |Numeric mask combination for the supported mode list.|
230| status         | [USBPortStatus](#usbportstatus9) | Yes  |USB port role.                      |
231
232## USBPortStatus<sup>9+</sup>
233
234Enumerates USB port roles.
235
236**System API**: This is a system API.
237
238**System capability**: SystemCapability.USB.USBManager
239
240| Name            | Type| Mandatory|Description                  |
241| ---------------- | -------- | ----------- |---------------------- |
242| currentMode      | number   | Yes  |Current USB mode.       |
243| currentPowerRole | number   | Yes  |Current power role.    |
244| currentDataRole  | number   | Yes  |Current data role.|
245
246## FunctionType<sup>9+</sup>
247
248Enumerates USB device function types.
249
250**System API**: This is a system API.
251
252**System capability**: SystemCapability.USB.USBManager
253
254| Name        | Value  | Description      |
255| ------------ | ---- | ---------- |
256| NONE         | 0    | No function.|
257| ACM          | 1    | ACM function. |
258| ECM          | 2    | ECM function. |
259| HDC          | 4    | HDC function. |
260| MTP          | 8    | Media transmission.|
261| PTP          | 16   | Image transmission.|
262| RNDIS        | 32   | Network sharing.|
263| MIDI         | 64   | MIDI function.|
264| AUDIO_SOURCE | 128  | Audio function.|
265| NCM          | 256  | NCM transmission. |
266
267## PortModeType<sup>9+</sup>
268
269Enumerates USB port mode types.
270
271**System API**: This is a system API.
272
273**System capability**: SystemCapability.USB.USBManager
274
275| Name     | Value  | Description                                                |
276| --------- | ---- | ---------------------------------------------------- |
277| NONE      | 0    | None                                                |
278| UFP       | 1    | Upstream facing port, which functions as the sink of power supply.                            |
279| DFP       | 2    | Downstream facing port, which functions as the source of power supply.                            |
280| DRP       | 3    | Dynamic reconfiguration port (DRP), which can function as the DFP (host) or UFP (device). It is not supported currently.|
281| NUM_MODES | 4    | Not supported currently.                                        |
282
283## PowerRoleType<sup>9+</sup>
284
285Enumerates power role types.
286
287**System API**: This is a system API.
288
289**System capability**: SystemCapability.USB.USBManager
290
291| Name  | Value  | Description      |
292| ------ | ---- | ---------- |
293| NONE   | 0    | None      |
294| SOURCE | 1    | External power supply.|
295| SINK   | 2    | Internal power supply.|
296
297## DataRoleType<sup>9+</sup>
298
299Enumerates data role types.
300
301**System API**: This is a system API.
302
303**System capability**: SystemCapability.USB.USBManager
304
305| Name  | Value  | Description        |
306| ------ | ---- | ------------ |
307| NONE   | 0    | None        |
308| HOST   | 1    | USB host.|
309| DEVICE | 2    | USB device.|
310