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