1# @ohos.enterprise.usbManager（USB管理）(系统接口) 2 3本模块提供USB管理能力。 4 5> **说明**： 6> 7> 本模块首批接口从API version 10开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。 8> 9> 本模块接口仅可在Stage模型下使用。 10> 11> 本模块接口仅对[设备管理应用](enterpriseDeviceManagement-overview.md#基本概念)开放，需将[设备管理应用激活](js-apis-enterprise-adminManager-sys.md#adminmanagerenableadmin)后调用，实现相应功能。 12> 13> 本模块接口均为系统接口。 14 15## 导入模块 16 17```ts 18import usbManager from '@ohos.enterprise.usbManager'; 19``` 20 21## usbManager.setUsbPolicy 22 23setUsbPolicy(admin: Want, usbPolicy: UsbPolicy, callback: AsyncCallback\<void>): void 24 25指定设备管理应用设置USB的读写策略。使用callback异步回调。 26 27**需要权限：** ohos.permission.ENTERPRISE_MANAGE_USB 28 29**系统能力：** SystemCapability.Customization.EnterpriseDeviceManager 30 31 32 33**参数：** 34 35| 参数名 | 类型 | 必填 | 说明 | 36| ----- | ----------------------------------- | ---- | ------- | 37| admin | [Want](../apis-ability-kit/js-apis-app-ability-want.md) | 是 | 设备管理应用。 | 38| usbPolicy | [UsbPolicy](#usbpolicy) | 是 | USB读写策略（此接口只支持READ_WRITE和READ_ONLY）。 | 39| callback | AsyncCallback\<void> | 是 | 回调函数。当接口调用成功，err为null，否则为错误对象。 | 40 41**错误码**： 42 43以下错误码的详细介绍请参见[企业设备管理错误码](errorcode-enterpriseDeviceManager.md) 44 45| 错误码ID | 错误信息 | 46| ------- | ---------------------------------------------------------------------------- | 47| 9200001 | the application is not an administrator of the device. | 48| 9200002 | the administrator application does not have permission to manage the device. | 49 50**示例：** 51 52```ts 53import Want from '@ohos.app.ability.Want'; 54let wantTemp: Want = { 55 bundleName: 'bundleName', 56 abilityName: 'abilityName', 57}; 58let policy: usbManager.UsbPolicy = usbManager.UsbPolicy.READ_WRITE 59 60usbManager.setUsbPolicy(wantTemp, policy, (err) => { 61 if (err) { 62 console.error(`Failed to set usb policy. Code is ${err.code}, message is ${err.message}`); 63 return; 64 } 65 console.info('Succeeded in setting usb policy'); 66}) 67``` 68 69## usbManager.setUsbPolicy 70 71setUsbPolicy(admin: Want, usbPolicy: UsbPolicy): Promise\<void> 72 73指定设备管理应用设置USB的读写策略。使用Promise异步回调。 74 75**需要权限：** ohos.permission.ENTERPRISE_MANAGE_USB 76 77**系统能力：** SystemCapability.Customization.EnterpriseDeviceManager 78 79 80 81**参数：** 82 83| 参数名 | 类型 | 必填 | 说明 | 84| ----- | ----------------------------------- | ---- | ------- | 85| admin | [Want](../apis-ability-kit/js-apis-app-ability-want.md) | 是 | 设备管理应用。 | 86| usbPolicy | [UsbPolicy](#usbpolicy) | 是 | USB读写策略（此接口只支持READ_WRITE和READ_ONLY）。 | 87 88**返回值：** 89 90| 类型 | 说明 | 91| ----- | ----------------------------------- | 92| Promise\<void> | 无返回结果的Promise对象。当指定设备管理应用设置USB策略失败时抛出错误对象。 | 93 94**错误码**： 95 96以下错误码的详细介绍请参见[企业设备管理错误码](errorcode-enterpriseDeviceManager.md) 97 98| 错误码ID | 错误信息 | 99| ------- | ---------------------------------------------------------------------------- | 100| 9200001 | the application is not an administrator of the device. | 101| 9200002 | the administrator application does not have permission to manage the device. | 102 103**示例：** 104 105```ts 106import Want from '@ohos.app.ability.Want'; 107import { BusinessError } from '@ohos.base'; 108let wantTemp: Want = { 109 bundleName: 'bundleName', 110 abilityName: 'abilityName', 111}; 112let policy: usbManager.UsbPolicy = usbManager.UsbPolicy.READ_WRITE 113 114usbManager.setUsbPolicy(wantTemp, policy).then(() => { 115 console.info('Succeeded in setting usb policy'); 116}).catch((err: BusinessError) => { 117 console.error(`Failed to set usb policy. Code is ${err.code}, message is ${err.message}`); 118}) 119``` 120 121## UsbPolicy 122 123USB读写策略的枚举。 124 125**系统能力：** SystemCapability.Customization.EnterpriseDeviceManager 126 127 128 129| 名称 | 值 | 说明 | 130| -------- | -------- | -------- | 131| READ_WRITE | 0 | 可读可写。 | 132| READ_ONLY | 1 | 只读。 | 133| DISABLED<sup>11+</sup> | 2 | 禁用。 | 134 135## UsbDeviceId<sup>11+</sup> 136 137USB设备ID信息。 138 139**系统能力：** SystemCapability.Customization.EnterpriseDeviceManager 140 141 142 143| 名称 | 类型 | 必填 | 说明 | 144| --------- | ------ | ---- | -------- | 145| vendorId | number | 是 | 厂商ID。 | 146| productId | number | 是 | 产品ID。 | 147 148## usbManager.disableUsb<sup>11+</sup> 149 150disableUsb(admin: Want, disable: boolean): void 151 152指定设备管理应用设置禁用或启用USB。 153 154**需要权限：** ohos.permission.ENTERPRISE_MANAGE_USB 155 156**系统能力：** SystemCapability.Customization.EnterpriseDeviceManager 157 158 159 160**参数：** 161 162| 参数名 | 类型 | 必填 | 说明 | 163| ------- | ----------------------------------- | ---- | ------------------------------------------------ | 164| admin | [Want](../apis-ability-kit/js-apis-app-ability-want.md) | 是 | 设备管理应用。 | 165| disable | boolean | 是 | 是否禁用USB设备，true表示禁用，false表示不禁用。 | 166 167**错误码**： 168 169以下错误码的详细介绍请参见[企业设备管理错误码](errorcode-enterpriseDeviceManager.md) 170 171| 错误码ID | 错误信息 | 172| -------- | ------------------------------------------------------------ | 173| 9200001 | the application is not an administrator of the device. | 174| 9200002 | the administrator application does not have permission to manage the device. | 175| 9200010 | a conflicting policy has been configured. | 176 177**示例：** 178 179```ts 180import Want from '@ohos.app.ability.Want'; 181let wantTemp: Want = { 182 bundleName: 'com.example.myapplication', 183 abilityName: 'EntryAbility', 184}; 185try { 186 usbManager.disableUsb(wantTemp, true); 187 console.info(`Succeeded in disabling USB`); 188} catch (err) { 189 console.error(`Failed to disabling USB. Code: ${err.code}, message: ${err.message}`); 190} 191``` 192 193## usbManager.isUsbDisabled<sup>11+</sup> 194 195isUsbDisabled(admin: Want): boolean 196 197指定设备管理应用查询USB是否禁用。 198 199**需要权限：** ohos.permission.ENTERPRISE_MANAGE_USB 200 201**系统能力：** SystemCapability.Customization.EnterpriseDeviceManager 202 203 204 205**参数：** 206 207| 参数名 | 类型 | 必填 | 说明 | 208| ------ | ----------------------------------- | ---- | -------------- | 209| admin | [Want](../apis-ability-kit/js-apis-app-ability-want.md) | 是 | 设备管理应用。 | 210 211**返回值：** 212 213| 类型 | 说明 | 214| ------- | ------------------------------------------------------ | 215| boolean | 返回true表示USB被禁用，<br/>返回false表示USB未被禁用。 | 216 217**错误码**： 218 219以下错误码的详细介绍请参见[企业设备管理错误码](errorcode-enterpriseDeviceManager.md) 220 221| 错误码ID | 错误信息 | 222| -------- | ------------------------------------------------------------ | 223| 9200001 | the application is not an administrator of the device. | 224| 9200002 | the administrator application does not have permission to manage the device. | 225 226**示例：** 227 228```ts 229import Want from '@ohos.app.ability.Want'; 230let wantTemp: Want = { 231 bundleName: 'com.example.myapplication', 232 abilityName: 'EntryAbility', 233}; 234try { 235 let isDisabled = usbManager.isUsbDisabled(wantTemp); 236 console.info(`Succeeded in querying if USB is disabled: ${isDisabled}`); 237} catch (err) { 238 console.error(`Failed to query if USB is disabled. Code: ${err.code}, message: ${err.message}`); 239} 240``` 241 242## usbManager.addAllowedUsbDevices<sup>11+</sup> 243 244addAllowedUsbDevices(admin: Want, usbDeviceIds: Array\<UsbDeviceId>): void 245 246指定设备管理应用添加USB设备可用白名单。 247 248**需要权限：** ohos.permission.ENTERPRISE_MANAGE_USB 249 250**系统能力：** SystemCapability.Customization.EnterpriseDeviceManager 251 252 253 254**参数：** 255 256| 参数名 | 类型 | 必填 | 说明 | 257| ------------ | ------------------------------------ | ---- | ------------------------------------------- | 258| admin | [Want](../apis-ability-kit/js-apis-app-ability-want.md) | 是 | 设备管理应用。 | 259| usbDeviceIds | Array<[UsbDeviceId](#usbdeviceid11)> | 是 | USB设备ID数组。添加后的数组长度上限为1000。 | 260 261**错误码**： 262 263以下错误码的详细介绍请参见[企业设备管理错误码](errorcode-enterpriseDeviceManager.md) 264 265| 错误码ID | 错误信息 | 266| -------- | ------------------------------------------------------------ | 267| 9200001 | the application is not an administrator of the device. | 268| 9200002 | the administrator application does not have permission to manage the device. | 269| 9200010 | a conflicting policy has been configured. | 270 271**示例：** 272 273```ts 274import Want from '@ohos.app.ability.Want'; 275let wantTemp: Want = { 276 bundleName: 'com.example.myapplication', 277 abilityName: 'EntryAbility', 278}; 279try { 280 let usbDeviceIds: Array<usbManager.UsbDeviceId> = [{ 281 vendorId: 1, 282 productId: 1 283 }]; 284 usbManager.addAllowedUsbDevices(wantTemp, usbDeviceIds); 285 console.info(`Succeeded in adding allowed USB devices`); 286} catch (err) { 287 console.error(`Failed to adding allowed USB devices. Code: ${err.code}, message: ${err.message}`); 288} 289``` 290 291## usbManager.removeAllowedUsbDevices<sup>11+</sup> 292 293removeAllowedUsbDevices(admin: Want, usbDeviceIds: Array\<UsbDeviceId>): void 294 295指定设备管理应用移除USB设备可用白名单。 296 297**需要权限：** ohos.permission.ENTERPRISE_MANAGE_USB 298 299**系统能力：** SystemCapability.Customization.EnterpriseDeviceManager 300 301 302 303**参数：** 304 305| 参数名 | 类型 | 必填 | 说明 | 306| ------------ | ------------------------------------ | ---- | --------------- | 307| admin | [Want](../apis-ability-kit/js-apis-app-ability-want.md) | 是 | 设备管理应用。 | 308| usbDeviceIds | Array<[UsbDeviceId](#usbdeviceid11)> | 是 | USB设备ID数组。 | 309 310**错误码**： 311 312以下错误码的详细介绍请参见[企业设备管理错误码](errorcode-enterpriseDeviceManager.md) 313 314| 错误码ID | 错误信息 | 315| -------- | ------------------------------------------------------------ | 316| 9200001 | the application is not an administrator of the device. | 317| 9200002 | the administrator application does not have permission to manage the device. | 318 319**示例：** 320 321```ts 322import Want from '@ohos.app.ability.Want'; 323let wantTemp: Want = { 324 bundleName: 'com.example.myapplication', 325 abilityName: 'EntryAbility', 326}; 327try { 328 let usbDeviceIds: Array<usbManager.UsbDeviceId> = [{ 329 vendorId: 1, 330 productId: 1 331 }]; 332 usbManager.removeAllowedUsbDevices(wantTemp, usbDeviceIds); 333 console.info(`Succeeded in removing allowed USB devices`); 334} catch (err) { 335 console.error(`Failed to removing allowed USB devices. Code: ${err.code}, message: ${err.message}`); 336} 337``` 338 339## usbManager.getAllowedUsbDevices<sup>11+</sup> 340 341getAllowedUsbDevices(admin: Want): Array\<UsbDeviceId> 342 343指定设备管理应用获取USB设备可用白名单。 344 345**需要权限：** ohos.permission.ENTERPRISE_MANAGE_USB 346 347**系统能力：** SystemCapability.Customization.EnterpriseDeviceManager 348 349 350 351**参数：** 352 353| 参数名 | 类型 | 必填 | 说明 | 354| ------ | ----------------------------------- | ---- | -------------- | 355| admin | [Want](../apis-ability-kit/js-apis-app-ability-want.md) | 是 | 设备管理应用。 | 356 357**返回值：** 358 359| 类型 | 说明 | 360| ------------------------------------ | ------------------------- | 361| Array<[UsbDeviceId](#usbdeviceid11)> | 可用USB白名单设备ID数组。 | 362 363**错误码**： 364 365以下错误码的详细介绍请参见[企业设备管理错误码](errorcode-enterpriseDeviceManager.md) 366 367| 错误码ID | 错误信息 | 368| -------- | ------------------------------------------------------------ | 369| 9200001 | the application is not an administrator of the device. | 370| 9200002 | the administrator application does not have permission to manage the device. | 371 372**示例：** 373 374```ts 375import Want from '@ohos.app.ability.Want'; 376let wantTemp: Want = { 377 bundleName: 'com.example.myapplication', 378 abilityName: 'EntryAbility', 379}; 380try { 381 let result: Array<usbManager.UsbDeviceId> = usbManager.getAllowedUsbDevices(wantTemp); 382 console.info(`Succeeded in removing allowed USB devices. Result: ${JSON.stringify(result)}`); 383} catch (err) { 384 console.error(`Failed to removing allowed USB devices. Code: ${err.code}, message: ${err.message}`); 385} 386``` 387 388## usbManager.setUsbStorageDeviceAccessPolicy<sup>11+</sup> 389 390setUsbStorageDeviceAccessPolicy(admin: Want, usbPolicy: UsbPolicy): void 391 392指定设备管理应用设置USB存储设备访问策略。 393 394**需要权限：** ohos.permission.ENTERPRISE_MANAGE_USB 395 396**系统能力：** SystemCapability.Customization.EnterpriseDeviceManager 397 398 399 400**参数：** 401 402| 参数名 | 类型 | 必填 | 说明 | 403| --------- | ----------------------------------- | ---- | --------------------- | 404| admin | [Want](../apis-ability-kit/js-apis-app-ability-want.md) | 是 | 设备管理应用。 | 405| usbPolicy | [UsbPolicy](#usbpolicy) | 是 | USB存储设备访问策略。 | 406 407**错误码**： 408 409以下错误码的详细介绍请参见[企业设备管理错误码](errorcode-enterpriseDeviceManager.md) 410 411| 错误码ID | 错误信息 | 412| -------- | ------------------------------------------------------------ | 413| 9200001 | the application is not an administrator of the device. | 414| 9200002 | the administrator application does not have permission to manage the device. | 415| 9200010 | a conflicting policy has been configured. | 416 417**示例：** 418 419```ts 420import Want from '@ohos.app.ability.Want'; 421let wantTemp: Want = { 422 bundleName: 'com.example.myapplication', 423 abilityName: 'EntryAbility', 424}; 425try { 426 let policy: usbManager.UsbPolicy = usbManager.UsbPolicy.DISABLED; 427 usbManager.setUsbStorageDeviceAccessPolicy(wantTemp, policy); 428 console.info(`Succeeded in setting USB storage device access policy`); 429} catch (err) { 430 console.error(`Failed to setting USB storage device access policy. Code: ${err.code}, message: ${err.message}`); 431} 432``` 433 434## usbManager.getUsbStorageDeviceAccessPolicy<sup>11+</sup> 435 436getUsbStorageDeviceAccessPolicy(admin: Want): UsbPolicy 437 438指定设备管理应用获取USB存储设备访问策略。 439 440**需要权限：** ohos.permission.ENTERPRISE_MANAGE_USB 441 442**系统能力：** SystemCapability.Customization.EnterpriseDeviceManager 443 444 445 446**参数：** 447 448| 参数名 | 类型 | 必填 | 说明 | 449| ------ | ----------------------------------- | ---- | -------------- | 450| admin | [Want](../apis-ability-kit/js-apis-app-ability-want.md) | 是 | 设备管理应用。 | 451 452**返回值：** 453 454| 类型 | 说明 | 455| ----------------------- | --------------------- | 456| [UsbPolicy](#usbpolicy) | USB存储设备访问策略。 | 457 458**错误码**： 459 460以下错误码的详细介绍请参见[企业设备管理错误码](errorcode-enterpriseDeviceManager.md) 461 462| 错误码ID | 错误信息 | 463| -------- | ------------------------------------------------------------ | 464| 9200001 | the application is not an administrator of the device. | 465| 9200002 | the administrator application does not have permission to manage the device. | 466 467**示例：** 468 469```ts 470import Want from '@ohos.app.ability.Want'; 471let wantTemp: Want = { 472 bundleName: 'com.example.myapplication', 473 abilityName: 'EntryAbility', 474}; 475try { 476 let result: usbManager.UsbPolicy = usbManager.getUsbStorageDeviceAccessPolicy(wantTemp); 477 console.info(`Succeeded in getting USB storage device access policy. Result: ${JSON.stringify(result)}`); 478} catch (err) { 479 console.error(`Failed togetting USB storage device access policy. Code: ${err.code}, message: ${err.message}`); 480} 481``` 482