1# @ohos.enterprise.usbManager (USB Management) 2 3The **usbManager** module provides APIs for USB management. 4 5> **NOTE** 6> 7> - The initial APIs of this module are supported since API version 10. Newly added APIs will be marked with a superscript to indicate their earliest API version. 8> 9> - The APIs of this module can be used only in the stage model. 10> 11> - The APIs provided by this module can be called only by a [device administrator application](enterpriseDeviceManagement-overview.md#basic-concepts) that is [enabled](js-apis-enterprise-adminManager.md#adminmanagerenableadmin). 12 13## Modules to Import 14 15```ts 16import usbManager from '@ohos.enterprise.usbManager'; 17``` 18 19## usbManager.setUsbPolicy 20 21setUsbPolicy(admin: Want, usbPolicy: UsbPolicy, callback: AsyncCallback\<void>): void 22 23Sets the USB access policy through the specified device administrator application. This API uses an asynchronous callback to return the result. 24 25Required permissions: ohos.permission.ENTERPRISE_MANAGE_USB 26 27**System capability**: SystemCapability.Customization.EnterpriseDeviceManager 28 29**System API**: This is a system API. 30 31**Parameters** 32 33| Name | Type | Mandatory | Description | 34| ----- | ----------------------------------- | ---- | ------- | 35| admin | [Want](js-apis-app-ability-want.md) | Yes | Device administrator application.| 36| usbPolicy | [UsbPolicy](#usbpolicy) | Yes| USB access policy. This API supports **READ_WRITE** and **READ_ONLY** only.| 37| callback | AsyncCallback\<void> | Yes| Callback invoked to return the result. If the operation is successful, **err** is **null**. Otherwise, **err** is an error object.| 38 39**Error codes** 40 41For details about the error codes, see [Enterprise Device Management Error Codes](../errorcodes/errorcode-enterpriseDeviceManager.md). 42 43| ID| Error Message | 44| ------- | ---------------------------------------------------------------------------- | 45| 9200001 | the application is not an administrator of the device. | 46| 9200002 | the administrator application does not have permission to manage the device. | 47 48**Example** 49 50```ts 51import Want from '@ohos.app.ability.Want'; 52let wantTemp: Want = { 53 bundleName: 'bundleName', 54 abilityName: 'abilityName', 55}; 56let policy: usbManager.UsbPolicy = usbManager.UsbPolicy.READ_WRITE 57 58usbManager.setUsbPolicy(wantTemp, policy, (err) => { 59 if (err) { 60 console.error(`Failed to set usb policy. Code is ${err.code}, message is ${err.message}`); 61 return; 62 } 63 console.info('Succeeded in setting usb policy'); 64}) 65``` 66 67## usbManager.setUsbPolicy 68 69setUsbPolicy(admin: Want, usbPolicy: UsbPolicy): Promise\<void> 70 71Sets the USB access policy through the specified device administrator application. This API uses a promise to return the result. 72 73Required permissions: ohos.permission.ENTERPRISE_MANAGE_USB 74 75**System capability**: SystemCapability.Customization.EnterpriseDeviceManager 76 77**System API**: This is a system API. 78 79**Parameters** 80 81| Name | Type | Mandatory | Description | 82| ----- | ----------------------------------- | ---- | ------- | 83| admin | [Want](js-apis-app-ability-want.md) | Yes | Device administrator application.| 84| usbPolicy | [UsbPolicy](#usbpolicy) | Yes| USB access policy. This API supports **READ_WRITE** and **READ_ONLY** only.| 85 86**Return value** 87 88| Type | Description | 89| ----- | ----------------------------------- | 90| Promise\<void> | Promise that returns no value. An error object will be thrown if the operation fails.| 91 92**Error codes** 93 94For details about the error codes, see [Enterprise Device Management Error Codes](../errorcodes/errorcode-enterpriseDeviceManager.md). 95 96| ID| Error Message | 97| ------- | ---------------------------------------------------------------------------- | 98| 9200001 | the application is not an administrator of the device. | 99| 9200002 | the administrator application does not have permission to manage the device. | 100 101**Example** 102 103```ts 104import Want from '@ohos.app.ability.Want'; 105import { BusinessError } from '@ohos.base'; 106let wantTemp: Want = { 107 bundleName: 'bundleName', 108 abilityName: 'abilityName', 109}; 110let policy: usbManager.UsbPolicy = usbManager.UsbPolicy.READ_WRITE 111 112usbManager.setUsbPolicy(wantTemp, policy).then(() => { 113 console.info('Succeeded in setting usb policy'); 114}).catch((err: BusinessError) => { 115 console.error(`Failed to set usb policy. Code is ${err.code}, message is ${err.message}`); 116}) 117``` 118 119## UsbPolicy 120 121Enumerates the USB access policies. 122 123**System capability**: SystemCapability.Customization.EnterpriseDeviceManager 124 125**System API**: This is a system API. 126 127| Name| Value| Description| 128| -------- | -------- | -------- | 129| READ_WRITE | 0 | Read and write.| 130| READ_ONLY | 1 | Read only.| 131| DISABLED<sup>11+</sup> | 2 | Disabled.| 132 133## UsbDeviceId<sup>11+</sup> 134 135Represents the USB device identity information. 136 137**System capability**: SystemCapability.Customization.EnterpriseDeviceManager 138 139**System API**: This is a system API. 140 141| Name | Type | Mandatory| Description | 142| --------- | ------ | ---- | -------- | 143| vendorId | number | Yes | Vendor ID.| 144| productId | number | Yes | Product ID.| 145 146## usbManager.disableUsb<sup>11+</sup> 147 148disableUsb(admin: Want, disable: boolean): void 149 150Enables or disables USB through the specified device administrator application. 151 152Required permissions: ohos.permission.ENTERPRISE_MANAGE_USB 153 154**System capability**: SystemCapability.Customization.EnterpriseDeviceManager 155 156**System API**: This is a system API. 157 158**Parameters** 159 160| Name | Type | Mandatory| Description | 161| ------- | ----------------------------------- | ---- | ------------------------------------------------ | 162| admin | [Want](js-apis-app-ability-want.md) | Yes | Device administrator application. | 163| disable | boolean | Yes | Whether to disable USB. The value **true** means to disable USB; the value **false** means the opposite.| 164 165**Error codes** 166 167For details about the error codes, see [Enterprise Device Management Error Codes](../errorcodes/errorcode-enterpriseDeviceManager.md). 168 169| ID| Error Message | 170| -------- | ------------------------------------------------------------ | 171| 9200001 | the application is not an administrator of the device. | 172| 9200002 | the administrator application does not have permission to manage the device. | 173| 9200010 | a conflicting policy has been configured. | 174 175**Example** 176 177```ts 178import Want from '@ohos.app.ability.Want'; 179let wantTemp: Want = { 180 bundleName: 'com.example.myapplication', 181 abilityName: 'EntryAbility', 182}; 183try { 184 usbManager.disableUsb(wantTemp, true); 185 console.info(`Succeeded in disabling USB`); 186} catch (err) { 187 console.error(`Failed to disabling USB. Code: ${err.code}, message: ${err.message}`); 188} 189``` 190 191## usbManager.isUsbDisabled<sup>11+</sup> 192 193isUsbDisabled(admin: Want): boolean 194 195Checks whether USB is disabled through the specified device administrator application. 196 197Required permissions: ohos.permission.ENTERPRISE_MANAGE_USB 198 199**System capability**: SystemCapability.Customization.EnterpriseDeviceManager 200 201**System API**: This is a system API. 202 203**Parameters** 204 205| Name| Type | Mandatory| Description | 206| ------ | ----------------------------------- | ---- | -------------- | 207| admin | [Want](js-apis-app-ability-want.md) | Yes | Device administrator application.| 208 209**Return value** 210 211| Type | Description | 212| ------- | ------------------------------------------------------ | 213| boolean | Returns **true** if USB is disabled; returns **false** otherwise. | 214 215**Error codes** 216 217For details about the error codes, see [Enterprise Device Management Error Codes](../errorcodes/errorcode-enterpriseDeviceManager.md). 218 219| ID| Error Message | 220| -------- | ------------------------------------------------------------ | 221| 9200001 | the application is not an administrator of the device. | 222| 9200002 | the administrator application does not have permission to manage the device. | 223 224**Example** 225 226```ts 227import Want from '@ohos.app.ability.Want'; 228let wantTemp: Want = { 229 bundleName: 'com.example.myapplication', 230 abilityName: 'EntryAbility', 231}; 232try { 233 let isDisabled = usbManager.isUsbDisabled(wantTemp); 234 console.info(`Succeeded in querying if USB is disabled: ${isDisabled}`); 235} catch (err) { 236 console.error(`Failed to query if USB is disabled. Code: ${err.code}, message: ${err.message}`); 237} 238``` 239 240## usbManager.addAllowedUsbDevices<sup>11+</sup> 241 242addAllowedUsbDevices(admin: Want, usbDeviceIds: Array\<UsbDeviceId>): void 243 244Adds allowed USB devices through the specified device administrator application. 245 246Required permissions: ohos.permission.ENTERPRISE_MANAGE_USB 247 248**System capability**: SystemCapability.Customization.EnterpriseDeviceManager 249 250**System API**: This is a system API. 251 252**Parameters** 253 254| Name | Type | Mandatory| Description | 255| ------------ | ------------------------------------ | ---- | ------------------------------------------- | 256| admin | [Want](js-apis-app-ability-want.md) | Yes | Device administrator application. | 257| usbDeviceIds | Array<[UsbDeviceId](#usbdeviceid11)> | Yes | IDs of the allowed USB devices to add. This array can hold a maximum of 1000 device IDs.| 258 259**Error codes** 260 261For details about the error codes, see [Enterprise Device Management Error Codes](../errorcodes/errorcode-enterpriseDeviceManager.md). 262 263| ID| Error Message | 264| -------- | ------------------------------------------------------------ | 265| 9200001 | the application is not an administrator of the device. | 266| 9200002 | the administrator application does not have permission to manage the device. | 267| 9200010 | a conflicting policy has been configured. | 268 269**Example** 270 271```ts 272import Want from '@ohos.app.ability.Want'; 273let wantTemp: Want = { 274 bundleName: 'com.example.myapplication', 275 abilityName: 'EntryAbility', 276}; 277try { 278 let usbDeviceIds: Array<usbManager.UsbDeviceId> = [{ 279 vendorId: 1, 280 productId: 1 281 }]; 282 usbManager.addAllowedUsbDevices(wantTemp, usbDeviceIds); 283 console.info(`Succeeded in adding allowed USB devices`); 284} catch (err) { 285 console.error(`Failed to adding allowed USB devices. Code: ${err.code}, message: ${err.message}`); 286} 287``` 288 289## usbManager.removeAllowedUsbDevices<sup>11+</sup> 290 291removeAllowedUsbDevices(admin: Want, usbDeviceIds: Array\<UsbDeviceId>): void 292 293Removes allowed USB devices through the specified device administrator application. 294 295Required permissions: ohos.permission.ENTERPRISE_MANAGE_USB 296 297**System capability**: SystemCapability.Customization.EnterpriseDeviceManager 298 299**System API**: This is a system API. 300 301**Parameters** 302 303| Name | Type | Mandatory| Description | 304| ------------ | ------------------------------------ | ---- | --------------- | 305| admin | [Want](js-apis-app-ability-want.md) | Yes | Device administrator application. | 306| usbDeviceIds | Array<[UsbDeviceId](#usbdeviceid11)> | Yes | IDs of the allowed USB devices to remove.| 307 308**Error codes** 309 310For details about the error codes, see [Enterprise Device Management Error Codes](../errorcodes/errorcode-enterpriseDeviceManager.md). 311 312| ID| Error Message | 313| -------- | ------------------------------------------------------------ | 314| 9200001 | the application is not an administrator of the device. | 315| 9200002 | the administrator application does not have permission to manage the device. | 316 317**Example** 318 319```ts 320import Want from '@ohos.app.ability.Want'; 321let wantTemp: Want = { 322 bundleName: 'com.example.myapplication', 323 abilityName: 'EntryAbility', 324}; 325try { 326 let usbDeviceIds: Array<usbManager.UsbDeviceId> = [{ 327 vendorId: 1, 328 productId: 1 329 }]; 330 usbManager.removeAllowedUsbDevices(wantTemp, usbDeviceIds); 331 console.info(`Succeeded in removing allowed USB devices`); 332} catch (err) { 333 console.error(`Failed to removing allowed USB devices. Code: ${err.code}, message: ${err.message}`); 334} 335``` 336 337## usbManager.getAllowedUsbDevices<sup>11+</sup> 338 339getAllowedUsbDevices(admin: Want): Array\<UsbDeviceId> 340 341Obtains allowed USB devices through the specified device administrator application. 342 343Required permissions: ohos.permission.ENTERPRISE_MANAGE_USB 344 345**System capability**: SystemCapability.Customization.EnterpriseDeviceManager 346 347**System API**: This is a system API. 348 349**Parameters** 350 351| Name| Type | Mandatory| Description | 352| ------ | ----------------------------------- | ---- | -------------- | 353| admin | [Want](js-apis-app-ability-want.md) | Yes | Device administrator application.| 354 355**Return value** 356 357| Type | Description | 358| ------------------------------------ | ------------------------- | 359| Array<[UsbDeviceId](#usbdeviceid11)> | Allowed USB devices obtained.| 360 361**Error codes** 362 363For details about the error codes, see [Enterprise Device Management Error Codes](../errorcodes/errorcode-enterpriseDeviceManager.md). 364 365| ID| Error Message | 366| -------- | ------------------------------------------------------------ | 367| 9200001 | the application is not an administrator of the device. | 368| 9200002 | the administrator application does not have permission to manage the device. | 369 370**Example** 371 372```ts 373import Want from '@ohos.app.ability.Want'; 374let wantTemp: Want = { 375 bundleName: 'com.example.myapplication', 376 abilityName: 'EntryAbility', 377}; 378try { 379 let result: Array<usbManager.UsbDeviceId> = usbManager.getAllowedUsbDevices(wantTemp); 380 console.info(`Succeeded in removing allowed USB devices. Result: ${JSON.stringify(result)}`); 381} catch (err) { 382 console.error(`Failed to removing allowed USB devices. Code: ${err.code}, message: ${err.message}`); 383} 384``` 385 386## usbManager.setUsbStorageDeviceAccessPolicy<sup>11+</sup> 387 388setUsbStorageDeviceAccessPolicy(admin: Want, usbPolicy: UsbPolicy): void 389 390Sets the USB storage device access policy through the specified device administrator application. 391 392Required permissions: ohos.permission.ENTERPRISE_MANAGE_USB 393 394**System capability**: SystemCapability.Customization.EnterpriseDeviceManager 395 396**System API**: This is a system API. 397 398**Parameters** 399 400| Name | Type | Mandatory| Description | 401| --------- | ----------------------------------- | ---- | --------------------- | 402| admin | [Want](js-apis-app-ability-want.md) | Yes | Device administrator application. | 403| usbPolicy | [UsbPolicy](#usbpolicy) | Yes | USB storage device access policy.| 404 405**Error codes** 406 407For details about the error codes, see [Enterprise Device Management Error Codes](../errorcodes/errorcode-enterpriseDeviceManager.md). 408 409| ID| Error Message | 410| -------- | ------------------------------------------------------------ | 411| 9200001 | the application is not an administrator of the device. | 412| 9200002 | the administrator application does not have permission to manage the device. | 413| 9200010 | a conflicting policy has been configured. | 414 415**Example** 416 417```ts 418import Want from '@ohos.app.ability.Want'; 419let wantTemp: Want = { 420 bundleName: 'com.example.myapplication', 421 abilityName: 'EntryAbility', 422}; 423try { 424 let policy: usbManager.UsbPolicy = usbManager.UsbPolicy.DISABLED; 425 usbManager.setUsbStorageDeviceAccessPolicy(wantTemp, policy); 426 console.info(`Succeeded in setting USB storage device access policy`); 427} catch (err) { 428 console.error(`Failed to setting USB storage device access policy. Code: ${err.code}, message: ${err.message}`); 429} 430``` 431 432## usbManager.getUsbStorageDeviceAccessPolicy<sup>11+</sup> 433 434getUsbStorageDeviceAccessPolicy(admin: Want): UsbPolicy 435 436Obtains the USB storage device access policy through the specified device administrator application. 437 438Required permissions: ohos.permission.ENTERPRISE_MANAGE_USB 439 440**System capability**: SystemCapability.Customization.EnterpriseDeviceManager 441 442**System API**: This is a system API. 443 444**Parameters** 445 446| Name| Type | Mandatory| Description | 447| ------ | ----------------------------------- | ---- | -------------- | 448| admin | [Want](js-apis-app-ability-want.md) | Yes | Device administrator application.| 449 450**Return value** 451 452| Type | Description | 453| ----------------------- | --------------------- | 454| [UsbPolicy](#usbpolicy) | USB storage device access policy.| 455 456**Error codes** 457 458For details about the error codes, see [Enterprise Device Management Error Codes](../errorcodes/errorcode-enterpriseDeviceManager.md). 459 460| ID| Error Message | 461| -------- | ------------------------------------------------------------ | 462| 9200001 | the application is not an administrator of the device. | 463| 9200002 | the administrator application does not have permission to manage the device. | 464 465**Example** 466 467```ts 468import Want from '@ohos.app.ability.Want'; 469let wantTemp: Want = { 470 bundleName: 'com.example.myapplication', 471 abilityName: 'EntryAbility', 472}; 473try { 474 let result: usbManager.UsbPolicy = usbManager.getUsbStorageDeviceAccessPolicy(wantTemp); 475 console.info(`Succeeded in getting USB storage device access policy. Result: ${JSON.stringify(result)}`); 476} catch (err) { 477 console.error(`Failed togetting USB storage device access policy. Code: ${err.code}, message: ${err.message}`); 478} 479``` 480