1# @ohos.enterprise.usbManager（USB管理）
2
3本模块提供USB管理能力。
4
5> **说明**：
6>
7> 本模块首批接口从API version 12开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。
8>
9> 本模块接口仅可在Stage模型下使用。
10>
11> 本模块接口仅对[设备管理应用](../../mdm/mdm-kit-guide.md#功能介绍)开放，需将设备管理应用激活后调用，实现相应功能。
12>
13> 全局通用限制类策略由restrictions统一提供，若要全局禁用USB，请参考[@ohos.enterprise.restrictions（限制类策略）](js-apis-enterprise-restrictions.md)。
14
15## 导入模块
16
17```ts
18import { usbManager } from '@kit.MDMKit';
19```
20
21## usbManager.addAllowedUsbDevices
22
23addAllowedUsbDevices(admin: Want, usbDeviceIds: Array\<UsbDeviceId>): void
24
25指定设备管理应用添加USB设备可用白名单。
26
27**需要权限：** ohos.permission.ENTERPRISE_MANAGE_USB
28
29**系统能力：** SystemCapability.Customization.EnterpriseDeviceManager
30
31
32
33**参数：**
34
35| 参数名       | 类型                                                    | 必填 | 说明                                        |
36| ------------ | ------------------------------------------------------- | ---- | ------------------------------------------- |
37| admin        | [Want](../apis-ability-kit/js-apis-app-ability-want.md) | 是   | 设备管理应用。                              |
38| usbDeviceIds | Array<[UsbDeviceId](#usbdeviceid)>                      | 是   | USB设备ID数组。添加后的数组长度上限为1000。 |
39
40**错误码**：
41
42以下错误码的详细介绍请参见[企业设备管理错误码](errorcode-enterpriseDeviceManager.md)和[通用错误码](../errorcode-universal.md)。
43
44| 错误码ID | 错误信息                                                     |
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**示例：**
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
76指定设备管理应用移除USB设备可用白名单。
77
78**需要权限：** ohos.permission.ENTERPRISE_MANAGE_USB
79
80**系统能力：** SystemCapability.Customization.EnterpriseDeviceManager
81
82
83
84**参数：**
85
86| 参数名       | 类型                                                    | 必填 | 说明            |
87| ------------ | ------------------------------------------------------- | ---- | --------------- |
88| admin        | [Want](../apis-ability-kit/js-apis-app-ability-want.md) | 是   | 设备管理应用。  |
89| usbDeviceIds | Array<[UsbDeviceId](#usbdeviceid)>                      | 是   | USB设备ID数组。 |
90
91**错误码**：
92
93以下错误码的详细介绍请参见[企业设备管理错误码](errorcode-enterpriseDeviceManager.md)和[通用错误码](../errorcode-universal.md)。
94
95| 错误码ID | 错误信息                                                     |
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**示例：**
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
126指定设备管理应用获取USB设备可用白名单。
127
128**需要权限：** ohos.permission.ENTERPRISE_MANAGE_USB
129
130**系统能力：** SystemCapability.Customization.EnterpriseDeviceManager
131
132
133
134**参数：**
135
136| 参数名 | 类型                                                    | 必填 | 说明           |
137| ------ | ------------------------------------------------------- | ---- | -------------- |
138| admin  | [Want](../apis-ability-kit/js-apis-app-ability-want.md) | 是   | 设备管理应用。 |
139
140**返回值：**
141
142| 类型                               | 说明                      |
143| ---------------------------------- | ------------------------- |
144| Array<[UsbDeviceId](#usbdeviceid)> | 可用USB白名单设备ID数组。 |
145
146**错误码**：
147
148以下错误码的详细介绍请参见[企业设备管理错误码](errorcode-enterpriseDeviceManager.md)和[通用错误码](../errorcode-universal.md)。
149
150| 错误码ID | 错误信息                                                     |
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**示例：**
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
177指定设备管理应用设置USB存储设备访问策略。
178
179**需要权限：** ohos.permission.ENTERPRISE_MANAGE_USB
180
181**系统能力：** SystemCapability.Customization.EnterpriseDeviceManager
182
183
184
185**参数：**
186
187| 参数名    | 类型                                                    | 必填 | 说明                  |
188| --------- | ------------------------------------------------------- | ---- | --------------------- |
189| admin     | [Want](../apis-ability-kit/js-apis-app-ability-want.md) | 是   | 设备管理应用。        |
190| usbPolicy | [UsbPolicy](#usbpolicy)                                 | 是   | USB存储设备访问策略。 |
191
192**错误码**：
193
194以下错误码的详细介绍请参见[企业设备管理错误码](errorcode-enterpriseDeviceManager.md)和[通用错误码](../errorcode-universal.md)。
195
196| 错误码ID | 错误信息                                                     |
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**示例：**
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
225指定设备管理应用获取USB存储设备访问策略。
226
227**需要权限：** ohos.permission.ENTERPRISE_MANAGE_USB
228
229**系统能力：** SystemCapability.Customization.EnterpriseDeviceManager
230
231
232
233**参数：**
234
235| 参数名 | 类型                                                    | 必填 | 说明           |
236| ------ | ------------------------------------------------------- | ---- | -------------- |
237| admin  | [Want](../apis-ability-kit/js-apis-app-ability-want.md) | 是   | 设备管理应用。 |
238
239**返回值：**
240
241| 类型                    | 说明                  |
242| ----------------------- | --------------------- |
243| [UsbPolicy](#usbpolicy) | USB存储设备访问策略。 |
244
245**错误码**：
246
247以下错误码的详细介绍请参见[企业设备管理错误码](errorcode-enterpriseDeviceManager.md)和[通用错误码](../errorcode-universal.md)。
248
249| 错误码ID | 错误信息                                                     |
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**示例：**
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
276指定设备管理应用添加禁止使用的USB设备类型。
277
278**需要权限：** ohos.permission.ENTERPRISE_MANAGE_USB
279
280**系统能力：** SystemCapability.Customization.EnterpriseDeviceManager
281
282
283
284**参数：**
285
286| 参数名     | 类型                                                    | 必填 | 说明                                                   |
287| ---------- | ------------------------------------------------------- | ---- | ------------------------------------------------------ |
288| admin      | [Want](../apis-ability-kit/js-apis-app-ability-want.md) | 是   | 设备管理应用。                                         |
289| usbDevices | Array<[UsbDeviceType](#usbdevicetype14)>                | 是   | 要添加的USB设备类型的数组。添加后的数组长度上限为200。 |
290
291**错误码**：
292
293以下错误码的详细介绍请参见[企业设备管理错误码](errorcode-enterpriseDeviceManager.md)和[通用错误码](../errorcode-universal.md)。
294
295| 错误码ID | 错误信息                                                     |
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**示例：**
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
329指定设备管理应用移除禁止使用的USB设备类型。
330
331**需要权限：** ohos.permission.ENTERPRISE_MANAGE_USB
332
333**系统能力：** SystemCapability.Customization.EnterpriseDeviceManager
334
335
336
337**参数：**
338
339| 参数名     | 类型                                                    | 必填 | 说明                        |
340| ---------- | ------------------------------------------------------- | ---- | --------------------------- |
341| admin      | [Want](../apis-ability-kit/js-apis-app-ability-want.md) | 是   | 设备管理应用。              |
342| usbDevices | Array<[UsbDeviceType](#usbdevicetype14)>                | 是   | 要移除的USB设备类型的数组。 |
343
344**错误码**：
345
346以下错误码的详细介绍请参见[企业设备管理错误码](errorcode-enterpriseDeviceManager.md)和[通用错误码](../errorcode-universal.md)。
347
348| 错误码ID | 错误信息                                                     |
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**示例：**
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
381指定设备管理应用获取禁止使用的USB设备类型。
382
383**需要权限：** ohos.permission.ENTERPRISE_MANAGE_USB
384
385**系统能力：** SystemCapability.Customization.EnterpriseDeviceManager
386
387
388
389**参数：**
390
391| 参数名 | 类型                                                    | 必填 | 说明           |
392| ------ | ------------------------------------------------------- | ---- | -------------- |
393| admin  | [Want](../apis-ability-kit/js-apis-app-ability-want.md) | 是   | 设备管理应用。 |
394
395**返回值：**
396
397| 类型                                     | 说明                    |
398| ---------------------------------------- | ----------------------- |
399| Array<[UsbDeviceType](#usbdevicetype14)> | 禁止使用的USB设备类型。 |
400
401**错误码**：
402
403以下错误码的详细介绍请参见[企业设备管理错误码](errorcode-enterpriseDeviceManager.md)和[通用错误码](../errorcode-universal.md)。
404
405| 错误码ID | 错误信息                                                     |
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**示例：**
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
430USB设备ID信息。
431
432**系统能力：** SystemCapability.Customization.EnterpriseDeviceManager
433
434| 名称      | 类型   | 必填 | 说明     |
435| --------- | ------ | ---- | -------- |
436| vendorId  | number | 是   | 厂商ID。 |
437| productId | number | 是   | 产品ID。 |
438
439## UsbDeviceType<sup>14+</sup>
440
441USB设备类型信息。其中具体编号可查询：https://www.usb.org/defined-class-codes
442
443**系统能力：** SystemCapability.Customization.EnterpriseDeviceManager
444
445| 名称       | 类型                        | 必填 | 说明         |
446| ---------- | --------------------------- | ---- | ------------ |
447| baseClass  | number                      | 是   | 类型编号。   |
448| subClass   | number                      | 是   | 子类型编号。 |
449| protocol   | number                      | 是   | 协议编号。   |
450| descriptor | [Descriptor](#descriptor14) | 是   | USB描述符。  |
451
452## UsbPolicy
453
454USB读写策略的枚举。
455
456**系统能力：** SystemCapability.Customization.EnterpriseDeviceManager
457
458| 名称       | 值   | 说明       |
459| ---------- | ---- | ---------- |
460| READ_WRITE | 0    | 可读可写。 |
461| READ_ONLY  | 1    | 只读。     |
462| DISABLED   | 2    | 禁用。     |
463
464## Descriptor<sup>14+</sup>
465
466USB描述符的枚举。
467
468**系统能力：** SystemCapability.Customization.EnterpriseDeviceManager
469
470| 名称      | 值   | 说明         |
471| --------- | ---- | ------------ |
472| INTERFACE | 0    | 接口描述符。 |
473| DEVICE    | 1    | 设备描述符。 |
474