1# @ohos.usbManager (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 9开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。 15> 当前页面仅包含本模块的系统接口，其他公开接口参见[@ohos.usbManager (USB管理)](js-apis-usbManager.md)。 16 17## 导入模块 18 19```ts 20import { usbManager } from '@kit.BasicServicesKit'; 21``` 22 23## addRight <sup>(deprecated)</sup> 24 25addRight(bundleName: string, deviceName: string): boolean 26 27添加软件包访问设备的权限。系统应用默认拥有访问设备权限，调用此接口不会产生影响。 28 29usbManager.requestRight (#usbrequestright)会触发弹框请求用户授权；addRight不会触发弹框，而是直接添加软件包访问设备的权限。 30 31**说明：** 32 33> 从 API version 9开始支持，从API version 12开始废弃。建议使用 [addDeviceAccessRight](#adddeviceaccessright12) 替代。 34 35**系统接口：** 此接口为系统接口。 36 37**系统能力：** SystemCapability.USB.USBManager 38 39**参数：** 40 41| 参数名 | 类型 | 必填 | 说明 | 42| ---------- | ------ | ---- | ------------ | 43| deviceName | string | 是 | 设备名称。 | 44| bundleName | string | 是 | 软件包名称。 | 45 46**返回值：** 47 48| 类型 | 说明 | 49| ------- | ------------------------------------------------------------------------- | 50| boolean | 返回权限添加结果。返回true表示权限添加成功；返回false则表示权限添加失败。 | 51 52**错误码：** 53 54以下错误码的详细介绍请参见[USB服务错误码](errorcode-usb.md)。 55 56| 错误码ID | 错误信息 | 57| -------- | ------------------------------------------------------------------------------------------------------- | 58| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. | 59| 202 | Permission denied. Normal application do not have permission to use system api. | 60 61**示例：** 62 63```ts 64let devicesName: string = "1-1"; 65let bundleName: string = "com.example.hello"; 66if (usbManager.addRight(bundleName, devicesName)) { 67 console.log(`Succeed in adding right`); 68} 69``` 70 71## usbFunctionsFromString<sup>(deprecated)</sup> 72 73usbFunctionsFromString(funcs: string): number 74 75在设备模式下，将字符串形式的USB功能列表转化为数字掩码。 76 77**说明：** 78 79> 从 API version 9开始支持，从API version 12开始废弃。建议使用 [getFunctionsFromString](#getfunctionsfromstring12) 替代。 80 81**系统接口：** 此接口为系统接口。 82 83**系统能力：** SystemCapability.USB.USBManager 84 85**参数：** 86 87| 参数名 | 类型 | 必填 | 说明 | 88| ------ | ------ | ---- | ---------------------- | 89| funcs | string | 是 | 字符串形式的功能列表。 | 90 91**返回值：** 92 93| 类型 | 说明 | 94| ------ | ------------------ | 95| number | 转化后的数字掩码。 | 96 97**错误码：** 98 99以下错误码的详细介绍请参见[USB服务错误码](errorcode-usb.md)。 100 101| 错误码ID | 错误信息 | 102| -------- | ------------------------------------------------------------------------------------------------------- | 103| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. | 104| 202 | Permission denied. Normal application do not have permission to use system api. | 105 106**示例：** 107 108```ts 109let funcs: string = "acm"; 110let ret: number = usbManager.usbFunctionsFromString(funcs); 111``` 112 113## usbFunctionsToString<sup>(deprecated)</sup> 114 115usbFunctionsToString(funcs: FunctionType): string 116 117在设备模式下，将数字掩码形式的USB功能列表转化为字符串。 118 119**说明：** 120 121> 从 API version 9开始支持，从API version 12开始废弃。建议使用 [getStringFromFunctions](#getstringfromfunctions12) 替代。 122 123**系统接口：** 此接口为系统接口。 124 125**系统能力：** SystemCapability.USB.USBManager 126 127**参数：** 128 129| 参数名 | 类型 | 必填 | 说明 | 130| ------ | ----------------------------- | ---- | ----------------- | 131| funcs | [FunctionType](#functiontype) | 是 | USB功能数字掩码。 | 132 133**返回值：** 134 135| 类型 | 说明 | 136| ------ | ------------------------------ | 137| string | 转化后的字符串形式的功能列表。 | 138 139**错误码：** 140 141以下错误码的详细介绍请参见[USB服务错误码](errorcode-usb.md)。 142 143| 错误码ID | 错误信息 | 144| -------- | ------------------------------------------------------------------------------------------------------- | 145| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. | 146| 202 | Permission denied. Normal application do not have permission to use system api. | 147 148**示例：** 149 150```ts 151let funcs: number = usbManager.FunctionType.ACM | usb.FunctionType.ECM; 152let ret: string = usbManager.usbFunctionsToString(funcs); 153``` 154 155## setCurrentFunctions<sup>(deprecated)</sup> 156 157setCurrentFunctions(funcs: FunctionType): Promise\<void\> 158 159在设备模式下，设置当前的USB功能列表。 160 161**说明：** 162 163> 从 API version 9开始支持，从API version 12开始废弃。建议使用 [setDeviceFunctions](#setdevicefunctions12) 替代。 164 165**系统接口：** 此接口为系统接口。 166 167**系统能力：** SystemCapability.USB.USBManager 168 169**参数：** 170 171| 参数名 | 类型 | 必填 | 说明 | 172| ------ | ----------------------------- | ---- | ----------------- | 173| funcs | [FunctionType](#functiontype) | 是 | USB功能数字掩码。 | 174 175**返回值：** 176 177| 类型 | 说明 | 178| ------------------- | ------------- | 179| Promise\<void\> | Promise对象。 | 180 181**错误码：** 182 183以下错误码的详细介绍请参见[USB服务错误码](errorcode-usb.md)。 184 185| 错误码ID | 错误信息 | 186| -------- | ------------------------------------------------------------------------------------------------------- | 187| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. | 188| 14400002 | Permission denied. The HDC is disabled by the system. | 189 190**示例：** 191 192```ts 193import {BusinessError} from '@kit.BasicServicesKit'; 194let funcs: number = usbManager.FunctionType.HDC; 195usbManager.setCurrentFunctions(funcs).then(() => { 196 console.info('usb setCurrentFunctions successfully.'); 197}).catch((err: BusinessError) => { 198 console.error('usb setCurrentFunctions failed: ' + err.code + ' message: ' + err.message); 199}); 200``` 201 202## getCurrentFunctions<sup>(deprecated)</sup> 203 204getCurrentFunctions(): FunctionType 205 206在设备模式下，获取当前的USB功能列表的数字组合掩码。开发者模式关闭时，如果没有设备接入，接口可能返回`undefined`，注意需要对接口返回值做判空处理。 207 208**说明：** 209 210> 从 API version 9开始支持，从API version 12开始废弃。建议使用 [getDeviceFunctions](#getdevicefunctions12) 替代。 211 212**系统接口：** 此接口为系统接口。 213 214**系统能力：** SystemCapability.USB.USBManager 215 216**返回值：** 217 218| 类型 | 说明 | 219| ----------------------------- | --------------------------------- | 220| [FunctionType](#functiontype) | 当前的USB功能列表的数字组合掩码。 | 221 222**错误码：** 223 224以下错误码的详细介绍请参见[USB服务错误码](errorcode-usb.md)。 225 226| 错误码ID | 错误信息 | 227| -------- | ------------------------------------------------------------------------------- | 228| 401 | Parameter error. No parameters are required. | 229| 202 | Permission denied. Normal application do not have permission to use system api. | 230 231**示例：** 232 233```ts 234let ret: number = usbManager.getCurrentFunctions(); 235``` 236 237## getPorts<sup>(deprecated)</sup> 238 239getPorts(): Array\<USBPort\> 240 241获取所有物理USB端口描述信息。开发者模式关闭时，如果没有设备接入，接口可能返回`undefined`，注意需要对接口返回值做判空处理。 242 243**说明：** 244 245> 从 API version 9开始支持，从API version 12开始废弃。建议使用 [getPortList](#getportlist12) 替代。 246 247**系统接口：** 此接口为系统接口。 248 249**系统能力：** SystemCapability.USB.USBManager 250 251**返回值：** 252 253| 类型 | 说明 | 254| -------------------------- | --------------------- | 255| Array<[USBPort](#usbport)> | USB端口描述信息列表。 | 256 257**错误码：** 258 259以下错误码的详细介绍请参见[USB服务错误码](errorcode-usb.md)。 260 261| 错误码ID | 错误信息 | 262| -------- | ------------------------------------------------------------------------------- | 263| 401 | Parameter error. No parameters are required. | 264| 202 | Permission denied. Normal application do not have permission to use system api. | 265 266**示例：** 267 268```ts 269let ret: Array<usbManager.USBPort> = usbManager.getPorts(); 270``` 271 272## getSupportedModes(deprecated) 273 274getSupportedModes(portId: number): PortModeType 275 276获取指定的端口支持的模式列表的组合掩码。 277 278**说明：** 279 280> 从 API version 9开始支持，从API version 12开始废弃。建议使用 [getPortSupportModes](#getportsupportmodes12) 替代。 281 282**系统接口：** 此接口为系统接口。 283 284**系统能力：** SystemCapability.USB.USBManager 285 286**参数：** 287 288| 参数名 | 类型 | 必填 | 说明 | 289| ------ | ------ | ---- | -------- | 290| portId | number | 是 | 端口号。 | 291 292**返回值：** 293 294| 类型 | 说明 | 295| ----------------------------- | -------------------------- | 296| [PortModeType](#portmodetype) | 支持的模式列表的组合掩码。 | 297 298**错误码：** 299 300以下错误码的详细介绍请参见[USB服务错误码](errorcode-usb.md)。 301 302| 错误码ID | 错误信息 | 303| -------- | ------------------------------------------------------------------------------------------------------- | 304| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. | 305| 202 | Permission denied. Normal application do not have permission to use system api. | 306 307**示例：** 308 309```ts 310let ret: number = usbManager.getSupportedModes(0); 311``` 312 313## setPortRoles<sup>(deprecated)</sup> 314 315setPortRoles(portId: number, powerRole: PowerRoleType, dataRole: DataRoleType): Promise\<void\> 316 317设置指定的端口支持的角色模式，包含充电角色、数据传输角色。 318 319**说明：** 320 321> 从 API version 9开始支持，从API version 12开始废弃。建议使用 [setPortRoleTypes](#setportroletypes12) 替代。 322 323**系统接口：** 此接口为系统接口。 324 325**系统能力：** SystemCapability.USB.USBManager 326 327**参数：** 328 329| 参数名 | 类型 | 必填 | 说明 | 330| --------- | ------------------------------- | ---- | ---------------- | 331| portId | number | 是 | 端口号。 | 332| powerRole | [PowerRoleType](#powerroletype) | 是 | 充电的角色。 | 333| dataRole | [DataRoleType](#dataroletype) | 是 | 数据传输的角色。 | 334 335**返回值：** 336 337| 类型 | 说明 | 338| ------------------- | ------------- | 339| Promise\<void\> | Promise对象。 | 340 341**错误码：** 342 343以下错误码的详细介绍请参见[USB服务错误码](errorcode-usb.md)。 344 345| 错误码ID | 错误信息 | 346| -------- | ------------------------------------------------------------------------------------------------------- | 347| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. | 348 349**示例：** 350 351```ts 352import {BusinessError} from '@kit.BasicServicesKit'; 353let portId: number = 1; 354usbManager.setPortRoles(portId, usbManager.PowerRoleType.SOURCE, usbManager.DataRoleType.HOST).then(() => { 355 console.info('usb setPortRoles successfully.'); 356}).catch((err: BusinessError) => { 357 console.error('usb setPortRoles failed: ' + err.code + ' message: ' + err.message); 358}); 359``` 360 361## addDeviceAccessRight<sup>12+</sup> 362 363addDeviceAccessRight(tokenId: string, deviceName: string): boolean 364 365添加软件包访问设备的权限。系统应用默认拥有访问设备权限，调用此接口不会产生影响。 366 367usbManager.requestRight (#usbrequestright)会触发弹框请求用户授权；addDeviceAccessRight不会触发弹框，而是直接添加软件包访问设备的权限。 368 369**说明：** 370 371> 从 API version 12开始支持。 372 373**系统接口：** 此接口为系统接口。 374 375**需要权限：** ohos.permission.MANAGE_USB_CONFIG 376 377**系统能力：** SystemCapability.USB.USBManager 378 379**参数：** 380 381| 参数名 | 类型 | 必填 | 说明 | 382| ---------- | ------ | ---- | --------------- | 383| deviceName | string | 是 | 设备名称。 | 384| tokenId | string | 是 | 软件包tokenId。 | 385 386**返回值：** 387 388| 类型 | 说明 | 389| ------- | ------------------------------------------------------------------------- | 390| boolean | 返回权限添加结果。返回true表示权限添加成功；返回false则表示权限添加失败。 | 391 392**错误码：** 393 394以下错误码的详细介绍请参见[USB服务错误码](errorcode-usb.md)。 395 396| 错误码ID | 错误信息 | 397| -------- | ------------------------------------------------------------------------------------------------------- | 398| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. | 399| 201 | Permission verification failed. The application does not have the permission required to call the API. | 400| 202 | Permission denied. Normal application do not have permission to use system api. | 401| 801 | Capability not supported. | 402 403**示例：** 404 405```ts 406import { bundleManager } from '@kit.AbilityKit'; 407import { BusinessError } from '@kit.BasicServicesKit'; 408let devicesName: string = "1-1"; 409let tokenId: string = ""; 410 411 try { 412 let bundleFlags = bundleManager.BundleFlag.GET_BUNDLE_INFO_DEFAULT; 413 bundleManager.getBundleInfoForSelf(bundleFlags).then((bundleInfo) => { 414 console.info('testTag', 'getBundleInfoForSelf successfully. Data: %{public}s', JSON.stringify(bundleInfo)); 415 let token = bundleInfo.appInfo.accessTokenId; 416 tokenId = token.toString(); 417 if (usbManager.addDeviceAccessRight(tokenId, devicesName)) { 418 console.log(`Succeed in adding right`); 419 } 420 }).catch((err : BusinessError) => { 421 console.error('testTag getBundleInfoForSelf failed' ); 422 }); 423 } catch (err) { 424 console.error('testTag failed'); 425 } 426``` 427 428## getFunctionsFromString<sup>12+</sup> 429 430getFunctionsFromString(funcs: string): number 431 432在设备模式下，将字符串形式的USB功能列表转化为数字掩码。 433 434**说明：** 435 436> 从 API version 12开始支持。 437 438**系统接口：** 此接口为系统接口。 439 440**需要权限：** ohos.permission.MANAGE_USB_CONFIG 441 442**系统能力：** SystemCapability.USB.USBManager 443 444**参数：** 445 446| 参数名 | 类型 | 必填 | 说明 | 447| ------ | ------ | ---- | ---------------------- | 448| funcs | string | 是 | 字符串形式的功能列表。 | 449 450**返回值：** 451 452| 类型 | 说明 | 453| ------ | ------------------ | 454| number | 转化后的数字掩码。 | 455 456**错误码：** 457 458以下错误码的详细介绍请参见[USB服务错误码](errorcode-usb.md)。 459 460| 错误码ID | 错误信息 | 461| -------- | ------------------------------------------------------------------------------- | 462| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. | 463| 201 | Permission verification failed. The application does not have the permission required to call the API. | 464| 202 | Permission denied. Normal application do not have permission to use system api. | 465| 801 | Capability not supported. | 466 467**示例：** 468 469```ts 470let funcs: string = "acm"; 471let ret: number = usbManager.getFunctionsFromString(funcs); 472``` 473 474## getStringFromFunctions<sup>12+</sup> 475 476getStringFromFunctions(funcs: FunctionType): string 477 478在设备模式下，将数字掩码形式的USB功能列表转化为字符串。 479 480**说明：** 481 482> 从 API version 12开始支持。 483 484**系统接口：** 此接口为系统接口。 485 486**需要权限：** ohos.permission.MANAGE_USB_CONFIG 487 488**系统能力：** SystemCapability.USB.USBManager 489 490**参数：** 491 492| 参数名 | 类型 | 必填 | 说明 | 493| ------ | ----------------------------- | ---- | ----------------- | 494| funcs | [FunctionType](#functiontype) | 是 | USB功能数字掩码。 | 495 496**返回值：** 497 498| 类型 | 说明 | 499| ------ | ------------------------------ | 500| string | 转化后的字符串形式的功能列表。 | 501 502**错误码：** 503 504以下错误码的详细介绍请参见[USB服务错误码](errorcode-usb.md)。 505 506| 错误码ID | 错误信息 | 507| -------- | ------------------------------------------------------------------------------------------------------- | 508| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. | 509| 201 | Permission verification failed. The application does not have the permission required to call the API. | 510| 202 | Permission denied. Normal application do not have permission to use system api. | 511| 801 | Capability not supported. | 512 513**示例：** 514 515```ts 516let funcs: number = usbManager.FunctionType.ACM | usbManager.FunctionType.ECM; 517let ret: string = usbManager.getStringFromFunctions(funcs); 518``` 519 520## setDeviceFunctions<sup>12+</sup> 521 522setDeviceFunctions(funcs: FunctionType): Promise\<void\> 523 524在设备模式下，设置当前的USB功能列表。 525 526**说明：** 527 528> 从 API version 12开始支持。 529 530**系统接口：** 此接口为系统接口。 531 532**需要权限：** ohos.permission.MANAGE_USB_CONFIG 533 534**系统能力：** SystemCapability.USB.USBManager 535 536**参数：** 537 538| 参数名 | 类型 | 必填 | 说明 | 539| ------ | ----------------------------- | ---- | ----------------- | 540| funcs | [FunctionType](#functiontype) | 是 | USB功能数字掩码。 | 541 542**返回值：** 543 544| 类型 | 说明 | 545| ------------------- | ------------- | 546| Promise\<void\> | Promise对象。 | 547 548**错误码：** 549 550以下错误码的详细介绍请参见[USB服务错误码](errorcode-usb.md)。 551 552| 错误码ID | 错误信息 | 553| -------- | ------------------------------------------------------------------------------------------------------- | 554| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. | 555| 201 | Permission verification failed. The application does not have the permission required to call the API. | 556| 202 | Permission denied. Normal application do not have permission to use system api. | 557| 801 | Capability not supported. | 558| 14400002 | Permission denied. The HDC is disabled by the system. | 559| 14400006 | Unsupported operation. The function is not supported. | 560 561**示例：** 562 563```ts 564import { BusinessError } from '@kit.BasicServicesKit'; 565let funcs: number = usbManager.FunctionType.HDC; 566usbManager.setDeviceFunctions(funcs).then(() => { 567 console.info('usb setDeviceFunctions successfully.'); 568}).catch((err : BusinessError) => { 569 console.error('usb setDeviceFunctions failed: ' + err.code + ' message: ' + err.message); 570}); 571``` 572 573## getDeviceFunctions<sup>12+</sup> 574 575getDeviceFunctions(): FunctionType 576 577在设备模式下，获取当前的USB功能列表的数字组合掩码。开发者模式关闭时，如果没有设备接入，接口可能返回`undefined`，注意需要对接口返回值做判空处理。 578 579**说明：** 580 581> 从 API version 12开始支持。 582 583**系统接口：** 此接口为系统接口。 584 585**需要权限：** ohos.permission.MANAGE_USB_CONFIG 586 587**系统能力：** SystemCapability.USB.USBManager 588 589**返回值：** 590 591| 类型 | 说明 | 592| ----------------------------- | --------------------------------- | 593| [FunctionType](#functiontype) | 当前的USB功能列表的数字组合掩码。 | 594 595**错误码：** 596 597以下错误码的详细介绍请参见[USB服务错误码](errorcode-usb.md)。 598 599| 错误码ID | 错误信息 | 600| -------- | ------------------------------------------------------------------------------- | 601| 401 | Parameter error. No parameters are required. | 602| 201 | Permission verification failed. The application does not have the permission required to call the API. | 603| 202 | Permission denied. Normal application do not have permission to use system api. | 604| 801 | Capability not supported. | 605 606**示例：** 607 608```ts 609let ret: number = usbManager.getDeviceFunctions(); 610``` 611 612## getPortList<sup>12+</sup> 613 614getPortList(): Array\<USBPort\> 615 616获取所有物理USB端口描述信息。开发者模式关闭时，如果没有设备接入，接口可能返回`undefined`，注意需要对接口返回值做判空处理。 617 618**说明：** 619 620> 从 API version 12开始支持。 621 622**系统接口：** 此接口为系统接口。 623 624**需要权限：** ohos.permission.MANAGE_USB_CONFIG 625 626**系统能力：** SystemCapability.USB.USBManager 627 628**返回值：** 629 630| 类型 | 说明 | 631| -------------------------- | --------------------- | 632| Array<[USBPort](#usbport)> | USB端口描述信息列表。 | 633 634**错误码：** 635 636以下错误码的详细介绍请参见[USB服务错误码](errorcode-usb.md)。 637 638| 错误码ID | 错误信息 | 639| -------- | ------------------------------------------------------------------------------------------------------- | 640| 201 | Permission verification failed. The application does not have the permission required to call the API. | 641| 202 | Permission denied. Normal application do not have permission to use system api. | 642| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. | 643| 801 | Capability not supported. | 644 645**示例：** 646 647```ts 648let ret: Array<usbManager.USBPort> = usbManager.getPortList(); 649``` 650 651## getPortSupportModes<sup>12+</sup> 652 653getPortSupportModes(portId: number): PortModeType 654 655获取指定的端口支持的模式列表的组合掩码。 656 657**系统接口：** 此接口为系统接口。 658 659**需要权限：** ohos.permission.MANAGE_USB_CONFIG 660 661**系统能力：** SystemCapability.USB.USBManager 662 663**参数：** 664 665| 参数名 | 类型 | 必填 | 说明 | 666| ------ | ------ | ---- | -------- | 667| portId | number | 是 | 端口号。 | 668 669**返回值：** 670 671| 类型 | 说明 | 672| ----------------------------- | -------------------------- | 673| [PortModeType](#portmodetype) | 支持的模式列表的组合掩码。 | 674 675**错误码：** 676 677以下错误码的详细介绍请参见[USB服务错误码](errorcode-usb.md)。 678 679| 错误码ID | 错误信息 | 680| -------- | ------------------------------------------------------------------------------------------------------- | 681| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. | 682| 201 | Permission verification failed. The application does not have the permission required to call the API. | 683| 202 | Permission denied. Normal application do not have permission to use system api. | 684| 801 | Capability not supported. | 685| 14400003 | Unsupported operation. The current device does not support port role switching. | 686 687**示例：** 688 689```ts 690let ret: number = usbManager.getPortSupportModes(0); 691``` 692 693## setPortRoleTypes<sup>12+</sup> 694 695setPortRoleTypes(portId: number, powerRole: PowerRoleType, dataRole: DataRoleType): Promise\<void\> 696 697设置指定的端口支持的角色模式，包含充电角色、数据传输角色。 698 699**说明：** 700 701> 从 API version 12开始支持。 702 703**系统接口：** 此接口为系统接口。 704 705**需要权限：** ohos.permission.MANAGE_USB_CONFIG 706 707**系统能力：** SystemCapability.USB.USBManager 708 709**参数：** 710 711| 参数名 | 类型 | 必填 | 说明 | 712| --------- | ------------------------------- | ---- | ---------------- | 713| portId | number | 是 | 端口号。 | 714| powerRole | [PowerRoleType](#powerroletype) | 是 | 充电的角色。 | 715| dataRole | [DataRoleType](#dataroletype) | 是 | 数据传输的角色。 | 716 717**返回值：** 718 719| 类型 | 说明 | 720| ------------------- | ------------- | 721| Promise\<void\> | Promise对象。 | 722 723**错误码：** 724 725以下错误码的详细介绍请参见[USB服务错误码](errorcode-usb.md)。 726 727| 错误码ID | 错误信息 | 728| -------- | ------------------------------------------------------------------------------------------------------- | 729| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. | 730| 201 | Permission verification failed. The application does not have the permission required to call the API. | 731| 202 | Permission denied. Normal application do not have permission to use system api. | 732| 801 | Capability not supported. | 733| 14400003 | Unsupported operation. The current device does not support port role switching. | 734 735**示例：** 736 737```ts 738import { BusinessError } from '@kit.BasicServicesKit'; 739let portId: number = 1; 740usbManager.setPortRoleTypes(portId, usbManager.PowerRoleType.SOURCE, usbManager.DataRoleType.HOST).then(() => { 741 console.info('usb setPortRoleTypes successfully.'); 742}).catch((err : BusinessError) => { 743 console.error('usb setPortRoleTypes failed: ' + err.code + ' message: ' + err.message); 744}); 745``` 746 747## addAccessoryRight<sup>14+<sup> 748 749addAccessoryRight(tokenId: number, accessory: USBAccessory): void 750 751为应用程序添加访问USB配件权限。 752 753usbManager.requestAccessoryRight会触发弹窗请求用户授权；addAccessoryRight不会触发弹窗，而是直接添加应用程序访问设备的权限。 754 755**系统接口：** 此接口为系统接口。 756 757**需要权限：** ohos.permission.MANAGE_USB_CONFIG 758 759**系统能力：** SystemCapability.USB.USBManager 760 761**参数：** 762 763| 参数名 | 类型 | 必填 | 说明 | 764| --------- | ------------ | ---- | ------------------------ | 765| tokenId | number | 是 | 应用程序tokenId。 | 766| accessory | USBAccessory | 是 | USB配件。 | 767 768**错误码：** 769 770以下错误码的详细介绍请参见[USB服务错误码](errorcode-usb.md)。 771 772| 错误码ID | 错误信息 | 773| -------- | ------------------------------------------------------------ | 774| 201 | The permission check failed. | 775| 202 | Permission denied. Normal application do not have permission to use system api. | 776| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. | 777| 801 | Capability not supported. | 778| 14400004 | Service exception. Possible causes: 1. No accessory is plugged in. | 779| 14400005 | Database operation exception. | 780 781**示例：** 782 783```ts 784import { hilog } from '@kit.PerformanceAnalysisKit'; 785import { bundleManager } from '@kit.AbilityKit'; 786try { 787 let accList: usbManager.USBAccessory[] = usbManager.getAccessoryList() 788 let flags = bundleManager.BundleFlag.GET_BUNDLE_INFO_WITH_APPLICATION | bundleManager.BundleFlag.GET_BUNDLE_INFO_WITH_EXTENSION_ABILITY 789 let bundleInfo = await bundleManager.getBundleInfoForSelf(flags) 790 let tokenId: number = bundleInfo.appInfo.accessTokenId 791 usbManager.addAccessoryRight(tokenId, accList[0]) 792 hilog.info(0, 'testTag ui', `addAccessoryRight success`) 793} catch (error) { 794 hilog.info(0, 'testTag ui', `addAccessoryRight error ${error.code}, message is ${error.message}`) 795} 796``` 797 798## USBPort 799 800USB设备端口。 801 802**系统接口：** 此接口为系统接口。 803 804**系统能力：** SystemCapability.USB.USBManager 805 806| 名称 | 类型 | 必填 | 说明 | 807| -------------- | ------------------------------- | ---- | ----------------------------------- | 808| id | number | 是 | USB端口唯一标识。 | 809| supportedModes | [PortModeType](#portmodetype) | 是 | USB端口所支持的模式的数字组合掩码。 | 810| status | [USBPortStatus](#usbportstatus) | 是 | USB端口角色。 | 811 812## USBPortStatus 813 814USB设备端口角色信息。 815 816**系统接口：** 此接口为系统接口。 817 818**系统能力：** SystemCapability.USB.USBManager 819 820| 名称 | 类型 | 必填 | 说明 | 821| ---------------- | ------ | ---- | ---------------------- | 822| currentMode | number | 是 | 当前的USB模式。 | 823| currentPowerRole | number | 是 | 当前设备充电模式。 | 824| currentDataRole | number | 是 | 当前设备数据传输模式。 | 825 826## FunctionType 827 828USB设备侧功能。 829 830**系统接口：** 此接口为系统接口。 831 832**系统能力：** SystemCapability.USB.USBManager 833 834| 名称 | 值 | 说明 | 835| ------------ | --- | ---------- | 836| NONE | 0 | 没有功能。 | 837| ACM | 1 | acm功能。 | 838| ECM | 2 | ecm功能。 | 839| HDC | 4 | hdc功能。 | 840| MTP | 8 | 媒体传输。 | 841| PTP | 16 | 图片传输。 | 842| RNDIS | 32 | 网络共享（暂不支持）。 | 843| MIDI | 64 | midi功能（暂不支持）。 | 844| AUDIO_SOURCE | 128 | 音频功能（暂不支持）。 | 845| NCM | 256 | ncm传输（暂不支持）。 | 846 847## PortModeType 848 849USB端口模式类型。 850 851**系统接口：** 此接口为系统接口。 852 853**系统能力：** SystemCapability.USB.USBManager 854 855| 名称 | 值 | 说明 | 856| --------- | -- | ---------------------------------------------------- | 857| NONE | 0 | 无。 | 858| UFP | 1 | 数据上行，需要外部供电。 | 859| DFP | 2 | 数据下行，对外提供电源。 | 860| DRP | 3 | 既可以做DFP(Host)，也可以做UFP(Device)，当前不支持。 | 861| NUM_MODES | 4 | 当前不支持。 | 862 863## PowerRoleType 864 865电源角色类型。 866 867**系统接口：** 此接口为系统接口。 868 869**系统能力：** SystemCapability.USB.USBManager 870 871| 名称 | 值 | 说明 | 872| ------ | -- | ---------- | 873| NONE | 0 | 无。 | 874| SOURCE | 1 | 对外提供电源。 | 875| SINK | 2 | 需要外部供电。 | 876 877## DataRoleType 878 879数据角色类型。 880 881**系统接口：** 此接口为系统接口。 882 883**系统能力：** SystemCapability.USB.USBManager 884 885| 名称 | 值 | 说明 | 886| ------ | -- | ------------ | 887| NONE | 0 | 无。 | 888| HOST | 1 | 主设备角色。 | 889| DEVICE | 2 | 从设备角色。 | 890 891