1# @ohos.usb (USB Manager) (System API) 2 3<!--Kit: Basic Services Kit--> 4<!--Subsystem: USB--> 5<!--Owner: @hwymlgitcode--> 6<!--Designer: @w00373942--> 7<!--Tester: @dong-dongzhen--> 8<!--Adviser: @w_Machine_cc--> 9 10The **usb** module provides USB device management functions, including USB device list query, bulk data transfer, control transfer, and permission control. 11 12> **NOTE** 13> 14> 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. 15> 16> 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). 17> 18> 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). 19 20## Modules to Import 21 22```js 23import usb from "@ohos.usb"; 24import { BusinessError } from '@ohos.base'; 25``` 26 27## usb.usbFunctionsFromString<sup>9+</sup> 28 29usbFunctionsFromString(funcs: string): number 30 31Converts the USB function list in the string format to a numeric mask in Device mode. 32 33**System API**: This is a system API. 34 35**System capability**: SystemCapability.USB.USBManager 36 37**Parameters** 38 39| Name| Type | Mandatory| Description | 40| ------ | ------ | ---- | ---------------------- | 41| funcs | string | Yes | Function list in string format.| 42 43**Return value** 44 45| Type | Description | 46| ------ | ------------------ | 47| number | Function list in numeric mask format.| 48 49**Example** 50 51```js 52let funcs = "acm"; 53let ret = usb.usbFunctionsFromString(funcs); 54``` 55 56## usb.usbFunctionsToString<sup>9+</sup> 57 58usbFunctionsToString(funcs: FunctionType): string 59 60Converts the USB function list in the numeric mask format to a string in Device mode. 61 62**System API**: This is a system API. 63 64**System capability**: SystemCapability.USB.USBManager 65 66**Parameters** 67 68| Name| Type | Mandatory| Description | 69| ------ | ------------------------------ | ---- | ----------------- | 70| funcs | [FunctionType](#functiontype9) | Yes | USB function list in numeric mask format.| 71 72**Return value** 73 74| Type | Description | 75| ------ | ------------------------------ | 76| string | Function list in string format.| 77 78**Example** 79 80```js 81let funcs = usb.FunctionType.ACM | usb.FunctionType.ECM; 82let ret = usb.usbFunctionsToString(funcs); 83``` 84 85## usb.setCurrentFunctions<sup>9+</sup> 86 87setCurrentFunctions(funcs: FunctionType): Promise\<boolean\> 88 89Sets the current USB function list in Device mode. 90 91**System API**: This is a system API. 92 93**System capability**: SystemCapability.USB.USBManager 94 95**Parameters** 96 97| Name| Type | Mandatory| Description | 98| ------ | ------------------------------ | ---- | ----------------- | 99| funcs | [FunctionType](#functiontype9) | Yes | USB function list in numeric mask format.| 100 101**Return value** 102 103| Type | Description | 104| ------------------ | ------------------------------------------------------------ | 105| Promise\<boolean\> | Promise used to return the result. The value **true** indicates that the operation is successful, and the value **false** indicates the opposite.| 106 107**Example** 108 109```js 110let funcs : number = usb.FunctionType.HDC; 111usb.setCurrentFunctions(funcs).then(() => { 112 console.info('usb setCurrentFunctions successfully.'); 113}).catch((err : BusinessError) => { 114 console.error('usb setCurrentFunctions failed: ' + err.code + ' message: ' + err.message); 115}); 116``` 117 118## usb.getCurrentFunctions<sup>9+</sup> 119 120getCurrentFunctions(): FunctionType 121 122Obtains the numeric mask combination for the USB function list in Device mode. 123 124**System API**: This is a system API. 125 126**System capability**: SystemCapability.USB.USBManager 127 128**Return value** 129 130| Type | Description | 131| ------------------------------ | --------------------------------- | 132| [FunctionType](#functiontype9) | Numeric mask combination for the USB function list.| 133 134**Example** 135 136```js 137let ret = usb.getCurrentFunctions(); 138``` 139 140## usb.getPorts<sup>9+</sup> 141 142getPorts(): Array\<USBPort\> 143 144Obtains the list of all physical USB ports. 145 146**System API**: This is a system API. 147 148**System capability**: SystemCapability.USB.USBManager 149 150**Return value** 151 152| Type | Description | 153| ----------------------------- | --------------------- | 154| [Array\<USBPort\>](#usbport9) | List of physical USB ports.| 155 156**Example** 157 158```js 159let ret = usb.getPorts(); 160``` 161 162## usb.getSupportedModes<sup>9+</sup> 163 164getSupportedModes(portId: number): PortModeType 165 166Obtains the mask combination for the supported mode list of a given USB port. 167 168**System API**: This is a system API. 169 170**System capability**: SystemCapability.USB.USBManager 171 172**Parameters** 173 174| Name| Type | Mandatory| Description | 175| ------ | ------ | ---- | -------- | 176| portId | number | Yes | Port number.| 177 178**Return value** 179 180| Type | Description | 181| ------------------------------ | -------------------------- | 182| [PortModeType](#portmodetype9) | Mask combination for the supported mode list.| 183 184**Example** 185 186```js 187let ret = usb.getSupportedModes(0); 188``` 189 190## usb.setPortRoles<sup>9+</sup> 191 192setPortRoles(portId: number, powerRole: PowerRoleType, dataRole: DataRoleType): Promise\<boolean\> 193 194Sets the role types supported by a specified port, which can be **powerRole** (for charging) and **dataRole** (for data transfer). 195 196**System API**: This is a system API. 197 198**System capability**: SystemCapability.USB.USBManager 199 200**Parameters** 201 202| Name | Type | Mandatory| Description | 203| --------- | -------------------------------- | ---- | ---------------- | 204| portId | number | Yes | Port number. | 205| powerRole | [PowerRoleType](#powerroletype9) | Yes | Role for charging. | 206| dataRole | [DataRoleType](#dataroletype9) | Yes | Role for data transfer.| 207 208**Return value** 209 210| Type | Description | 211| ------------------ | ------------------------------------------------------------ | 212| Promise\<boolean\> | Promise used to return the result. The value **true** indicates that the operation is successful, and the value **false** indicates the opposite.| 213 214**Example** 215 216```js 217let portId = 1; 218usb.setPortRoles(portId, usb.PowerRoleType.SOURCE, usb.DataRoleType.HOST).then(() => { 219 console.info('usb setPortRoles successfully.'); 220}).catch((err : BusinessError) => { 221 console.error('usb setPortRoles failed: ' + err.code + ' message: ' + err.message); 222}); 223``` 224 225## USBPort<sup>9+</sup> 226 227Represents a USB port. 228 229**System API**: This is a system API. 230 231**System capability**: SystemCapability.USB.USBManager 232 233| Name | Type | Mandatory|Description | 234| -------------- | -------------------------------- | -------------- |----------------------------------- | 235| id | number | Yes |Unique identifier of a USB port. | 236| supportedModes | [PortModeType](#portmodetype9) | Yes |Numeric mask combination for the supported mode list.| 237| status | [USBPortStatus](#usbportstatus9) | Yes |USB port role. | 238 239## USBPortStatus<sup>9+</sup> 240 241Enumerates USB port roles. 242 243**System API**: This is a system API. 244 245**System capability**: SystemCapability.USB.USBManager 246 247| Name | Type| Mandatory|Description | 248| ---------------- | -------- | ----------- |---------------------- | 249| currentMode | number | Yes |Current USB mode. | 250| currentPowerRole | number | Yes |Current power role. | 251| currentDataRole | number | Yes |Current data role.| 252 253## FunctionType<sup>9+</sup> 254 255Enumerates USB device function types. 256 257**System API**: This is a system API. 258 259**System capability**: SystemCapability.USB.USBManager 260 261| Name | Value | Description | 262| ------------ | ---- | ---------- | 263| NONE | 0 | No function.| 264| ACM | 1 | ACM function. | 265| ECM | 2 | ECM function. | 266| HDC | 4 | HDC function. | 267| MTP | 8 | Media transmission.| 268| PTP | 16 | Image transmission.| 269| RNDIS | 32 | Network sharing.| 270| MIDI | 64 | MIDI function.| 271| AUDIO_SOURCE | 128 | Audio function.| 272| NCM | 256 | NCM transmission. | 273 274## PortModeType<sup>9+</sup> 275 276Enumerates USB port mode types. 277 278**System API**: This is a system API. 279 280**System capability**: SystemCapability.USB.USBManager 281 282| Name | Value | Description | 283| --------- | ---- | ---------------------------------------------------- | 284| NONE | 0 | None | 285| UFP | 1 | Upstream facing port, which functions as the sink of power supply. | 286| DFP | 2 | Downstream facing port, which functions as the source of power supply. | 287| DRP | 3 | Dynamic reconfiguration port (DRP), which can function as the DFP (host) or UFP (device). It is not supported currently.| 288| NUM_MODES | 4 | Not supported currently. | 289 290## PowerRoleType<sup>9+</sup> 291 292Enumerates power role types. 293 294**System API**: This is a system API. 295 296**System capability**: SystemCapability.USB.USBManager 297 298| Name | Value | Description | 299| ------ | ---- | ---------- | 300| NONE | 0 | None | 301| SOURCE | 1 | External power supply.| 302| SINK | 2 | Internal power supply.| 303 304## DataRoleType<sup>9+</sup> 305 306Enumerates data role types. 307 308**System API**: This is a system API. 309 310**System capability**: SystemCapability.USB.USBManager 311 312| Name | Value | Description | 313| ------ | ---- | ------------ | 314| NONE | 0 | None | 315| HOST | 1 | USB host.| 316| DEVICE | 2 | USB device.| 317