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