1/*
2 * Copyright (c) 2023 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 HdiUsbDdk
18 * @{
19 *
20 * @brief Provides USB DDK APIs to open and close USB interfaces, perform non-isochronous and isochronous\n
21 * data transfer over USB pipes, and implement control transfer and interrupt transfer, etc.
22 * @since 4.0
23 */
24
25/* *
26 * @file IUsbDdk.idl
27 *
28 * @brief Declares the USB DDK APIs used by the USB host to access USB devices.
29 *
30 * @since 4.0
31 * @version 1.0
32 */
33
34package ohos.hdi.usb.ddk.v1_0;
35
36import ohos.hdi.usb.ddk.v1_0.UsbDdkTypes;
37
38/* *
39 * @brief Declares the USB DDK APIs used by the USB host to access USB devices.
40 */
41interface IUsbDdk
42{
43
44    /* *
45     * @brief Initializes the DDK.
46     *
47     * @return <b>0</b> if the operation is successful; a negative value otherwise.
48     * @since 4.0
49     */
50    Init();
51
52    /* *
53     * @brief Releases the DDK.
54     *
55     * @return <b>0</b> if the operation is successful; a negative value otherwise.
56     * @since 4.0
57     */
58    Release();
59
60    /* *
61     * @brief Obtains the USB device descriptor.
62     *
63     * @param deviceId ID of the device whose descriptor is to be obtained.
64     * @param desc Standard device descriptor defined in the USB protocol.
65     *
66     * @return <b>0</b> if the operation is successful; a negative value otherwise.
67     * @since 4.0
68     */
69    GetDeviceDescriptor([in] unsigned long deviceId, [out] struct UsbDeviceDescriptor desc);
70
71    /* *
72     * @brief Obtains the configuration descriptor.
73     *
74     * @param deviceId ID of the device whose configuration descriptor is to be obtained.
75     * @param configIndex Configuration index, which corresponds to <b>bConfigurationValue</b> in the USB protocol.
76     * @param configDesc Configuration descriptor, which includes the standard configuration descriptor defined in the\n
77     * USB protocol and the associated interface descriptor and endpoint descriptor.
78     *
79     * @return <b>0</b> if the operation is successful; a negative value otherwise.
80     * @since 4.0
81     */
82    GetConfigDescriptor([in] unsigned long deviceId, [in] unsigned char configIndex, [out] List<unsigned char> configDesc);
83
84    /* *
85     * @brief Claims a USB interface.
86     *
87     * @param deviceId ID of the device to be operated.
88     * @param interfaceIndex Interface index, which corresponds to <b>bInterfaceNumber</b> in the USB protocol.
89     * @param interfaceHandle Interface operation handle. After the interface is claimed successfully, a value will be\n
90     * assigned to this parameter.
91     *
92     * @return <b>0</b> if the operation is successful; a negative value otherwise.
93     * @since 4.0
94     */
95    ClaimInterface([in] unsigned long deviceId, [in] unsigned char interfaceIndex, [out] unsigned long interfaceHandle);
96
97    /* *
98     * @brief Releases a USB interface.
99     *
100     * @param interfaceHandle Interface operation handle.
101     *
102     * @return  <b>0</b> if the operation is successful; a negative value otherwise.
103     * @since 4.0
104     */
105    ReleaseInterface([in] unsigned long interfaceHandle);
106
107    /* *
108     * @brief Activates the alternate setting of the USB interface.
109     *
110     * @param interfaceHandle Interface operation handle.
111     * @param settingIndex Index of the alternate setting, which corresponds to <b>bAlternateSetting</b>\n
112     * in the USB protocol.
113     * @return  <b>0</b> if the operation is successful; a negative value otherwise.
114     * @since 4.0
115     */
116    SelectInterfaceSetting([in] unsigned long interfaceHandle, [in] unsigned char settingIndex);
117
118    /* *
119     * @brief Obtains the activated alternate setting of the USB interface.
120     *
121     * @param interfaceHandle Interface operation handle.
122     * @param settingIndex Index of the alternate setting, which corresponds to <b>bAlternateSetting</b>\n
123     * in the USB protocol.
124     *
125     * @return  <b>0</b> if the operation is successful; a negative value otherwise.
126     * @since 4.0
127     */
128    GetCurrentInterfaceSetting([in] unsigned long interfaceHandle, [out] unsigned char settingIndex);
129
130    /* *
131     * @brief Sends a control read transfer request. This API works in a synchronous manner.
132     *
133     * @param interfaceHandle Interface operation handle.
134     * @param setup Request data, which corresponds to <b>Setup Data</b> in the USB protocol.
135     * @param timeout Timeout duration, in milliseconds.
136     * @param data Data to be transferred.
137     * @return  <b>0</b> if the operation is successful; a negative value otherwise.
138     * @since 4.0
139     */
140    SendControlReadRequest([in] unsigned long interfaceHandle, [in] struct UsbControlRequestSetup setup, [in] unsigned int timeout, [out] List<unsigned char> data);
141
142    /* *
143     * @brief Sends a control write transfer request. This API works in a synchronous manner.
144     *
145     * @param interfaceHandle Interface operation handle.
146     * @param setup Request data, which corresponds to <b>Setup Data</b> in the USB protocol.
147     * @param timeout Timeout duration, in milliseconds.
148     * @param data Data to be transferred.
149     *
150     * @return <b>0</b> if the operation is successful; a negative value otherwise.
151     * @since 4.0
152     */
153    SendControlWriteRequest([in] unsigned long interfaceHandle, [in] struct UsbControlRequestSetup setup, [in] unsigned int timeout, [in] List<unsigned char> data);
154
155    /* *
156     * @brief Sends a pipe request. This API works in a synchronous manner. This API applies to interrupt transfer\n
157     * and bulk transfer.
158     *
159     * @param pipe Pipe used to transfer data.
160     * @param size Buffer size.
161     * @param offset Offset of the used buffer. The default value is 0, indicating that there is no offset\n
162     * and the buffer starts from the specified address.
163     * @param length Length of the used buffer. By default, the value is equal to the size, indicating that\n
164     * the entire buffer is used.
165     * @param transferredLength Length of the transferred data.
166     *
167     * @return <b>0</b> if the operation is successful; a negative value otherwise.
168     * @since 4.0
169     */
170    SendPipeRequest([in] struct UsbRequestPipe pipe, [in] unsigned int size, [in] unsigned int offset, [in] unsigned int length, [out] unsigned int transferedLength);
171
172    /* *
173     * @brief Sends a pipe request. This API works in a synchronous manner. This API applies to interrupt transfer\n
174     * and bulk transfer.
175     *
176     * @param pipe Pipe used to transfer data.
177     * @param ashmem Share memory used to transfer data;
178     * @param transferredLength Length of the transferred data;
179     *
180     * @return <b>0</b> if the operation is successful; a negative value otherwise.
181     * @since 5.0
182     * @version 1.0
183     */
184    SendPipeRequestWithAshmem([in] struct UsbRequestPipe pipe, [in] UsbAshmem ashmem, [out] unsigned int transferredLength);
185
186    /* *
187     * @brief Gets the file descriptor for memory mapping.
188     *
189     * @param deviceId ID of the device to be operated.
190     * @param fd The file descriptor obtained for memory mapping.
191     *
192     * @return <b>0</b> if the operation is successful; a negative value otherwise.
193     * @since 4.0
194     */
195    GetDeviceMemMapFd([in] unsigned long deviceId, [out] FileDescriptor fd);
196}
197