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