1# @ohos.usbManager (USB管理)(系统接口) 2 3本模块主要提供管理USB设备的相关功能，包括主设备上查询USB设备列表、批量数据传输、控制命令传输、权限控制等；从设备上端口管理、功能切换及查询等。 4 5> **说明：** 6> 7> 本模块首批接口从API version 9开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。 8> 当前页面仅包含本模块的系统接口，其他公开接口参见[@ohos.usbManager (USB管理)](js-apis-usbManager.md)。 9 10## 导入模块 11 12```ts 13import usb from "@ohos.usbManager"; 14``` 15 16## usb.addRight 17 18addRight(bundleName: string, deviceName: string): boolean 19 20添加软件包访问设备的权限。系统应用默认拥有访问设备权限，调用此接口不会产生影响。 21 22usb.requestRight (#usbrequestright)会触发弹框请求用户授权；addRight不会触发弹框，而是直接添加软件包访问设备的权限。 23 24**系统接口：** 此接口为系统接口。 25 26**系统能力：** SystemCapability.USB.USBManager 27 28**参数：** 29 30| 参数名 | 类型 | 必填 | 说明 | 31| -------- | -------- | -------- | -------- | 32| deviceName | string | 是 | 设备名称。 | 33| bundleName | string | 是 | 软件包名称。| 34 35**返回值：** 36 37| 类型 | 说明 | 38| -------- | -------- | 39| boolean | 返回权限添加结果。返回true表示权限添加成功；返回false则表示权限添加失败。 | 40 41**示例：** 42 43```ts 44let devicesName: string = "1-1"; 45let bundleName: string = "com.example.hello"; 46if (usb.addRight(bundleName, devicesName)) { 47 console.log(`Succeed in adding right`); 48} 49``` 50 51## usb.usbFunctionsFromString 52 53usbFunctionsFromString(funcs: string): number 54 55在设备模式下，将字符串形式的USB功能列表转化为数字掩码。 56 57**系统接口：** 此接口为系统接口。 58 59**系统能力：** SystemCapability.USB.USBManager 60 61**参数：** 62 63| 参数名 | 类型 | 必填 | 说明 | 64| ------ | ------ | ---- | ---------------------- | 65| funcs | string | 是 | 字符串形式的功能列表。 | 66 67**返回值：** 68 69| 类型 | 说明 | 70| ------ | ------------------ | 71| number | 转化后的数字掩码。 | 72 73**示例：** 74 75```ts 76let funcs: string = "acm"; 77let ret: number = usb.usbFunctionsFromString(funcs); 78``` 79 80## usb.usbFunctionsToString 81 82usbFunctionsToString(funcs: FunctionType): string 83 84在设备模式下，将数字掩码形式的USB功能列表转化为字符串。 85 86**系统接口：** 此接口为系统接口。 87 88**系统能力：** SystemCapability.USB.USBManager 89 90**参数：** 91 92| 参数名 | 类型 | 必填 | 说明 | 93| ------ | ------------------------------ | ---- | ----------------- | 94| funcs | [FunctionType](#functiontype) | 是 | USB功能数字掩码。 | 95 96**返回值：** 97 98| 类型 | 说明 | 99| ------ | ------------------------------ | 100| string | 转化后的字符串形式的功能列表。 | 101 102**示例：** 103 104```ts 105let funcs: number = usb.FunctionType.ACM | usb.FunctionType.ECM; 106let ret: string = usb.usbFunctionsToString(funcs); 107``` 108 109## usb.setCurrentFunctions 110 111setCurrentFunctions(funcs: FunctionType): Promise\<void\> 112 113在设备模式下，设置当前的USB功能列表。 114 115**系统接口：** 此接口为系统接口。 116 117**系统能力：** SystemCapability.USB.USBManager 118 119**参数：** 120 121| 参数名 | 类型 | 必填 | 说明 | 122| ------ | ------------------------------ | ---- | ----------------- | 123| funcs | [FunctionType](#functiontype) | 是 | USB功能数字掩码。 | 124 125**错误码：** 126 127以下错误码的详细介绍请参见[USB服务错误码](errorcode-usb.md)。 128 129| 错误码ID | 错误信息 | 130| -------- | ---------------------------------------------------- | 131| 14400002 | Permission denied.The HDC is disabled by the system. | 132 133**返回值：** 134 135| 类型 | 说明 | 136| --------------- | ------------- | 137| Promise\<void\> | Promise对象。 | 138 139**示例：** 140 141```ts 142import {BusinessError} from '@ohos.base'; 143let funcs: number = usb.FunctionType.HDC; 144usb.setCurrentFunctions(funcs).then(() => { 145 console.info('usb setCurrentFunctions successfully.'); 146}).catch((err: BusinessError) => { 147 console.error('usb setCurrentFunctions failed: ' + err.code + ' message: ' + err.message); 148}); 149``` 150 151## usb.getCurrentFunctions 152 153getCurrentFunctions(): FunctionType 154 155在设备模式下，获取当前的USB功能列表的数字组合掩码。 156 157**系统接口：** 此接口为系统接口。 158 159**系统能力：** SystemCapability.USB.USBManager 160 161**返回值：** 162 163| 类型 | 说明 | 164| ------------------------------ | --------------------------------- | 165| [FunctionType](#functiontype) | 当前的USB功能列表的数字组合掩码。 | 166 167**示例：** 168 169```ts 170let ret: number = usb.getCurrentFunctions(); 171``` 172 173## usb.getPorts 174 175getPorts(): Array\<USBPort\> 176 177获取所有物理USB端口描述信息。 178 179**系统接口：** 此接口为系统接口。 180 181**系统能力：** SystemCapability.USB.USBManager 182 183**返回值：** 184 185| 类型 | 说明 | 186| ----------------------------- | --------------------- | 187| Array<[USBPort](#usbport)> | USB端口描述信息列表。 | 188 189**示例：** 190 191```ts 192let ret: Array<usb.USBPort> = usb.getPorts(); 193``` 194 195## usb.getSupportedModes 196 197getSupportedModes(portId: number): PortModeType 198 199获取指定的端口支持的模式列表的组合掩码。 200 201**系统接口：** 此接口为系统接口。 202 203**系统能力：** SystemCapability.USB.USBManager 204 205**参数：** 206 207| 参数名 | 类型 | 必填 | 说明 | 208| ------ | ------ | ---- | -------- | 209| portId | number | 是 | 端口号。 | 210 211**返回值：** 212 213| 类型 | 说明 | 214| ------------------------------ | -------------------------- | 215| [PortModeType](#portmodetype) | 支持的模式列表的组合掩码。 | 216 217**示例：** 218 219```ts 220let ret: number = usb.getSupportedModes(0); 221``` 222 223## usb.setPortRoles 224 225setPortRoles(portId: number, powerRole: PowerRoleType, dataRole: DataRoleType): Promise\<void\> 226 227设置指定的端口支持的角色模式，包含充电角色、数据传输角色。 228 229**系统接口：** 此接口为系统接口。 230 231**系统能力：** SystemCapability.USB.USBManager 232 233**参数：** 234 235| 参数名 | 类型 | 必填 | 说明 | 236| --------- | -------------------------------- | ---- | ---------------- | 237| portId | number | 是 | 端口号。 | 238| powerRole | [PowerRoleType](#powerroletype) | 是 | 充电的角色。 | 239| dataRole | [DataRoleType](#dataroletype) | 是 | 数据传输的角色。 | 240 241**返回值：** 242 243| 类型 | 说明 | 244| --------------- | ------------- | 245| Promise\<void\> | Promise对象。 | 246 247**示例：** 248 249```ts 250import {BusinessError} from '@ohos.base'; 251let portId: number = 1; 252usb.setPortRoles(portId, usb.PowerRoleType.SOURCE, usb.DataRoleType.HOST).then(() => { 253 console.info('usb setPortRoles successfully.'); 254}).catch((err: BusinessError) => { 255 console.error('usb setPortRoles failed: ' + err.code + ' message: ' + err.message); 256}); 257``` 258 259## USBPort 260 261USB设备端口。 262 263**系统接口：** 此接口为系统接口。 264 265**系统能力：** SystemCapability.USB.USBManager 266 267| 名称 | 类型 | 必填 |说明 | 268| -------------- | ------------------------------- | ------------------- |------------------------ | 269| id | number | 是 |USB端口唯一标识。 | 270| supportedModes | [PortModeType](#portmodetype) | 是 |USB端口所支持的模式的数字组合掩码。 | 271| status | [USBPortStatus](#usbportstatus) | 是 |USB端口角色。 | 272 273## USBPortStatus 274 275USB设备端口角色信息。 276 277**系统接口：** 此接口为系统接口。 278 279**系统能力：** SystemCapability.USB.USBManager 280 281| 名称 | 类型 | 必填 |说明 | 282| ---------------- | -------- | ---------------- |---------------------- | 283| currentMode | number | 是 |当前的USB模式。 | 284| currentPowerRole | number | 是 |当前设备充电模式。 | 285| currentDataRole | number | 是 |当前设备数据传输模式。 | 286 287## FunctionType 288 289USB设备侧功能。 290 291**系统接口：** 此接口为系统接口。 292 293**系统能力：** SystemCapability.USB.USBManager 294 295| 名称 | 值 | 说明 | 296| ------------ | ---- | ---------- | 297| NONE | 0 | 没有功能。 | 298| ACM | 1 | acm功能。 | 299| ECM | 2 | ecm功能。 | 300| HDC | 4 | hdc功能。 | 301| MTP | 8 | 暂不支持。 | 302| PTP | 16 | 暂不支持。 | 303| RNDIS | 32 | 暂不支持。 | 304| MIDI | 64 | 暂不支持。 | 305| AUDIO_SOURCE | 128 | 暂不支持。 | 306| NCM | 256 | 暂不支持。 | 307 308## PortModeType 309 310USB端口模式类型。 311 312**系统接口：** 此接口为系统接口。 313 314**系统能力：** SystemCapability.USB.USBManager 315 316| 名称 | 值 | 说明 | 317| --------- | ---- | ---------------------------------------------------- | 318| NONE | 0 | 无。 | 319| UFP | 1 | 数据上行，需要外部供电。 | 320| DFP | 2 | 数据下行，对外提供电源。 | 321| DRP | 3 | 既可以做DFP(Host)，也可以做UFP(Device)，当前不支持。 | 322| NUM_MODES | 4 | 当前不支持。 | 323 324## PowerRoleType 325 326电源角色类型。 327 328**系统接口：** 此接口为系统接口。 329 330**系统能力：** SystemCapability.USB.USBManager 331 332| 名称 | 值 | 说明 | 333| ------ | ---- | ---------- | 334| NONE | 0 | 无。 | 335| SOURCE | 1 | 外部供电。 | 336| SINK | 2 | 内部供电。 | 337 338## DataRoleType 339 340数据角色类型。 341 342**系统接口：** 此接口为系统接口。 343 344**系统能力：** SystemCapability.USB.USBManager 345 346| 名称 | 值 | 说明 | 347| ------ | ---- | ------------ | 348| NONE | 0 | 无。 | 349| HOST | 1 | 主设备角色。 | 350| DEVICE | 2 | 从设备角色。 | 351 352