• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1/*
2 * Copyright (c) 2025 Huawei Device Co., Ltd.
3 * Licensed under the Apache License, Version 2.0 (the "License");
4 * you may not use this file except in compliance with the License.
5 * You may obtain a copy of the License at
6 *
7 *     http://www.apache.org/licenses/LICENSE-2.0
8 *
9 * Unless required by applicable law or agreed to in writing, software
10 * distributed under the License is distributed on an "AS IS" BASIS,
11 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12 * See the License for the specific language governing permissions and
13 * limitations under the License.
14 */
15
16/* *
17 * @addtogroup HdiUsb
18 * @{
19 *
20 * @brief Provides unified APIs for usb services to access usb drivers.
21 *
22 * A usb service can obtain a usb driver object or agent and then call APIs provided by this object or agent to
23 * access different types of usb devices based on the usb IDs, thereby obtaining usb information,
24 * subscribing to or unsubscribing from usb data, enabling or disabling a usb,
25 * setting the usb data reporting mode, and setting usb options such as the accuracy and measurement range.
26 *
27 * @since 5.1
28 * @version 1.0
29 */
30
31/* *
32 * @file IUsbHostInterface.idl
33 *
34 * @brief Declares the APIs provided by the usb module for obtaining usb information, subscribing to or
35 * unsubscribing from usb data, enabling or disabling a usb, setting the usb data reporting mode,
36 * and setting usb options such as the accuracy and measurement range.
37 *
38 * @since 5.1
39 * @version 1.0
40 */
41
42package ohos.hdi.usb.v2_0;
43
44import ohos.hdi.usb.v2_0.UsbTypes;
45import ohos.hdi.usb.v2_0.IUsbdSubscriber;
46import ohos.hdi.usb.v2_0.IUsbdBulkCallback;
47import ohos.hdi.usb.v2_0.IUsbdTransferCallback;
48
49/* *
50 * @brief Defines the functions for performing basic operations on usb.
51 *
52 * The operations include obtaining usb information, subscribing to or unsubscribing from usb data,
53 * enabling or disabling a usb, setting the usb data reporting mode, and setting usb options such as
54 * the accuracy and measurement range.
55 */
56interface IUsbHostInterface {
57
58    /* *
59     * @brief Opens a USB device to set up a connection.
60     *
61     * @param dev Indicates the USB device address.
62     *
63     * @return Returns <b>0</b> if the operation is successful; returns a non-0 value if the operation fails.
64     * @since 5.1
65     * @version 1.0
66     */
67    OpenDevice([in] struct UsbDev dev);
68
69    /* *
70     * @brief Closes a USB device to release all system resources related to the device.
71     *
72     * @param dev Indicates the USB device address.
73     *
74     * @return Returns <b>0</b> if the operation is successful; returns a non-0 value if the operation fails.
75     * @since 5.1
76     * @version 1.0
77     */
78    CloseDevice([in] struct UsbDev dev);
79
80    /* *
81     * @brief Reset device.
82     *
83     * @param dev Indicates the USB device address.
84     *
85     * @return Returns <b>0</b> if the operation is successful; returns a non-0 value if the operation fails.
86     * @since 5.1
87     * @version 1.0
88     */
89    ResetDevice([in] struct UsbDev dev);
90
91    /* *
92     * @brief Claims a USB interface exclusively. This must be done before data transfer.
93     *
94     * @param dev Indicates the USB device address.
95     * @param interfaceid Indicates the interface ID of the USB device.
96     * @param force Indicates whether to enable the force mode. The value <b>1</b> indicates that the force mode is
97     * enabled, and value <b>0</b> indicates the opposite.
98     *
99     * @return Returns <b>0</b> if the operation is successful; returns a non-0 value if the operation fails.
100     * @since 5.1
101     * @version 1.0
102     */
103    ClaimInterface([in] struct UsbDev dev, [in] unsigned char interfaceid, [in] unsigned char force);
104
105    /* *
106     * @brief Sets the alternate settings for the specified USB interface. This allows you to switch between two
107     * interfaces with the same ID but different alternate settings.
108     *
109     * @param dev Indicates the USB device address.
110     * @param interfaceid Indicates the interface ID of the USB device.
111     * @param altIndex Indicates the alternate settings of the USB interface.
112     *
113     * @return Returns <b>0</b> if the operation is successful; returns a non-0 value if the operation fails.
114     * @since 5.1
115     * @version 1.0
116     */
117    SetInterface([in] struct UsbDev dev, [in] unsigned char interfaceid, [in] unsigned char altIndex);
118
119    /* *
120     * @brief Releases a USB interface. This is usually done after data transfer.
121     *
122     * @param dev Indicates the USB device address.
123     * @param interfaceid Indicates the interface ID of the USB device.
124     *
125     * @return Returns <b>0</b> if the operation is successful; returns a non-0 value if the operation fails.
126     * @since 5.1
127     * @version 1.0
128     */
129    ReleaseInterface([in] struct UsbDev dev, [in] unsigned char interfaceid);
130
131    /* *
132     * @brief Sets the configuration information of a USB device.
133     *
134     * @param dev Indicates the USB device address.
135     * @param configIndex Indicates the configuration information of the USB device.
136     *
137     * @return Returns <b>0</b> if the operation is successful; returns a non-0 value if the operation fails.
138     * @since 5.1
139     * @version 1.0
140     */
141    SetConfig([in] struct UsbDev dev, [in] unsigned char configIndex);
142
143    /* *
144     * @brief Manage a USB interface exclusively. Detach or attach the interface.
145     *
146     * @param dev Indicates the USB device address.
147     * @param interfaceid Indicates the interface ID of the USB device.
148     * @param disable Indicates whether to disable the interface.
149     *
150     * @return Returns <b>0</b> if the operation is successful; returns a non-0 value if the operation fails.
151     * @since 5.1
152     * @version 1.0
153     */
154    ManageInterface([in] struct UsbDev dev, [in] unsigned char interfaceid, [in] boolean disable);
155
156    /* *
157     * @brief Clear the halt status for an endpoint.
158     *
159     * @param dev Indicates the USB device address.
160     * @param pipe Indicates the pipe of the USB device.
161     *
162     * @return Returns <b>0</b> if the operation is successful; returns a non-0 value if the operation fails.
163     * @since 5.1
164     * @version 1.0
165     */
166    ClearHalt([in] struct UsbDev dev, [in] struct UsbPipe pipe);
167
168    /* *
169     * @brief Obtains USB device speed.
170     *
171     * @param dev Indicates the USB device address.
172     * @param speed Indicates the USB device speed.
173     *
174     * @return Returns <b>0</b> if the operation is successful; returns a non-0 value if the operation fails.
175     * @since 5.1
176     * @version 1.0
177     */
178    GetDeviceSpeed([in] struct UsbDev dev, [out] unsigned char speed);
179
180    /* *
181     * @brief Obtains the file descriptor.
182     *
183     * @param dev Indicates the USB device address.
184     * @param fd USB device file descriptor
185     *
186     * @return Returns <b>0</b> if the operation is successful; returns a non-0 value if the operation fails.
187     * @since 5.1
188     * @version 1.0
189     */
190    GetDeviceFileDescriptor([in] struct UsbDev dev, [out] FileDescriptor fd);
191
192    /* *
193     * @brief Obtains the string descriptor of a USB device based on the specified string ID.
194     *
195     * @param dev Indicates the USB device address.
196     * @param descId Indicates string descriptor ID.
197     * @param descriptor Indicates the configuration descriptor of the USB device.
198     *
199     * @return Returns <b>0</b> if the operation is successful; returns a non-0 value if the operation fails.
200     * @since 5.1
201     * @version 1.0
202     */
203    GetStringDescriptor([in] struct UsbDev dev, [in] unsigned char descId, [out] unsigned char[] descriptor);
204
205    /* *
206     * @brief Obtains the raw descriptor.
207     *
208     * @param dev Indicates the USB device address.
209     * @param descriptor Indicates the raw descriptor of the USB device.
210     *
211     * @return Returns <b>0</b> if the operation is successful; returns a non-0 value if the operation fails.
212     * @since 5.1
213     * @version 1.0
214     */
215    GetRawDescriptor([in] struct UsbDev dev, [out] unsigned char[] descriptor);
216
217    /* *
218     * @brief Obtains the configuration information of a USB device.
219     *
220     * @param dev Indicates the USB device address.
221     * @param configIndex Indicates the configuration information of the USB device.
222     *
223     * @return Returns <b>0</b> if the operation is successful; returns a non-0 value if the operation fails.
224     * @since 5.1
225     * @version 1.0
226     */
227    GetConfig([in] struct UsbDev dev, [out] unsigned char configIndex);
228
229    /* *
230     * @brief Obtain the activation information of the USB device interface.
231     *
232     * @param dev Indicates the USB device address.
233     * @param interfaceid Indicates the interface ID of the USB device.
234     * @param unactivated Indicates whether the interface unactivated.
235     *
236     * @return Returns <b>0</b> if the operation is successful; returns a non-0 value if the operation fails.
237     * @since 5.1
238     * @version 1.0
239     */
240    GetInterfaceActiveStatus([in] struct UsbDev dev, [in] unsigned char interfaceid, [out] boolean unactivated );
241
242    /* *
243     * @brief Obtains the USB device descriptor.
244     *
245     * @param dev Indicates the USB device address.
246     * @param descriptor Indicates the USB device descriptor.
247     *
248     * @return Returns <b>0</b> if the operation is successful; returns a non-0 value if the operation fails.
249     * @since 5.1
250     * @version 1.0
251     */
252    GetDeviceDescriptor([in] struct UsbDev dev, [out] unsigned char[] descriptor);
253
254    /* *
255     * @brief Obtains the configuration descriptor of a USB device based on the specified config ID.
256     *
257     * @param dev Indicates the USB device address.
258     * @param descId Indicates configuration descriptor ID.
259     * @param descriptor Indicates the configuration descriptor of the USB device.
260     *
261     * @return Returns <b>0</b> if the operation is successful; returns a non-0 value if the operation fails.
262     * @since 5.1
263     * @version 1.0
264     */
265    GetConfigDescriptor([in] struct UsbDev dev, [in] unsigned char descId, [out] unsigned char[] descriptor);
266
267    /* *
268     * @brief Obtains the file descriptor.
269     *
270     * @param dev Indicates the USB device address.
271     * @param fd USB device file descriptor
272     *
273     * @return Returns <b>0</b> if the operation is successful; returns a non-0 value if the operation fails.
274     * @since 5.1
275     * @version 1.0
276     * @deprecated since 5.1
277     * @useinstead ohos.hdi.usb.v2_0.IUsbInterface.GetDeviceFileDescriptor
278     */
279    GetFileDescriptor([in] struct UsbDev dev, [out] int fd);
280
281    /* *
282     * @brief Sends or receives requests for isochronous transfer on a specified endpoint. The data transfer direction
283     * is determined by the endpoint direction.
284     *
285     * @param dev Indicates the USB device address.
286     * @param pipe Indicates the pipe of the USB device.
287     * @param clientData Indicates the client data.
288     * @param buffer Indicates the transferred data.
289     *
290     * @return Returns <b>0</b> if the operation is successful; returns a non-0 value if the operation fails.
291     * @since 5.1
292     * @version 1.0
293     */
294    RequestQueue([in] struct UsbDev dev, [in] struct UsbPipe pipe, [in] unsigned char[] clientData, [in] unsigned char[] buffer);
295
296    /* *
297     * @brief Waits for the operation result of the isochronous transfer request in <b>RequestQueue</b>.
298     *
299     * @param dev Indicates the USB device address.
300     * @param clientData Indicates the client data.
301     * @param buffer Indicates the transferred data.
302     * @param timeout Indicates the timeout duration.
303     *
304     * @return Returns <b>0</b> if the operation is successful; returns a non-0 value if the operation fails.
305     * @since 5.1
306     * @version 1.0
307     */
308    RequestWait([in] struct UsbDev dev, [out] unsigned char[] clientData, [out] unsigned char[] buffer, [in] int timeout);
309
310    /* *
311     * @brief Cancels the data transfer requests to be processed.
312     *
313     * @param dev Indicates the USB device address.
314     * @param pipe Indicates the pipe of the USB device.
315     *
316     * @return Returns <b>0</b> if the operation is successful; returns a non-0 value if the operation fails.
317     * @since 5.1
318     * @version 1.0
319     */
320    RequestCancel([in] struct UsbDev dev, [in] struct UsbPipe pipe);
321
322    /* *
323     * @brief Reads data on a specified endpoint during bulk transfer. The endpoint must be in the data reading
324     * direction. You can specify a timeout duration if needed.
325     *
326     * @param dev Indicates the USB device address.
327     * @param pipe Indicates the pipe of the USB device.
328     * @param timeout Indicates the timeout duration.
329     * @param data Indicates the read data.
330     *
331     * @return Returns <b>0</b> if the operation is successful; returns a non-0 value if the operation fails.
332     * @since 5.1
333     * @version 1.0
334     * @deprecated since 5.1
335     * @useinstead ohos.hdi.usb.v2_0.IUsbInterface.BulkTransferReadwithLength
336     */
337    BulkTransferRead([in] struct UsbDev dev, [in] struct UsbPipe pipe, [in] int timeout, [out] unsigned char[] data);
338
339    /* *
340     * @brief Writes data on a specified endpoint during bulk transfer. The endpoint must be in the data writing
341     * direction.
342     *
343     * @param dev Indicates the USB device address.
344     * @param pipe Indicates the pipe of the USB device.
345     * @param timeout Indicates the timeout duration.
346     * @param data Indicates the written data.
347     *
348     * @return Returns <b>0</b> if the operation is successful; returns a non-0 value if the operation fails.
349     * @since 5.1
350     * @version 1.0
351     */
352    BulkTransferWrite([in] struct UsbDev dev, [in] struct UsbPipe pipe, [in] int timeout, [in] unsigned char[] data);
353
354    /* *
355     * @brief Reads data on a specified endpoint during bulk transfer. The endpoint must be in the data reading
356     * direction. You can specify a timeout duration if needed.
357     *
358     * @param dev Indicates the USB device address.
359     * @param pipe Indicates the pipe of the USB device.
360     * @param timeout Indicates the timeout duration.
361     * @param length the maximum number of bytes to receive into the data buffer.
362     * @param data Indicates the read data.
363     *
364     * @return Returns <b>0</b> if the operation is successful; returns a non-0 value if the operation fails.
365     * @since 5.1
366     * @version 1.0
367     */
368    BulkTransferReadwithLength([in] struct UsbDev dev, [in] struct UsbPipe pipe, [in] int timeout, [in] int length, [out] unsigned char[] data);
369
370    /* *
371     * @brief Registers a callback for isochronous bulk transfer.
372     *
373     * @param dev Indicates the USB device address.
374     * @param pipe Indicates the pipe of the USB device.
375     * @param cb Indicates the reference to the callback.
376     *
377     * @return Returns <b>0</b> if the operation is successful; returns a non-0 value if the operation fails.
378     * @since 5.1
379     * @version 1.0
380     */
381    RegBulkCallback([in] struct UsbDev dev, [in] struct UsbPipe pipe, [in] IUsbdBulkCallback cb);
382
383    /* *
384     * @brief Unregisters the callback for isochronous bulk transfer.
385     *
386     * @param dev Indicates the USB device address.
387     * @param pipe Indicates the pipe of the USB device.
388     *
389     * @return Returns <b>0</b> if the operation is successful; returns a non-0 value if the operation fails.
390     * @since 5.1
391     * @version 1.0
392     */
393    UnRegBulkCallback([in] struct UsbDev dev, [in] struct UsbPipe pipe);
394
395    /* *
396     * @brief Reads data during isochronous bulk transfer.
397     *
398     * @param dev Indicates the USB device address.
399     * @param pipe Indicates the pipe of the USB device.
400     * @param ashmem Indicates the shared memory, which is used to store the read data.
401     *
402     * @return Returns <b>0</b> if the operation is successful; returns a non-0 value if the operation fails.
403     * @since 5.1
404     * @version 1.0
405     */
406    BulkRead([in] struct UsbDev dev, [in] struct UsbPipe pipe, [in] Ashmem ashmem);
407
408    /* *
409     * @brief Writes data during isochronous bulk transfer.
410     *
411     * @param dev Indicates the USB device address.
412     * @param pipe Indicates the pipe of the USB device.
413     * @param ashmem Indicates the shared memory, which is used to store the written data.
414     *
415     * @return Returns <b>0</b> if the operation is successful; returns a non-0 value if the operation fails.
416     * @since 5.1
417     * @version 1.0
418     */
419    BulkWrite([in] struct UsbDev dev, [in] struct UsbPipe pipe, [in] Ashmem ashmem);
420
421    /* *
422     * @brief Cancels the isochronous bulk transfer. The read and write operations on the current USB interface will
423     * be cancelled.
424     *
425     * @param dev Indicates the USB device address.
426     * @param pipe Indicates the pipe of the USB device.
427     *
428     * @return Returns <b>0</b> if the operation is successful; returns a non-0 value if the operation fails.
429     * @since 5.1
430     * @version 1.0
431     */
432    BulkCancel([in] struct UsbDev dev, [in] struct UsbPipe pipe);
433
434    /* *
435     * @brief Performs control transfer for endpoint 0 of the device. The data transfer direction is determined by the
436     * request type. If the result of <b>requestType</b>&
437     * <b>USB_ENDPOINT_DIR_MASK</b> is <b>USB_DIR_OUT</b>, the endpoint is in the data writing direction; if the result
438     * is <b>USB_DIR_IN</b>, the endpoint is in the data reading direction.
439     *
440     * @param dev Indicates the USB device address.
441     * @param ctrl Indicates the control data packet structure.
442     * @param data Indicates the read data.
443     *
444     * @return Returns <b>0</b> if the operation is successful; returns a non-0 value if the operation fails.
445     * @since 5.1
446     * @version 1.0
447     * @deprecated since 5.1
448     * @useinstead ohos.hdi.usb.v2_0.IUsbInterface.ControlTransferReadwithLength
449     */
450    ControlTransferRead([in] struct UsbDev dev, [in] struct UsbCtrlTransfer ctrl, [out] unsigned char[] data);
451
452    /* *
453     * @brief Performs control transfer for endpoint 0 of the device. The data transfer direction is determined by the
454     * request type. If the result of <b>requestType</b>&
455     * <b>USB_ENDPOINT_DIR_MASK</b> is <b>USB_DIR_OUT</b>, the endpoint is in the data writing direction; if the result
456     * is <b>USB_DIR_IN</b>, the endpoint is in the data writing direction.
457     *
458     * @param dev Indicates the USB device address.
459     * @param ctrl Indicates the control data packet structure.
460     * @param data Indicates the write data.
461     *
462     * @return Returns <b>0</b> if the operation is successful; returns a non-0 value if the operation fails.
463     * @since 5.1
464     * @version 1.0
465     */
466    ControlTransferWrite([in] struct UsbDev dev, [in] struct UsbCtrlTransfer ctrl, [in] unsigned char[] data);
467
468    /* *
469     * @brief Performs control transfer for endpoint 0 of the device. The data transfer direction is determined by the
470     * request type. If the result of <b>requestType</b>&
471     * <b>USB_ENDPOINT_DIR_MASK</b> is <b>USB_DIR_OUT</b>, the endpoint is in the data writing direction; if the result
472     * is <b>USB_DIR_IN</b>, the endpoint is in the data reading direction.
473     *
474     * @param dev Indicates the USB device address.
475     * @param ctrl Indicates the control data packet structure.
476     * @param data Indicates the read data.
477     *
478     * @return Returns <b>0</b> if the operation is successful; returns a non-0 value if the operation fails.
479     * @since 5.1
480     * @version 1.0
481     */
482    ControlTransferReadwithLength([in] struct UsbDev dev, [in] struct UsbCtrlTransferParams ctrl, [out] unsigned char[] data);
483
484    /* *
485     * @brief Reads data on a specified endpoint during interrupt transfer. The endpoint must be in the data reading
486     * direction.
487     *
488     * @param dev Indicates the USB device address.
489     * @param pipe Indicates the pipe of the USB device.
490     * @param timeout Indicates the timeout duration.
491     * @param data Indicates the read data.
492     *
493     * @return Returns <b>0</b> if the operation is successful; returns a non-0 value if the operation fails.
494     * @since 5.1
495     * @version 1.0
496     */
497    InterruptTransferRead([in] struct UsbDev dev, [in] struct UsbPipe pipe, [in] int timeout, [out] unsigned char[] data);
498
499    /* *
500     * @brief Writes data on a specified endpoint during interrupt transfer. The endpoint must be in the data writing
501     * direction.
502     *
503     * @param dev Indicates the USB device address.
504     * @param pipe Indicates the pipe of the USB device.
505     * @param timeout Indicates the timeout duration.
506     * @param data Indicates the read data.
507     *
508     * @return Returns <b>0</b> if the operation is successful; returns a non-0 value if the operation fails.
509     * @since 5.1
510     * @version 1.0
511     */
512    InterruptTransferWrite([in] struct UsbDev dev, [in] struct UsbPipe pipe, [in] int timeout, [in] unsigned char[] data);
513
514    /* *
515     * @brief Reads data on a specified endpoint during isochronous transfer. The endpoint must be in the data reading
516     * direction.
517     *
518     * @param dev Indicates the USB device address.
519     * @param pipe Indicates the pipe of the USB device.
520     * @param timeout Indicates the timeout duration.
521     * @param data Indicates the read data.
522     *
523     * @return Returns <b>0</b> if the operation is successful; returns a non-0 value if the operation fails.
524     * @since 5.1
525     * @version 1.0
526     */
527    IsoTransferRead([in] struct UsbDev dev, [in] struct UsbPipe pipe, [in] int timeout, [out] unsigned char[] data);
528
529    /* *
530     * @brief Writes data on a specified endpoint during isochronous transfer. The endpoint must be in the data writing
531     * direction.
532     *
533     * @param dev Indicates the USB device address.
534     * @param pipe Indicates the pipe of the USB device.
535     * @param timeout Indicates the timeout duration.
536     * @param data Indicates the read data.
537     *
538     * @return Returns <b>0</b> if the operation is successful; returns a non-0 value if the operation fails.
539     * @since 5.1
540     * @version 1.0
541     */
542    IsoTransferWrite([in] struct UsbDev dev, [in] struct UsbPipe pipe, [in] int timeout, [in] unsigned char[] data);
543
544    /* *
545     * @brief Binds a subscriber.
546     *
547     * @param subscriber Indicates the subscriber.
548     *
549     * @return Returns <b>0</b> if the operation is successful; returns a non-0 value if the operation fails.
550     * @since 5.1
551     * @version 1.0
552     */
553    BindUsbdHostSubscriber([in] IUsbdSubscriber subscriber);
554
555    /* *
556     * @brief Unbinds a subscriber.
557     *
558     * @param subscriber Indicates the subscriber.
559     *
560     * @return Returns <b>0</b> if the operation is successful; returns a non-0 value if the operation fails.
561     * @since 5.1
562     * @version 1.0
563     */
564    UnbindUsbdHostSubscriber([in] IUsbdSubscriber subscriber);
565
566    /* *
567     * @brief Submit usb async transfer.
568     *
569     * @param dev Indicates the USB device address.
570     * @param info Indicates the param info of the USB transfer.
571     * @param cb Indicates the callback function of base.
572     * @param ashmem Indicates the object of share memory
573     *
574     * @return Returns <b>0</b> if the operation is successful; returns a non-0 value if the operation fails.
575     * @since 5.1
576     * @version 1.0
577     */
578    UsbSubmitTransfer([in] struct UsbDev dev, [in] USBTransferInfo info, [in] IUsbdTransferCallback cb, [in] Ashmem ashmem);
579
580    /* *
581     * @brief Cancels the usb async transfer by endpoint.
582     *
583     * @param dev Indicates the USB device address.
584     * @param endpoint Indicates the endpoint address.
585     *
586     * @return Returns <b>0</b> if the operation is successful; returns a non-0 value if the operation fails.
587     * @since 5.1
588     * @version 1.0
589     */
590    UsbCancelTransfer([in] struct UsbDev dev, [in] int endpoint);
591}