1/*
2 * Copyright (c) 2022 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 3.2
28 */
29
30/* *
31 * @file IUsbInterface.idl
32 *
33 * @brief Declares the APIs provided by the usb module for obtaining usb information, subscribing to or
34 * unsubscribing from usb data, enabling or disabling a usb, setting the usb data reporting mode,
35 * and setting usb options such as the accuracy and measurement range.
36 *
37 * @since 3.2
38 * @version 1.0
39 */
40
41package ohos.hdi.usb.v1_0;
42
43import ohos.hdi.usb.v1_0.UsbTypes;
44import ohos.hdi.usb.v1_0.IUsbdSubscriber;
45import ohos.hdi.usb.v1_0.IUsbdBulkCallback;
46
47/* *
48 * @brief Defines the functions for performing basic operations on usb.
49 *
50 * The operations include obtaining usb information, subscribing to or unsubscribing from usb data,
51 * enabling or disabling a usb, setting the usb data reporting mode, and setting usb options such as
52 * the accuracy and measurement range.
53 */
54interface IUsbInterface {
55
56    /* *
57     * @brief Opens a USB device to set up a connection.
58     *
59     * @param dev Indicates the USB device address.
60     *
61     * @return Returns <b>0</b> if the operation is successful; returns a non-0 value if the operation fails.
62     * @since 3.2
63     */
64    OpenDevice([in] struct UsbDev dev);
65
66    /* *
67     * @brief Closes a USB device to release all system resources related to the device.
68     *
69     * @param dev Indicates the USB device address.
70     *
71     * @return Returns <b>0</b> if the operation is successful; returns a non-0 value if the operation fails.
72     * @since 3.2
73     */
74    CloseDevice([in] struct UsbDev dev);
75
76    /* *
77     * @brief Obtains the USB device descriptor.
78     *
79     * @param dev Indicates the USB device address.
80     * @param descriptor Indicates the USB device descriptor.
81     *
82     * @return Returns <b>0</b> if the operation is successful; returns a non-0 value if the operation fails.
83     * @since 3.2
84     */
85    GetDeviceDescriptor([in] struct UsbDev dev, [out] unsigned char[] descriptor);
86
87    /* *
88     * @brief Obtains the string descriptor of a USB device based on the specified string ID.
89     *
90     * @param dev Indicates the USB device address.
91     * @param descId Indicates string descriptor ID.
92     * @param descriptor Indicates the configuration descriptor of the USB device.
93     *
94     * @return Returns <b>0</b> if the operation is successful; returns a non-0 value if the operation fails.
95     * @since 3.2
96     */
97    GetStringDescriptor([in] struct UsbDev dev, [in] unsigned char descId, [out] unsigned char[] descriptor);
98
99    /* *
100     * @brief Obtains the configuration descriptor of a USB device based on the specified config ID.
101     *
102     * @param dev Indicates the USB device address.
103     * @param descId Indicates configuration descriptor ID.
104     * @param descriptor Indicates the configuration descriptor of the USB device.
105     *
106     * @return Returns <b>0</b> if the operation is successful; returns a non-0 value if the operation fails.
107     * @since 3.2
108     */
109    GetConfigDescriptor([in] struct UsbDev dev, [in] unsigned char descId, [out] unsigned char[] descriptor);
110
111    /* *
112     * @brief Obtains the raw descriptor.
113     *
114     * @param dev Indicates the USB device address.
115     * @param descriptor Indicates the raw descriptor of the USB device.
116     *
117     * @return Returns <b>0</b> if the operation is successful; returns a non-0 value if the operation fails.
118     * @since 3.2
119     */
120    GetRawDescriptor([in] struct UsbDev dev, [out] unsigned char[] descriptor);
121
122    /* *
123     * @brief Obtains the file descriptor.
124     *
125     * @param dev Indicates the USB device address.
126     * @param fd USB device file descriptor
127     *
128     * @return Returns <b>0</b> if the operation is successful; returns a non-0 value if the operation fails.
129     * @since 3.2
130     * @deprecated since 5.0
131     * @useinstead ohos.hdi.usb.v1_1.IUsbInterface.GetDeviceFileDescriptor
132     */
133    GetFileDescriptor([in] struct UsbDev dev, [out] int fd);
134
135    /* *
136     * @brief Sets the configuration information of a USB device.
137     *
138     * @param dev Indicates the USB device address.
139     * @param configIndex Indicates the configuration information of the USB device.
140     *
141     * @return Returns <b>0</b> if the operation is successful; returns a non-0 value if the operation fails.
142     * @since 3.2
143     */
144    SetConfig([in] struct UsbDev dev, [in] unsigned char configIndex);
145
146    /* *
147     * @brief Obtains the configuration information of a USB device.
148     *
149     * @param dev Indicates the USB device address.
150     * @param configIndex Indicates the configuration information of the USB device.
151     *
152     * @return Returns <b>0</b> if the operation is successful; returns a non-0 value if the operation fails.
153     * @since 3.2
154     */
155    GetConfig([in] struct UsbDev dev, [out] unsigned char configIndex);
156
157    /* *
158     * @brief Claims a USB interface exclusively. This must be done before data transfer.
159     *
160     * @param dev Indicates the USB device address.
161     * @param interfaceid Indicates the interface ID of the USB device.
162     * @param force Indicates whether to enable the force mode. The value <b>1</b> indicates that the force mode is
163     * enabled, and value <b>0</b> indicates the opposite.
164     *
165     * @return Returns <b>0</b> if the operation is successful; returns a non-0 value if the operation fails.
166     * @since 3.2
167     */
168    ClaimInterface([in] struct UsbDev dev, [in] unsigned char interfaceid, [in] unsigned char force);
169
170    /* *
171     * @brief Manage a USB interface exclusively. Detach or attach the interface.
172     *
173     * @param dev Indicates the USB device address.
174     * @param interfaceid Indicates the interface ID of the USB device.
175     * @param disable Indicates whether to disable the interface.
176     *
177     * @return Returns <b>0</b> if the operation is successful; returns a non-0 value if the operation fails.
178     * @since 3.2
179     */
180    ManageInterface([in] struct UsbDev dev, [in] unsigned char interfaceid, [in] boolean disable);
181
182    /* *
183     * @brief Releases a USB interface. This is usually done after data transfer.
184     *
185     * @param dev Indicates the USB device address.
186     * @param interfaceid Indicates the interface ID of the USB device.
187     *
188     * @return Returns <b>0</b> if the operation is successful; returns a non-0 value if the operation fails.
189     * @since 3.2
190     */
191    ReleaseInterface([in] struct UsbDev dev, [in] unsigned char interfaceid);
192
193    /* *
194     * @brief Sets the alternate settings for the specified USB interface. This allows you to switch between two
195     * interfaces with the same ID but different alternate settings.
196     *
197     * @param dev Indicates the USB device address.
198     * @param interfaceid Indicates the interface ID of the USB device.
199     * @param altIndex Indicates the alternate settings of the USB interface.
200     *
201     * @return Returns <b>0</b> if the operation is successful; returns a non-0 value if the operation fails.
202     * @since 3.2
203     */
204    SetInterface([in] struct UsbDev dev, [in] unsigned char interfaceid, [in] unsigned char altIndex);
205
206    /* *
207     * @brief Reads data on a specified endpoint during bulk transfer. The endpoint must be in the data reading
208     * direction. You can specify a timeout duration if needed.
209     *
210     * @param dev Indicates the USB device address.
211     * @param pipe Indicates the pipe of the USB device.
212     * @param timeout Indicates the timeout duration.
213     * @param data Indicates the read data.
214     *
215     * @return Returns <b>0</b> if the operation is successful; returns a non-0 value if the operation fails.
216     * @since 3.2
217     * @deprecated since 5.0
218     * @useinstead ohos.hdi.usb.v1_1.IUsbInterface.BulkTransferReadwithLength
219     */
220    BulkTransferRead([in] struct UsbDev dev, [in] struct UsbPipe pipe, [in] int timeout, [out] unsigned char[] data);
221
222    /* *
223     * @brief Writes data on a specified endpoint during bulk transfer. The endpoint must be in the data writing
224     * direction.
225     *
226     * @param dev Indicates the USB device address.
227     * @param pipe Indicates the pipe of the USB device.
228     * @param timeout Indicates the timeout duration.
229     * @param data Indicates the written data.
230     *
231     * @return Returns <b>0</b> if the operation is successful; returns a non-0 value if the operation fails.
232     * @since 3.2
233     */
234    BulkTransferWrite([in] struct UsbDev dev, [in] struct UsbPipe pipe, [in] int timeout, [in] unsigned char[] data);
235
236    /* *
237     * @brief Performs control transfer for endpoint 0 of the device. The data transfer direction is determined by the
238     * request type. If the result of <b>requestType</b>&
239     * <b>USB_ENDPOINT_DIR_MASK</b> is <b>USB_DIR_OUT</b>, the endpoint is in the data writing direction; if the result
240     * is <b>USB_DIR_IN</b>, the endpoint is in the data reading direction.
241     *
242     * @param dev Indicates the USB device address.
243     * @param ctrl Indicates the control data packet structure.
244     * @param data Indicates the read data.
245     *
246     * @return Returns <b>0</b> if the operation is successful; returns a non-0 value if the operation fails.
247     * @since 3.2
248     * @deprecated since 5.0
249     * @useinstead ohos.hdi.usb.v1_1.IUsbInterface.ControlTransferReadwithLength
250     */
251    ControlTransferRead([in] struct UsbDev dev, [in] struct UsbCtrlTransfer ctrl, [out] unsigned char[] data);
252
253    /* *
254     * @brief Performs control transfer for endpoint 0 of the device. The data transfer direction is determined by the
255     * request type. If the result of <b>requestType</b>&
256     * <b>USB_ENDPOINT_DIR_MASK</b> is <b>USB_DIR_OUT</b>, the endpoint is in the data writing direction; if the result
257     * is <b>USB_DIR_IN</b>, the endpoint is in the data writing direction.
258     *
259     * @param dev Indicates the USB device address.
260     * @param ctrl Indicates the control data packet structure.
261     * @param data Indicates the write data.
262     *
263     * @return Returns <b>0</b> if the operation is successful; returns a non-0 value if the operation fails.
264     * @since 3.2
265     */
266    ControlTransferWrite([in] struct UsbDev dev, [in] struct UsbCtrlTransfer ctrl, [in] unsigned char[] data);
267
268    /* *
269     * @brief Reads data on a specified endpoint during interrupt transfer. The endpoint must be in the data reading
270     * direction.
271     *
272     * @param dev Indicates the USB device address.
273     * @param pipe Indicates the pipe of the USB device.
274     * @param timeout Indicates the timeout duration.
275     * @param data Indicates the read data.
276     *
277     * @return Returns <b>0</b> if the operation is successful; returns a non-0 value if the operation fails.
278     * @since 3.2
279     */
280    InterruptTransferRead([in] struct UsbDev dev, [in] struct UsbPipe pipe, [in] int timeout, [out] unsigned char[] data);
281
282    /* *
283     * @brief Writes data on a specified endpoint during interrupt transfer. The endpoint must be in the data writing
284     * direction.
285     *
286     * @param dev Indicates the USB device address.
287     * @param pipe Indicates the pipe of the USB device.
288     * @param timeout Indicates the timeout duration.
289     * @param data Indicates the read data.
290     *
291     * @return Returns <b>0</b> if the operation is successful; returns a non-0 value if the operation fails.
292     * @since 3.2
293     */
294    InterruptTransferWrite([in] struct UsbDev dev, [in] struct UsbPipe pipe, [in] int timeout, [in] unsigned char[] data);
295
296    /* *
297     * @brief Reads data on a specified endpoint during isochronous transfer. The endpoint must be in the data reading
298     * direction.
299     *
300     * @param dev Indicates the USB device address.
301     * @param pipe Indicates the pipe of the USB device.
302     * @param timeout Indicates the timeout duration.
303     * @param data Indicates the read data.
304     *
305     * @return Returns <b>0</b> if the operation is successful; returns a non-0 value if the operation fails.
306     * @since 3.2
307     */
308    IsoTransferRead([in] struct UsbDev dev, [in] struct UsbPipe pipe, [in] int timeout, [out] unsigned char[] data);
309
310    /* *
311     * @brief Writes data on a specified endpoint during isochronous transfer. The endpoint must be in the data writing
312     * direction.
313     *
314     * @param dev Indicates the USB device address.
315     * @param pipe Indicates the pipe of the USB device.
316     * @param timeout Indicates the timeout duration.
317     * @param data Indicates the read data.
318     *
319     * @return Returns <b>0</b> if the operation is successful; returns a non-0 value if the operation fails.
320     * @since 3.2
321     */
322    IsoTransferWrite([in] struct UsbDev dev, [in] struct UsbPipe pipe, [in] int timeout, [in] unsigned char[] data);
323
324    /* *
325     * @brief Sends or receives requests for isochronous transfer on a specified endpoint. The data transfer direction
326     * is determined by the endpoint direction.
327     *
328     * @param dev Indicates the USB device address.
329     * @param pipe Indicates the pipe of the USB device.
330     * @param clientData Indicates the client data.
331     * @param buffer Indicates the transferred data.
332     *
333     * @return Returns <b>0</b> if the operation is successful; returns a non-0 value if the operation fails.
334     * @since 3.2
335     */
336    RequestQueue([in] struct UsbDev dev, [in] struct UsbPipe pipe, [in] unsigned char[] clientData, [in] unsigned char[] buffer);
337
338    /* *
339     * @brief Waits for the operation result of the isochronous transfer request in <b>RequestQueue</b>.
340     *
341     * @param dev Indicates the USB device address.
342     * @param clientData Indicates the client data.
343     * @param buffer Indicates the transferred data.
344     * @param timeout Indicates the timeout duration.
345     *
346     * @return Returns <b>0</b> if the operation is successful; returns a non-0 value if the operation fails.
347     * @since 3.2
348     */
349    RequestWait([in] struct UsbDev dev, [out] unsigned char[] clientData, [out] unsigned char[] buffer, [in] int timeout);
350
351    /* *
352     * @brief Cancels the data transfer requests to be processed.
353     *
354     * @param dev Indicates the USB device address.
355     * @param pipe Indicates the pipe of the USB device.
356     *
357     * @return Returns <b>0</b> if the operation is successful; returns a non-0 value if the operation fails.
358     * @since 3.2
359     */
360    RequestCancel([in] struct UsbDev dev, [in] struct UsbPipe pipe);
361
362    /* *
363     * @brief Obtains the list of functions (represented by bit field) supported by the current device.
364     *
365     * @param funcs Indicates the list of functions supported by the current device.
366     *
367     * @return Returns <b>0</b> if the operation is successful; returns a non-0 value if the operation fails.
368     * @since 3.2
369     */
370    GetCurrentFunctions([out] int funcs);
371
372    /* *
373     * @brief Sets the list of functions (represented by bit field) supported by the current device.
374     *
375     * @param funcs Indicates the list of functions supported by the current device.
376     *
377     * @return Returns <b>0</b> if the operation is successful; returns a non-0 value if the operation fails.
378     * @since 3.2
379     */
380    SetCurrentFunctions([in] int funcs);
381
382    /* *
383     * @brief Closes a USB device to release all system resources related to the device.
384     *
385     * @param portId Indicates the port ID of the USB interface.
386     * @param powerRole Indicates the power role.
387     * @param dataRole Indicates the data role.
388     *
389     * @return Returns <b>0</b> if the operation is successful; returns a non-0 value if the operation fails.
390     * @since 3.2
391     */
392    SetPortRole([in] int portId, [in] int powerRole, [in] int dataRole);
393
394    /* *
395     * @brief Queries the current settings of a port.
396     *
397     * @param portId Indicates the port ID of the USB interface.
398     * @param powerRole Indicates the power role.
399     * @param dataRole Indicates the data role.
400     * @param mode Indicates the mode.
401     *
402     * @return Returns <b>0</b> if the operation is successful; returns a non-0 value if the operation fails.
403     * @since 3.2
404     */
405    QueryPort([out] int portId, [out] int powerRole, [out] int dataRole, [out] int mode);
406
407    /* *
408     * @brief Binds a subscriber.
409     *
410     * @param subscriber Indicates the subscriber.
411     *
412     * @return Returns <b>0</b> if the operation is successful; returns a non-0 value if the operation fails.
413     * @since 3.2
414     */
415    BindUsbdSubscriber([in] IUsbdSubscriber subscriber);
416
417    /* *
418     * @brief Unbinds a subscriber.
419     *
420     * @param subscriber Indicates the subscriber.
421     *
422     * @return Returns <b>0</b> if the operation is successful; returns a non-0 value if the operation fails.
423     * @since 3.2
424     */
425    UnbindUsbdSubscriber([in] IUsbdSubscriber subscriber);
426
427    /* *
428     * @brief Registers a callback for isochronous bulk transfer.
429     *
430     * @param dev Indicates the USB device address.
431     * @param pipe Indicates the pipe of the USB device.
432     * @param cb Indicates the reference to the callback.
433     *
434     * @return Returns <b>0</b> if the operation is successful; returns a non-0 value if the operation fails.
435     * @since 3.2
436     */
437    RegBulkCallback([in] struct UsbDev dev, [in] struct UsbPipe pipe, [in] IUsbdBulkCallback cb);
438
439    /* *
440     * @brief Unregisters the callback for isochronous bulk transfer.
441     *
442     * @param dev Indicates the USB device address.
443     * @param pipe Indicates the pipe of the USB device.
444     *
445     * @return Returns <b>0</b> if the operation is successful; returns a non-0 value if the operation fails.
446     * @since 3.2
447     */
448    UnRegBulkCallback([in] struct UsbDev dev, [in] struct UsbPipe pipe);
449
450    /* *
451     * @brief Reads data during isochronous bulk transfer.
452     *
453     * @param dev Indicates the USB device address.
454     * @param pipe Indicates the pipe of the USB device.
455     * @param ashmem Indicates the shared memory, which is used to store the read data.
456     *
457     * @return Returns <b>0</b> if the operation is successful; returns a non-0 value if the operation fails.
458     * @since 3.2
459     */
460    BulkRead([in] struct UsbDev dev, [in] struct UsbPipe pipe, [in] Ashmem ashmem);
461
462    /* *
463     * @brief Writes data during isochronous bulk transfer.
464     *
465     * @param dev Indicates the USB device address.
466     * @param pipe Indicates the pipe of the USB device.
467     * @param ashmem Indicates the shared memory, which is used to store the written data.
468     *
469     * @return Returns <b>0</b> if the operation is successful; returns a non-0 value if the operation fails.
470     * @since 3.2
471     */
472    BulkWrite([in] struct UsbDev dev, [in] struct UsbPipe pipe, [in] Ashmem ashmem);
473
474    /* *
475     * @brief Cancels the isochronous bulk transfer. The read and write operations on the current USB interface will
476     * be cancelled.
477     *
478     * @param dev Indicates the USB device address.
479     * @param pipe Indicates the pipe of the USB device.
480     *
481     * @return Returns <b>0</b> if the operation is successful; returns a non-0 value if the operation fails.
482     * @since 3.2
483     */
484    BulkCancel([in] struct UsbDev dev, [in] struct UsbPipe pipe);
485}