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