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 12. 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 of this module can be called only by a [device administrator application](../../mdm/mdm-kit-guide.md#introduction) that is enabled. 12> 13> The global restriction policy is provided by **restrictions**. To disable USB globally, see [@ohos.enterprise.restrictions (restriction policy)](js-apis-enterprise-restrictions.md). 14 15## Modules to Import 16 17```ts 18import { usbManager } from '@kit.MDMKit'; 19``` 20 21## usbManager.addAllowedUsbDevices 22 23addAllowedUsbDevices(admin: Want, usbDeviceIds: Array\<UsbDeviceId>): void 24 25Adds allowed USB devices. 26 27A policy conflict is reported when this API is called in the following scenarios: 28 291. The USB capability of the device has been disabled using the [setDisallowedPolicy](js-apis-enterprise-restrictions.md#restrictionssetdisallowedpolicy) API. 302. The USB storage device access policy has been disabled using the [setUsbStorageDeviceAccessPolicy](#usbmanagersetusbstoragedeviceaccesspolicy) API. 313. Disallowed USB device types have been added using the [addDisallowedUsbDevices](#usbmanageradddisallowedusbdevices14) API. 32 33**Required permission**: ohos.permission.ENTERPRISE_MANAGE_USB 34 35**System capability**: SystemCapability.Customization.EnterpriseDeviceManager 36 37 38 39**Parameters** 40 41| Name | Type | Mandatory| Description | 42| ------------ | ------------------------------------------------------- | ---- | ------------------------------------------------------------ | 43| admin | [Want](../apis-ability-kit/js-apis-app-ability-want.md) | Yes | EnterpriseAdminExtensionAbility. | 44| usbDeviceIds | Array<[UsbDeviceId](#usbdeviceid)> | Yes | USB device IDs, which can be obtained through [getDevices](../apis-basic-services-kit/js-apis-usbManager.md#usbmanagergetdevices). This array can hold a maximum of 1000 USB device IDs.| 45 46**Error codes** 47 48For details about the error codes, see [Enterprise Device Management Error Codes](errorcode-enterpriseDeviceManager.md) and [Universal Error Codes](../errorcode-universal.md). 49 50| ID| Error Message | 51| -------- | ------------------------------------------------------------ | 52| 9200001 | The application is not an administrator application of the device. | 53| 9200002 | The administrator application does not have permission to manage the device. | 54| 9200010 | A conflict policy has been configured. | 55| 201 | Permission verification failed. The application does not have the permission required to call the API. | 56| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 57 58**Example** 59 60```ts 61import { Want } from '@kit.AbilityKit'; 62let wantTemp: Want = { 63 bundleName: 'com.example.myapplication', 64 abilityName: 'EntryAbility', 65}; 66try { 67 let usbDeviceIds: Array<usbManager.UsbDeviceId> = [{ 68 vendorId: 1, 69 productId: 1 70 }]; 71 usbManager.addAllowedUsbDevices(wantTemp, usbDeviceIds); 72 console.info(`Succeeded in adding allowed USB devices.`); 73} catch (err) { 74 console.error(`Failed to add allowed USB devices. Code: ${err.code}, message: ${err.message}`); 75} 76``` 77 78## usbManager.removeAllowedUsbDevices 79 80removeAllowedUsbDevices(admin: Want, usbDeviceIds: Array\<UsbDeviceId>): void 81 82Removes allowed USB devices. 83 84**Required permission**: ohos.permission.ENTERPRISE_MANAGE_USB 85 86**System capability**: SystemCapability.Customization.EnterpriseDeviceManager 87 88 89 90**Parameters** 91 92| Name | Type | Mandatory| Description | 93| ------------ | ------------------------------------------------------- | ---- | ------------------------------------------------------------ | 94| admin | [Want](../apis-ability-kit/js-apis-app-ability-want.md) | Yes | EnterpriseAdminExtensionAbility. | 95| usbDeviceIds | Array<[UsbDeviceId](#usbdeviceid)> | Yes | USB device IDs, which can be obtained through [getDevices](../apis-basic-services-kit/js-apis-usbManager.md#usbmanagergetdevices).| 96 97**Error codes** 98 99For details about the error codes, see [Enterprise Device Management Error Codes](errorcode-enterpriseDeviceManager.md) and [Universal Error Codes](../errorcode-universal.md). 100 101| ID| Error Message | 102| -------- | ------------------------------------------------------------ | 103| 9200001 | The application is not an administrator application of the device. | 104| 9200002 | The administrator application does not have permission to manage the device. | 105| 201 | Permission verification failed. The application does not have the permission required to call the API. | 106| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 107 108**Example** 109 110```ts 111import { Want } from '@kit.AbilityKit'; 112let wantTemp: Want = { 113 bundleName: 'com.example.myapplication', 114 abilityName: 'EntryAbility', 115}; 116try { 117 let usbDeviceIds: Array<usbManager.UsbDeviceId> = [{ 118 vendorId: 1, 119 productId: 1 120 }]; 121 usbManager.removeAllowedUsbDevices(wantTemp, usbDeviceIds); 122 console.info(`Succeeded in removing allowed USB devices.`); 123} catch (err) { 124 console.error(`Failed to remove allowed USB devices. Code: ${err.code}, message: ${err.message}`); 125} 126``` 127 128## usbManager.getAllowedUsbDevices 129 130getAllowedUsbDevices(admin: Want): Array\<UsbDeviceId> 131 132Obtains allowed USB devices. 133 134**Required permission**: ohos.permission.ENTERPRISE_MANAGE_USB 135 136**System capability**: SystemCapability.Customization.EnterpriseDeviceManager 137 138 139 140**Parameters** 141 142| Name| Type | Mandatory| Description | 143| ------ | ------------------------------------------------------- | ---- | -------------------------------------- | 144| admin | [Want](../apis-ability-kit/js-apis-app-ability-want.md) | Yes | EnterpriseAdminExtensionAbility.| 145 146**Return value** 147 148| Type | Description | 149| ---------------------------------- | ------------------------- | 150| Array<[UsbDeviceId](#usbdeviceid)> | Allowed USB devices obtained.| 151 152**Error codes** 153 154For details about the error codes, see [Enterprise Device Management Error Codes](errorcode-enterpriseDeviceManager.md) and [Universal Error Codes](../errorcode-universal.md). 155 156| ID| Error Message | 157| -------- | ------------------------------------------------------------ | 158| 9200001 | The application is not an administrator application of the device. | 159| 9200002 | The administrator application does not have permission to manage the device. | 160| 201 | Permission verification failed. The application does not have the permission required to call the API. | 161| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 162 163**Example** 164 165```ts 166import { Want } from '@kit.AbilityKit'; 167let wantTemp: Want = { 168 bundleName: 'com.example.myapplication', 169 abilityName: 'EntryAbility', 170}; 171try { 172 let result: Array<usbManager.UsbDeviceId> = usbManager.getAllowedUsbDevices(wantTemp); 173 console.info(`Succeeded in getting allowed USB devices. Result: ${JSON.stringify(result)}`); 174} catch (err) { 175 console.error(`Failed to get allowed USB devices. Code: ${err.code}, message: ${err.message}`); 176} 177``` 178 179## usbManager.setUsbStorageDeviceAccessPolicy 180 181setUsbStorageDeviceAccessPolicy(admin: Want, usbPolicy: UsbPolicy): void 182 183Sets the access policy of the USB storage device. 184 185A policy conflict occurs when you set the USB storage device access policy to read, write, or read-only in the following scenarios: 186 1871. The USB capability of the device has been disabled through [setDisallowedPolicy](js-apis-enterprise-restrictions.md#restrictionssetdisallowedpolicy). 1882. A USB storage device has been disallowed to use through [addDisallowedUsbDevices](#usbmanageradddisallowedusbdevices14). 189 190A policy conflict is reported if the USB storage device access policy is disabled by calling this API in the following scenarios: 191 1921. The USB capability of the device has been disabled through [setDisallowedPolicy](js-apis-enterprise-restrictions.md#restrictionssetdisallowedpolicy). 1932. Allowed USB devices have been added through [addAllowedUsbDevices](#usbmanageraddallowedusbdevices). 194 195You can disable a USB storage device by calling this API or [addDisallowedUsbDevices](#usbmanageradddisallowedusbdevices14). The latter is recommended. 196 197**Required permission**: ohos.permission.ENTERPRISE_MANAGE_USB 198 199**System capability**: SystemCapability.Customization.EnterpriseDeviceManager 200 201 202 203**Parameters** 204 205| Name | Type | Mandatory| Description | 206| --------- | ------------------------------------------------------- | ---- | -------------------------------------- | 207| admin | [Want](../apis-ability-kit/js-apis-app-ability-want.md) | Yes | EnterpriseAdminExtensionAbility.| 208| usbPolicy | [UsbPolicy](#usbpolicy) | Yes | USB storage device access policy. | 209 210**Error codes** 211 212For details about the error codes, see [Enterprise Device Management Error Codes](errorcode-enterpriseDeviceManager.md) and [Universal Error Codes](../errorcode-universal.md). 213 214| ID| Error Message | 215| -------- | ------------------------------------------------------------ | 216| 9200001 | The application is not an administrator application of the device. | 217| 9200002 | The administrator application does not have permission to manage the device. | 218| 9200010 | A conflict policy has been configured. | 219| 201 | Permission verification failed. The application does not have the permission required to call the API. | 220| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 221 222**Example** 223 224```ts 225import { Want } from '@kit.AbilityKit'; 226let wantTemp: Want = { 227 bundleName: 'com.example.myapplication', 228 abilityName: 'EntryAbility', 229}; 230try { 231 let policy: usbManager.UsbPolicy = usbManager.UsbPolicy.DISABLED; 232 usbManager.setUsbStorageDeviceAccessPolicy(wantTemp, policy); 233 console.info(`Succeeded in setting USB storage device access policy.`); 234} catch (err) { 235 console.error(`Failed to setting USB storage device access policy. Code: ${err.code}, message: ${err.message}`); 236} 237``` 238 239## usbManager.getUsbStorageDeviceAccessPolicy 240 241getUsbStorageDeviceAccessPolicy(admin: Want): UsbPolicy 242 243Obtains the access policy of the USB storage device. 244 245**Required permission**: ohos.permission.ENTERPRISE_MANAGE_USB 246 247**System capability**: SystemCapability.Customization.EnterpriseDeviceManager 248 249 250 251**Parameters** 252 253| Name| Type | Mandatory| Description | 254| ------ | ------------------------------------------------------- | ---- | -------------------------------------- | 255| admin | [Want](../apis-ability-kit/js-apis-app-ability-want.md) | Yes | EnterpriseAdminExtensionAbility.| 256 257**Return value** 258 259| Type | Description | 260| ----------------------- | --------------------- | 261| [UsbPolicy](#usbpolicy) | USB storage device access policy obtained.| 262 263**Error codes** 264 265For details about the error codes, see [Enterprise Device Management Error Codes](errorcode-enterpriseDeviceManager.md) and [Universal Error Codes](../errorcode-universal.md). 266 267| ID| Error Message | 268| -------- | ------------------------------------------------------------ | 269| 9200001 | The application is not an administrator application of the device. | 270| 9200002 | The administrator application does not have permission to manage the device. | 271| 201 | Permission verification failed. The application does not have the permission required to call the API. | 272| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 273 274**Example** 275 276```ts 277import { Want } from '@kit.AbilityKit'; 278let wantTemp: Want = { 279 bundleName: 'com.example.myapplication', 280 abilityName: 'EntryAbility', 281}; 282try { 283 let result: usbManager.UsbPolicy = usbManager.getUsbStorageDeviceAccessPolicy(wantTemp); 284 console.info(`Succeeded in getting USB storage device access policy. Result: ${JSON.stringify(result)}`); 285} catch (err) { 286 console.error(`Failed togetting USB storage device access policy. Code: ${err.code}, message: ${err.message}`); 287} 288``` 289 290## usbManager.addDisallowedUsbDevices<sup>14+</sup> 291 292addDisallowedUsbDevices(admin: Want, usbDevices: Array\<UsbDeviceType>): void 293 294Adds disallowed USB device types. 295 296A policy conflict is reported when this API is called in the following scenarios: 297 2981. The USB capability of the device has been disabled through [setDisallowedPolicy](js-apis-enterprise-restrictions.md#restrictionssetdisallowedpolicy). 2992. The available USB devices have been added through [addAllowedUsbDevices](#usbmanageraddallowedusbdevices). 300 301**Required permission**: ohos.permission.ENTERPRISE_MANAGE_USB 302 303**System capability**: SystemCapability.Customization.EnterpriseDeviceManager 304 305 306 307**Parameters** 308 309| Name | Type | Mandatory| Description | 310| ---------- | ------------------------------------------------------- | ---- | ------------------------------------------------------------ | 311| admin | [Want](../apis-ability-kit/js-apis-app-ability-want.md) | Yes | EnterpriseAdminExtensionAbility. | 312| usbDevices | Array<[UsbDeviceType](#usbdevicetype14)> | Yes | Array of the USB devices to be added, which can be obtained through [getDevices](../apis-basic-services-kit/js-apis-usbManager.md#usbmanagergetdevices). This array can hold a maximum of 200 USB device IDs.| 313 314**Error codes** 315 316For details about the error codes, see [Enterprise Device Management Error Codes](errorcode-enterpriseDeviceManager.md) and [Universal Error Codes](../errorcode-universal.md). 317 318| ID| Error Message | 319| -------- | ------------------------------------------------------------ | 320| 9200001 | The application is not an administrator application of the device. | 321| 9200002 | The administrator application does not have permission to manage the device. | 322| 9200010 | A conflict policy has been configured. | 323| 201 | Permission verification failed. The application does not have the permission required to call the API. | 324| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 325 326**Example** 327 328```ts 329import { Want } from '@kit.AbilityKit'; 330let wantTemp: Want = { 331 bundleName: 'com.example.myapplication', 332 abilityName: 'EntryAbility', 333}; 334try { 335 let usbDevices: Array<usbManager.UsbDeviceType> = [{ 336 baseClass: 8, 337 subClass: 0, 338 protocol: 0, 339 descriptor: usbManager.Descriptor.INTERFACE 340 }]; 341 usbManager.addDisallowedUsbDevices(wantTemp, usbDevices); 342 console.info(`Succeeded in adding disallowed USB devices.`); 343} catch (err) { 344 console.error(`Failed to add disallowed USB devices. Code: ${err.code}, message: ${err.message}`); 345} 346``` 347 348## usbManager.removeDisallowedUsbDevices<sup>14+</sup> 349 350removeDisallowedUsbDevices(admin: Want, usbDevices: Array\<UsbDeviceType>): void 351 352Removes the disallowed USB device types. 353 354**Required permission**: ohos.permission.ENTERPRISE_MANAGE_USB 355 356**System capability**: SystemCapability.Customization.EnterpriseDeviceManager 357 358 359 360**Parameters** 361 362| Name | Type | Mandatory| Description | 363| ---------- | ------------------------------------------------------- | ---- | ------------------------------------------------------------ | 364| admin | [Want](../apis-ability-kit/js-apis-app-ability-want.md) | Yes | EnterpriseAdminExtensionAbility. | 365| usbDevices | Array<[UsbDeviceType](#usbdevicetype14)> | Yes | Array of the USB devices to be removed, which can be obtained through [getDevices](../apis-basic-services-kit/js-apis-usbManager.md#usbmanagergetdevices).| 366 367**Error codes** 368 369For details about the error codes, see [Enterprise Device Management Error Codes](errorcode-enterpriseDeviceManager.md) and [Universal Error Codes](../errorcode-universal.md). 370 371| ID| Error Message | 372| -------- | ------------------------------------------------------------ | 373| 9200001 | The application is not an administrator application of the device. | 374| 9200002 | The administrator application does not have permission to manage the device. | 375| 201 | Permission verification failed. The application does not have the permission required to call the API. | 376| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 377 378**Example** 379 380```ts 381import { Want } from '@kit.AbilityKit'; 382let wantTemp: Want = { 383 bundleName: 'com.example.myapplication', 384 abilityName: 'EntryAbility', 385}; 386try { 387 let usbDevices: Array<usbManager.UsbDeviceType> = [{ 388 baseClass: 8, 389 subClass: 0, 390 protocol: 0, 391 descriptor: usbManager.Descriptor.INTERFACE 392 }]; 393 usbManager.removeDisallowedUsbDevices(wantTemp, usbDevices); 394 console.info(`Succeeded in removing disallowed USB devices.`); 395} catch (err) { 396 console.error(`Failed to remove disallowed USB devices. Code: ${err.code}, message: ${err.message}`); 397} 398``` 399 400## usbManager.getDisallowedUsbDevices<sup>14+</sup> 401 402getDisallowedUsbDevices(admin: Want): Array\<UsbDeviceType> 403 404Obtains the disallowed USB device types. 405 406**Required permission**: ohos.permission.ENTERPRISE_MANAGE_USB 407 408**System capability**: SystemCapability.Customization.EnterpriseDeviceManager 409 410 411 412**Parameters** 413 414| Name| Type | Mandatory| Description | 415| ------ | ------------------------------------------------------- | ---- | -------------------------------------- | 416| admin | [Want](../apis-ability-kit/js-apis-app-ability-want.md) | Yes | EnterpriseAdminExtensionAbility.| 417 418**Return value** 419 420| Type | Description | 421| ---------------------------------------- | ----------------------- | 422| Array<[UsbDeviceType](#usbdevicetype14)> | Disallowed USB device types obtained.| 423 424**Error codes** 425 426For details about the error codes, see [Enterprise Device Management Error Codes](errorcode-enterpriseDeviceManager.md) and [Universal Error Codes](../errorcode-universal.md). 427 428| ID| Error Message | 429| -------- | ------------------------------------------------------------ | 430| 9200001 | The application is not an administrator application of the device. | 431| 9200002 | The administrator application does not have permission to manage the device. | 432| 201 | Permission verification failed. The application does not have the permission required to call the API. | 433| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. | 434 435**Example** 436 437```ts 438import { Want } from '@kit.AbilityKit'; 439let wantTemp: Want = { 440 bundleName: 'com.example.myapplication', 441 abilityName: 'EntryAbility', 442}; 443try { 444 let result: Array<usbManager.UsbDeviceType> = usbManager.getDisallowedUsbDevices(wantTemp); 445 console.info(`Succeeded in getting disallowed USB devices. Result: ${JSON.stringify(result)}`); 446} catch (err) { 447 console.error(`Failed to get disallowed USB devices. Code: ${err.code}, message: ${err.message}`); 448} 449``` 450 451## UsbDeviceId 452 453Represents the USB device identity information. 454 455**System capability**: SystemCapability.Customization.EnterpriseDeviceManager 456 457| Name | Type | Mandatory| Description | 458| --------- | ------ | ---- | -------- | 459| vendorId | number | Yes | Vendor ID.| 460| productId | number | Yes | Product ID.| 461 462## UsbDeviceType<sup>14+</sup> 463 464Represents the USB device type information. For details about the ID, see [defined-class-codes](https://www.usb.org/defined-class-codes). 465 466**System capability**: SystemCapability.Customization.EnterpriseDeviceManager 467 468| Name | Type | Mandatory| Description | 469| ---------- | --------------------------- | ---- | ------------------------------------------------------------ | 470| baseClass | number | Yes | Type ID, which can be obtained through [getDevices](../apis-basic-services-kit/js-apis-usbManager.md#usbmanagergetdevices). If the value of descriptor is **DEVICE**, obtain the **USBDevice.clazz** field. If the value of descriptor is **INTERFACE**, obtain the **USBDevice.configs.interfaces.clazz** field.| 471| subClass | number | Yes | Subtype ID, which can be obtained through [getDevices](../apis-basic-services-kit/js-apis-usbManager.md#usbmanagergetdevices). If the value of descriptor is **DEVICE**, obtain the **USBDevice.subClass** field. If the value of descriptor is **INTERFACE**, obtain the **USBDevice.configs.interfaces.subClass** field.| 472| protocol | number | Yes | Protocol ID, which can be obtained through [getDevices](../apis-basic-services-kit/js-apis-usbManager.md#usbmanagergetdevices). If the value of descriptor is **DEVICE**, obtain the **USBDevice.protocol** field. If the value of descriptor is **INTERFACE**, obtain the **USBDevice.configs.interfaces.protocol** field.| 473| descriptor | [Descriptor](#descriptor14) | Yes | USB descriptor. Obtain the value of Descriptor Usage corresponding to **baseClass** as the input parameter based on [defined-class-codes](https://www.usb.org/defined-class-codes). If the value of Descriptor Usage is set to **Both**, **DEVICE** is input for disallowed devices, and **INTERFACE** is input for disallowed interfaces.| 474 475## UsbPolicy 476 477Enumerates the USB access policies. 478 479**System capability**: SystemCapability.Customization.EnterpriseDeviceManager 480 481| Name | Value | Description | 482| ---------- | ---- | ---------- | 483| READ_WRITE | 0 | Read and write.| 484| READ_ONLY | 1 | Read only. | 485| DISABLED | 2 | Disabled. | 486 487## Descriptor<sup>14+</sup> 488 489Enumerates USB descriptors. 490 491**System capability**: SystemCapability.Customization.EnterpriseDeviceManager 492 493| Name | Value | Description | 494| --------- | ---- | ------------ | 495| INTERFACE | 0 | Interface descriptor.| 496| DEVICE | 1 | Device descriptor.| 497