1# @ohos.usb (USB管理)(已停止维护)
2
3本模块主要提供管理USB设备的相关功能，包括查询USB设备列表、批量数据传输、控制命令传输、权限控制等。
4
5>  **说明：**
6>
7> 本模块首批接口从API version 8开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。
8>
9> 从API version 9开始，该接口不再维护，推荐使用新接口[@ohos.usbManager](js-apis-usbManager.md)。
10
11## 导入模块
12
13```js
14import usb from "@ohos.usb";
15```
16
17## usb.getDevices
18
19getDevices(): Array<Readonly<USBDevice>>
20
21获取USB设备列表。
22
23**系统能力：**  SystemCapability.USB.USBManager
24
25**返回值：**
26
27| 类型                                                   | 说明      |
28| ---------------------------------------------------- | ------- |
29| Array<Readonly<[USBDevice](#usbdevice)>> | 设备信息列表。 |
30
31**示例：**
32
33```js
34let devicesList = usb.getDevices();
35console.log(`devicesList = ${devicesList}`);
36//devicesList  返回的数据结构
37//此处提供一个简单的示例，如下
38/*[
39  {
40    name: "1-1",
41    serial: "",
42    manufacturerName: "",
43    productName: "",
44    version: "",
45    vendorId: 7531,
46    productId: 2,
47    clazz: 9,
48    subClass: 0,
49    protocol: 1,
50    devAddress: 1,
51    busNum: 1,
52    configs: [
53      {
54        id: 1,
55        attributes: 224,
56        isRemoteWakeup: true,
57        isSelfPowered: true,
58        maxPower: 0,
59        name: "1-1",
60        interfaces: [
61          {
62            id: 0,
63            protocol: 0,
64            clazz: 9,
65            subClass: 0,
66            alternateSetting: 0,
67            name: "1-1",
68            endpoints: [
69              {
70                address: 129,
71                attributes: 3,
72                interval: 12,
73                maxPacketSize: 4,
74                direction: 128,
75                number: 1,
76                type: 3,
77                interfaceId: 0,
78              },
79            ],
80          },
81        ],
82      },
83    ],
84  },
85]*/
86```
87
88## usb.connectDevice
89
90connectDevice(device: USBDevice): Readonly<USBDevicePipe>
91
92打开USB设备。
93
94需要调用[usb.getDevices](#usbgetdevices)获取设备信息以及device，再调用[usb.requestRight](#usbrequestright)获取设备请求权限。
95
96**系统能力：**  SystemCapability.USB.USBManager
97
98**参数：**
99
100| 参数名 | 类型 | 必填 | 说明 |
101| -------- | -------- | -------- | -------- |
102| device | [USBDevice](#usbdevice) | 是 | USB设备信息。 |
103
104**返回值：**
105
106| 类型 | 说明 |
107| -------- | -------- |
108| Readonly<[USBDevicePipe](#usbdevicepipe)> | 指定的传输通道对象。 |
109
110**示例：**
111
112```js
113let devicepipe= usb.connectDevice(device);
114console.log(`devicepipe = ${devicepipe}`);
115```
116
117## usb.hasRight
118
119hasRight(deviceName: string): boolean
120
121判断是否有权访问该设备。
122
123**系统能力：**  SystemCapability.USB.USBManager
124
125**参数：**
126
127| 参数名 | 类型 | 必填 | 说明 |
128| -------- | -------- | -------- | -------- |
129| deviceName | string | 是 | 设备名称。 |
130
131**返回值：**
132
133| 类型 | 说明 |
134| -------- | -------- |
135| boolean | true表示有访问设备的权限，false表示没有访问设备的权限。 |
136
137**示例：**
138
139```js
140let devicesName= "1-1";
141let bool = usb.hasRight(devicesName);
142console.log(`hasRight = ${bool}`);
143```
144
145## usb.requestRight
146
147requestRight(deviceName: string): Promise<boolean>
148
149请求软件包的临时权限以访问设备。使用Promise异步回调。系统应用默认拥有访问设备权限，无需调用此接口申请。
150
151**系统能力：**  SystemCapability.USB.USBManager
152
153**参数：**
154
155| 参数名 | 类型 | 必填 | 说明 |
156| -------- | -------- | -------- | -------- |
157| deviceName | string | 是 | 设备名称。 |
158
159**返回值：**
160
161| 类型 | 说明 |
162| -------- | -------- |
163| Promise<boolean> | Promise对象，返回临时权限的申请结果。返回true表示临时权限申请成功；返回false则表示临时权限申请失败。 |
164
165**示例：**
166
167```js
168let devicesName= "1-1";
169usb.requestRight(devicesName).then((ret) => {
170  console.log(`requestRight = ${ret}`);
171});
172```
173
174## usb.claimInterface
175
176claimInterface(pipe: USBDevicePipe, iface: USBInterface, force ?: boolean): number
177
178注册通信接口。
179
180需要调用[usb.getDevices](#usbgetdevices)获取设备信息以及interfaces；调用[usb.requestRight](#usbrequestright)获取设备请求权限；调用[usb.connectDevice](#usbconnectdevice)接口得到devicepipe作为参数。
181
182**系统能力：**  SystemCapability.USB.USBManager
183
184**参数：**
185
186| 参数名 | 类型 | 必填 | 说明 |
187| -------- | -------- | -------- | -------- |
188| pipe | [USBDevicePipe](#usbdevicepipe) | 是 | 用于确定总线号和设备地址。 |
189| iface | [USBInterface](#usbinterface) | 是 | 用于确定需要获取接口的索引。 |
190| force | boolean | 否 | 可选参数，是否强制获取。默认值为false ，表示不强制获取。 |
191
192**返回值：**
193
194| 类型 | 说明 |
195| -------- | -------- |
196| number | 注册通信接口成功返回0；注册通信接口失败返回其他错误码。 |
197
198**示例：**
199
200```js
201let ret = usb.claimInterface(devicepipe, interfaces);
202console.log(`claimInterface = ${ret}`);
203```
204
205## usb.releaseInterface
206
207releaseInterface(pipe: USBDevicePipe, iface: USBInterface): number
208
209释放注册过的通信接口。
210
211需要调用[usb.claimInterface](#usbclaiminterface)先获取接口，才能使用此方法释放接口。
212
213**系统能力：**  SystemCapability.USB.USBManager
214
215**参数：**
216
217| 参数名 | 类型 | 必填 | 说明 |
218| -------- | -------- | -------- | -------- |
219| pipe | [USBDevicePipe](#usbdevicepipe) | 是 | 用于确定总线号和设备地址。 |
220| iface | [USBInterface](#usbinterface) | 是 | 用于确定需要释放接口的索引。 |
221
222**返回值：**
223
224| 类型 | 说明 |
225| -------- | -------- |
226| number | 释放接口成功返回0；释放接口失败返回其他错误码。 |
227
228**示例：**
229
230```js
231let ret = usb.releaseInterface(devicepipe, interfaces);
232console.log(`releaseInterface = ${ret}`);
233```
234
235## usb.setConfiguration
236
237setConfiguration(pipe: USBDevicePipe, config: USBConfig): number
238
239设置设备配置。
240
241需要调用[usb.getDevices](#usbgetdevices)获取设备信息以及config；调用[usb.requestRight](#usbrequestright)获取设备请求权限；调用[usb.connectDevice](#usbconnectdevice)得到devicepipe作为参数。
242
243**系统能力：**  SystemCapability.USB.USBManager
244
245**参数：**
246
247| 参数名 | 类型 | 必填 | 说明 |
248| -------- | -------- | -------- | -------- |
249| pipe | [USBDevicePipe](#usbdevicepipe) | 是 | 用于确定总线号和设备地址。 |
250| config | [USBConfig](#usbconfig) | 是 | 用于确定需要设置的配置。 |
251
252**返回值：**
253
254| 类型 | 说明 |
255| -------- | -------- |
256| number | 设置设备配置成功返回0；设置设备配置失败返回其他错误码。 |
257
258**示例：**
259
260```js
261let ret = usb.setConfiguration(devicepipe, config);
262console.log(`setConfiguration = ${ret}`);
263```
264
265## usb.setInterface
266
267setInterface(pipe: USBDevicePipe, iface: USBInterface): number
268
269设置设备接口。
270
271需要调用[usb.getDevices](#usbgetdevices)获取设备列表以及interfaces；调用[usb.requestRight](#usbrequestright)获取设备请求权限；调用[usb.connectDevice](#usbconnectdevice)得到devicepipe作为参数；调用[usb.claimInterface](#usbclaiminterface)注册通信接口。
272
273**系统能力：**  SystemCapability.USB.USBManager
274
275**参数：**
276
277| 参数名   | 类型                              | 必填  | 说明            |
278| ----- | ------------------------------- | --- | ------------- |
279| pipe  | [USBDevicePipe](#usbdevicepipe) | 是   | 用于确定总线号和设备地址。 |
280| iface | [USBInterface](#usbinterface)   | 是   | 用于确定需要设置的接口。  |
281
282**返回值：**
283
284| 类型 | 说明 |
285| -------- | -------- |
286| number | 设置设备接口成功返回0；设置设备接口失败返回其他错误码。 |
287
288**示例：**
289
290```js
291let ret = usb.setInterface(devicepipe, interfaces);
292console.log(`setInterface = ${ret}`);
293```
294
295## usb.getRawDescriptor
296
297getRawDescriptor(pipe: USBDevicePipe): Uint8Array
298
299获取原始的USB描述符。
300
301需要调用[usb.getDevices](#usbgetdevices)获取设备列表；调用[usb.requestRight](#usbrequestright)获取设备请求权限；调用[usb.connectDevice](#usbconnectdevice)接口得到devicepipe作为参数。
302
303**系统能力：**  SystemCapability.USB.USBManager
304
305**参数：**
306
307| 参数名 | 类型 | 必填 | 说明 |
308| -------- | -------- | -------- | -------- |
309| pipe | [USBDevicePipe](#usbdevicepipe) | 是 | 用于确定总线号和设备地址。 |
310
311**返回值：**
312
313| 类型 | 说明 |
314| -------- | -------- |
315| Uint8Array | 返回获取的原始数据；失败返回undefined。 |
316
317**示例：**
318
319```js
320let ret = usb.getRawDescriptor(devicepipe);
321```
322
323## usb.getFileDescriptor
324
325getFileDescriptor(pipe: USBDevicePipe): number
326
327获取文件描述符。
328
329需要调用[usb.getDevices](#usbgetdevices)获取设备列表；调用[usb.requestRight](#usbrequestright)获取设备请求权限；调用[usb.connectDevice](#usbconnectdevice)接口得到devicepipe作为参数。
330
331**系统能力：**  SystemCapability.USB.USBManager
332
333**参数：**
334
335| 参数名 | 类型 | 必填 | 说明 |
336| -------- | -------- | -------- | -------- |
337| pipe | [USBDevicePipe](#usbdevicepipe) | 是 | 用于确定总线号和设备地址。 |
338
339**返回值：**
340
341| 类型     | 说明                   |
342| ------ | -------------------- |
343| number | 返回设备对应的文件描述符；失败返回-1。 |
344
345**示例：**
346
347```js
348let ret = usb.getFileDescriptor(devicepipe);
349```
350
351## usb.controlTransfer
352
353controlTransfer(pipe: USBDevicePipe, controlparam: USBControlParams, timeout ?: number): Promise<number>
354
355控制传输。
356
357需要调用[usb.getDevices](#usbgetdevices)获取设备列表；调用[usb.requestRight](#usbrequestright)获取设备请求权限；调用[usb.connectDevice](#usbconnectdevice)接口得到devicepipe作为参数。
358
359**系统能力：**  SystemCapability.USB.USBManager
360
361**参数：**
362
363| 参数名 | 类型 | 必填 | 说明 |
364| -------- | -------- | -------- | -------- |
365| pipe | [USBDevicePipe](#usbdevicepipe) | 是 | 用于确定设备。 |
366| controlparam | [USBControlParams](#usbcontrolparams) | 是 | 控制传输参数。 |
367| timeout | number | 否 | 超时时间（单位：ms），可选参数，默认为0不超时。 |
368
369**返回值：**
370
371| 类型 | 说明 |
372| -------- | -------- |
373| Promise<number> | Promise对象，获取传输或接收到的数据块大小。失败返回-1。 |
374
375**示例：**
376
377```js
378let param = {
379  request: 0,
380  reqType: 0,
381  target:0,
382  value: 0,
383  index: 0,
384  data: null
385};
386usb.controlTransfer(devicepipe, param).then((ret) => {
387 console.log(`controlTransfer = ${ret}`);
388})
389```
390
391## usb.bulkTransfer
392
393bulkTransfer(pipe: USBDevicePipe, endpoint: USBEndpoint, buffer: Uint8Array, timeout ?: number): Promise<number>
394
395批量传输。
396
397需要调用[usb.getDevices](#usbgetdevices)获取设备信息列表以及endpoint；再调用[usb.requestRight](#usbrequestright)获取设备请求权限；然后调用[usb.connectDevice](#usbconnectdevice)接口得到返回数据devicepipe之后，再次获取接口[usb.claimInterface](#usbclaiminterface)；再调用usb.bulkTransfer接口。
398
399**系统能力：**  SystemCapability.USB.USBManager
400
401**参数：**
402
403| 参数名 | 类型 | 必填 | 说明 |
404| -------- | -------- | -------- | -------- |
405| pipe | [USBDevicePipe](#usbdevicepipe) | 是 | 用于确定设备。 |
406| endpoint | [USBEndpoint](#usbendpoint) | 是 | 用于确定传输的端口。 |
407| buffer | Uint8Array | 是 | 用于写入或读取的缓冲区。 |
408| timeout | number | 否 | 超时时间（单位：ms），可选参数，默认为0不超时。|
409
410**返回值：**
411
412| 类型 | 说明 |
413| -------- | -------- |
414| Promise<number> | Promise对象，获取传输或接收到的数据块大小。失败返回-1。 |
415
416**示例：**
417
418```js
419//usb.getDevices 接口返回数据集合，取其中一个设备对象，并获取权限 。
420//把获取到的设备对象作为参数传入usb.connectDevice;当usb.connectDevice接口成功返回之后；
421//才可以调用第三个接口usb.claimInterface.当usb.claimInterface 调用成功以后,再调用该接口。
422usb.bulkTransfer(devicepipe, endpoint, buffer).then((ret) => {
423 console.log(`bulkTransfer = ${ret}`);
424});
425```
426
427## usb.closePipe
428
429closePipe(pipe: USBDevicePipe): number
430
431关闭设备消息控制通道。
432
433需要调用[usb.getDevices](#usbgetdevices)获取设备列表；调用[usb.requestRight](#usbrequestright)获取设备请求权限；调用[usb.connectDevice](#usbconnectdevice)得到devicepipe作为参数。
434
435**系统能力：**  SystemCapability.USB.USBManager
436
437**参数：**
438
439| 参数名 | 类型 | 必填 | 说明 |
440| -------- | -------- | -------- | -------- |
441| pipe | [USBDevicePipe](#usbdevicepipe) | 是 | 用于确定USB设备消息控制通道。 |
442
443**返回值：**
444
445| 类型 | 说明 |
446| -------- | -------- |
447| number | 关闭设备消息控制通道成功返回0；关闭设备消息控制通道失败返回其他错误码。 |
448
449**示例：**
450
451```js
452let ret = usb.closePipe(devicepipe);
453console.log(`closePipe = ${ret}`);
454```
455
456## USBEndpoint
457
458通过USB发送和接收数据的端口。通过[USBInterface](#usbinterface)获取。
459
460**系统能力：** SystemCapability.USB.USBManager
461
462| 名称            | 类型                                        |   必填      | 说明            |
463| ------------- | ------------------------------------------- | ------------- |------------ |
464| address       | number                                      | 是   |端点地址。         |
465| attributes    | number                                      | 是   |端点属性。         |
466| interval      | number                                      | 是   |端点间隔。         |
467| maxPacketSize | number                                      | 是   |端点最大数据包大小。    |
468| direction     | [USBRequestDirection](#usbrequestdirection) | 是   |端点的方向。        |
469| number        | number                                      | 是   |端点号。          |
470| type          | number                                      | 是   |端点类型。         |
471| interfaceId   | number                                      | 是   |端点所属的接口的唯一标识。 |
472
473## USBInterface
474
475一个[USBConfig](#usbconfig)中可以含有多个USBInterface，每个USBInterface提供一个功能。
476
477**系统能力：** SystemCapability.USB.USBManager
478
479| 名称               | 类型                                     |  必填      |说明                    |
480| ---------------- | ---------------------------------------- | ------------- |--------------------- |
481| id               | number                                   | 是   |接口的唯一标识。              |
482| protocol         | number                                   | 是   |接口的协议。                |
483| clazz            | number                                   | 是   |设备类型。                 |
484| subClass         | number                                   | 是   |设备子类。                 |
485| alternateSetting | number                                   | 是   |在同一个接口中的多个描述符中进行切换设置。 |
486| name             | string                                   | 是   |接口名称。                 |
487| endpoints        | Array<[USBEndpoint](#usbendpoint)> | 是   |当前接口所包含的端点。           |
488
489## USBConfig
490
491USB配置，一个[USBDevice](#usbdevice)中可以含有多个配置。
492
493**系统能力：** SystemCapability.USB.USBManager
494
495| 名称             | 类型                                             | 必填   |说明              |
496| -------------- | ------------------------------------------------ | --------------- |----------- |
497| id             | number                                           | 是   |配置的唯一标识。        |
498| attributes     | number                                           | 是   |配置的属性。          |
499| maxPower       | number                                           | 是   |最大功耗，以毫安为单位。    |
500| name           | string                                           | 是   |配置的名称，可以为空。     |
501| isRemoteWakeup | boolean                                          | 是   |检查当前配置是否支持远程唤醒。 |
502| isSelfPowered  | boolean                                          | 是   |检查当前配置是否支持独立电源。 |
503| interfaces     | Array <[USBInterface](#usbinterface)> | 是   |配置支持的接口属性。      |
504
505## USBDevice
506
507USB设备信息。
508
509**系统能力：** SystemCapability.USB.USBManager
510
511| 名称               | 类型                                 | 必填   |说明         |
512| ---------------- | ------------------------------------ | ---------- |---------- |
513| busNum           | number                               | 是   |总线地址。      |
514| devAddress       | number                               | 是   |设备地址。      |
515| serial           | string                               | 是   |序列号。       |
516| name             | string                               | 是   |设备名字。      |
517| manufacturerName | string                               | 是   |产商信息。      |
518| productName      | string                               | 是   |产品信息。      |
519| version          | string                               | 是   |版本。        |
520| vendorId         | number                               | 是   |厂商ID。      |
521| productId        | number                               | 是   |产品ID。      |
522| clazz            | number                               | 是   |设备类。       |
523| subClass         | number                               | 是   |设备子类。      |
524| protocol         | number                               | 是   |设备协议码。     |
525| configs          | Array<[USBConfig](#usbconfig)> | 是   |设备配置描述符信息。 |
526
527## USBDevicePipe
528
529USB设备消息传输通道，用于确定设备。
530
531**系统能力：** SystemCapability.USB.USBManager
532
533| 名称       | 类型   | 必填  |说明    |
534| ---------- | ------ | ----- |----- |
535| busNum     | number | 是   |总线地址。 |
536| devAddress | number | 是   |设备地址。 |
537
538## USBControlParams
539
540控制传输参数。
541
542**系统能力：** SystemCapability.USB.USBManager
543
544| 名称      | 类型                                            | 必填 |说明               |
545| ------- | ----------------------------------------------- | ---------------- |---------------- |
546| request | number                                          | 是   |请求类型。            |
547| target  | [USBRequestTargetType](#usbrequesttargettype)   | 是   |请求目标类型。          |
548| reqType | [USBControlRequestType](#usbcontrolrequesttype) | 是   |请求控制类型。          |
549| value   | number                                          | 是   |请求参数。            |
550| index   | number                                          | 是   |请求参数value对应的索引值。 |
551| data    | Uint8Array                                      | 是   |用于写入或读取的缓冲区。     |
552
553
554## USBRequestTargetType
555
556请求目标类型。
557
558**系统能力：** SystemCapability.USB.USBManager
559
560| 名称                         | 值   | 说明   |
561| ---------------------------- | ---- | ------ |
562| USB_REQUEST_TARGET_DEVICE    | 0    | 设备。 |
563| USB_REQUEST_TARGET_INTERFACE | 1    | 接口。 |
564| USB_REQUEST_TARGET_ENDPOINT  | 2    | 端点。 |
565| USB_REQUEST_TARGET_OTHER     | 3    | 其他。 |
566
567## USBControlRequestType
568
569控制请求类型。
570
571**系统能力：** SystemCapability.USB.USBManager
572
573| 名称                      | 值   | 说明   |
574| ------------------------- | ---- | ------ |
575| USB_REQUEST_TYPE_STANDARD | 0    | 标准。 |
576| USB_REQUEST_TYPE_CLASS    | 1    | 类。   |
577| USB_REQUEST_TYPE_VENDOR   | 2    | 厂商。 |
578
579## USBRequestDirection
580
581请求方向。
582
583**系统能力：** SystemCapability.USB.USBManager
584
585| 名称                        | 值   | 说明                     |
586| --------------------------- | ---- | ------------------------ |
587| USB_REQUEST_DIR_TO_DEVICE   | 0    | 写数据，主设备往从设备。 |
588| USB_REQUEST_DIR_FROM_DEVICE | 0x80 | 读数据，从设备往主设备。 |
589
590