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 HdiInput
18 * @{
19 *
20 * @brief Provides APIs for the upper-layer input service.
21 *
22 * Using the APIs provided by the Input module, input service developers can implement the following functions:
23 * enabling or disabling input devices, obtaining input events, querying device information, registering callback
24 * functions, and managing the feature status.
25 *
26 * @since 3.2
27 * @version 1.0
28 */
29
30/**
31 * @file IInputInterfaces.idl
32 *
33 * @brief Provides APIs for the input service to perform the following: enabling and disabling input devices,
34 * obtaining input events, querying device information, registering callback functions, and managing the feature status.
35 *
36 * @since 3.2
37 * @version 1.0
38 */
39
40/**
41 * @brief Defines the package path of the Input module APIs.
42 *
43 * @since 3.2
44 * @version 1.0
45 */
46package ohos.hdi.input.v1_0;
47
48import ohos.hdi.input.v1_0.IInputCallback;
49import ohos.hdi.input.v1_0.InputTypes;
50
51/**
52 * @brief Provides APIs for the upper-layer input service.
53 *
54 * Using the APIs provided by the Input module, input service developers can implement the following functions:
55 * enabling or disabling input devices, obtaining input events, querying device information, registering callback
56 * functions, and managing the feature status.
57 *
58 * @since 3.2
59 * @version 1.0
60 */
61interface IInputInterfaces {
62    /**
63     * @brief Scans all online input devices.
64     *
65     * @param staArr Array for storing input device scanning information, including the device index and
66     * device type. For details, see {@link DevDesc}.
67     *
68     * @return Returns <b>0</b> if the operation is successful.
69     * @return Returns a negative value if the operation fails.
70     *
71     *
72     * @since 3.2
73     * @version 1.0
74     */
75    ScanInputDevice([out] struct DevDesc[] staArr);
76
77    /**
78     * @brief Opens a specified input device file.
79     *
80     * @param devIndex Index of the input device. The value ranges from <b>0</b> to <b>31</b>.
81     * A maximum of 32 input devices are supported.
82     *
83     * @return Returns <b>0</b> if the operation is successful.
84     * @return Returns a negative value if the operation fails.
85     *
86     * @since 3.2
87     * @version 1.0
88     */
89    OpenInputDevice([in] unsigned int devIndex);
90
91    /**
92     * @brief Closes a specified input device file.
93     *
94     * @param devIndex Index of the input device. The value ranges from <b>0</b> to <b>31</b>.
95     * A maximum of 32 input devices are supported.
96     *
97     * @return Returns <b>0</b> if the operation is successful.
98     * @return Returns a negative value if the operation fails.
99     *
100     * @since 3.2
101     * @version 1.0
102     */
103    CloseInputDevice([in] unsigned int devIndex);
104
105    /**
106     * @brief Obtains information about the input device indicated by <b>devIndex</b>.
107     *
108     * @param devIndex Index of the input device. The value ranges from <b>0</b> to <b>31</b>.
109     * A maximum of 32 input devices are supported.
110     * @param devInfo Input device information. For details, see {@link DeviceInfo}.
111     *
112     * @return Returns <b>0</b> if the operation is successful.
113     * @return Returns a negative value if the operation fails.
114     *
115     * @since 3.2
116     * @version 1.0
117     */
118    GetInputDevice([in] unsigned int devIndex, [out] struct DeviceInfo devInfo);
119
120    /**
121     * @brief Obtains information about all input devices in the device list.
122     *
123     * @param devNum Total number of registered input devices.
124     * @param devList Information about all devices in the device list. For details, see {@link DeviceInfo}.
125     * @param size Number of elements in the <b>devList</b> array.
126     *
127     * @return Returns <b>0</b> if the operation is successful.
128     * @return Returns a negative value if the operation fails.
129     *
130     * @since 3.2
131     * @version 1.0
132     */
133    GetInputDeviceList([out] unsigned int devNum, [out] struct DeviceInfo[] devList, [in]unsigned int size);
134
135    /**
136     * @brief Sets the power status of the input device indicated by <b>devIndex</b>.
137     *
138     * When the OS enters the sleep mode or wakes up from the sleep mode, the input service or the power management
139     * module can set the power status of the input device, so that the driver IC of the device enters the
140     * corresponding state.
141     *
142     * @param devIndex Index of the input device. The value ranges from <b>0</b> to <b>31</b>.
143     * A maximum of 32 input devices are supported.
144     * @param status Power status. For example, <b>0</b> indicates the wakeup state, <b>1</b> indicates the suspend
145     * state, <b>2</b> indicates the low power state, and <b>3</b> indicates an unknown power state.
146     *
147     * @return Returns <b>0</b> if the operation is successful.
148     * @return Returns a negative value if the operation fails.
149     *
150     * @since 3.2
151     * @version 1.0
152     */
153    SetPowerStatus([in] unsigned int devIndex, [in] unsigned int status);
154
155    /**
156     * @brief Obtains the power status of the input device indicated by <b>devIndex</b>.
157     *
158     * When the OS enters the sleep mode or wakes up from the sleep mode, the input service or the power management
159     * module can obtain the power status of the input device.
160     *
161     * @param devIndex Index of the input device. The value ranges from <b>0</b> to <b>31</b>.
162     * A maximum of 32 input devices are supported.
163     * @param status Power status. For example, <b>0</b> indicates the wakeup state, <b>1</b> indicates the suspend
164     * state, <b>2</b> indicates the low power state, and <b>3</b> indicates an unknown power state.
165     *
166     * @return Returns <b>0</b> if the operation is successful.
167     * @return Returns a negative value if the operation fails.
168     *
169     * @since 3.2
170     * @version 1.0
171     */
172    GetPowerStatus([in] unsigned int devIndex, [out] unsigned int status);
173
174    /**
175     * @brief Obtains the type of the input device indicated by <b>devIndex</b>.
176     *
177     * @param devIndex Index of the input device. The value ranges from <b>0</b> to <b>31</b>.
178     * A maximum of 32 input devices are supported.
179     * @param deviceType Device type. For example, <b>0</b> indicates a touchscreen, <b>1</b> indicates a physical key,
180     * <b>2</b> indicates a keyboard, and <b>3</b> indicates a mouse.
181     *
182     * @return Returns <b>0</b> if the operation is successful.
183     * @return Returns a negative value if the operation fails.
184     *
185     * @since 3.2
186     * @version 1.0
187     */
188    GetDeviceType([in] unsigned int devIndex, [out] unsigned int deviceType);
189
190    /**
191     * @brief Obtains chip information of the input device indicated by <b>devIndex</b>.
192     *
193     * A product is usually equipped with modules and driver ICs provided by multiple vendors. The input service can
194     * call this function to obtain the chip information if needed.
195     *
196     * @param devIndex Index of the input device. The value ranges from <b>0</b> to <b>31</b>.
197     * A maximum of 32 input devices are supported.
198     * @param chipInfo Chip information.
199     *
200     * @return Returns <b>0</b> if the operation is successful.
201     * @return Returns a negative value if the operation fails.
202     *
203     * @since 3.2
204     * @version 1.0
205     */
206    GetChipInfo([in] unsigned int devIndex, [out] String chipInfo);
207
208    /**
209     * @brief Obtains the module vendor name of the input device indicated by <b>devIndex</b>.
210     *
211     * @param devIndex Index of the input device. The value ranges from <b>0</b> to <b>31</b>.
212     * A maximum of 32 input devices are supported.
213     * @param vendorName Module vendor name.
214     *
215     * @return Returns <b>0</b> if the operation is successful.
216     * @return Returns a negative value if the operation fails.
217     *
218     * @since 3.2
219     * @version 1.0
220     */
221    GetVendorName([in] unsigned int devIndex, [out] String vendorName);
222
223    /**
224     * @brief Obtains the driver chip name of the input device indicated by <b>devIndex</b>.
225     *
226     * @param devIndex Index of the input device. The value ranges from <b>0</b> to <b>31</b>.
227     * A maximum of 32 input devices are supported.
228     * @param chipName Driver chip name.
229     *
230     * @return Returns <b>0</b> if the operation is successful.
231     * @return Returns a negative value if the operation fails.
232     *
233     * @since 3.2
234     * @version 1.0
235     */
236    GetChipName([in] unsigned int devIndex, [out] String chipName);
237
238    /**
239     * @brief Sets the gesture mode of the input device indicated by <b>devIndex</b>.
240     *
241     * The input service can use this function to enable or disable the gesture mode
242     * by setting <b>EnableBit</b> of the gesture mode.
243     *
244     * @param devIndex Index of the input device. The value ranges from <b>0</b> to <b>31</b>.
245     * A maximum of 32 input devices are supported.
246     * @param gestureMode Gesture mode.
247     *
248     * @return Returns <b>0</b> if the operation is successful.
249     * @return Returns a negative value if the operation fails.
250     *
251     * @since 3.2
252     * @version 1.0
253     */
254    SetGestureMode([in] unsigned int devIndex, [in] unsigned int gestureMode);
255
256    /**
257     * @brief Conducts a capacitance self-test.
258     *
259     * The capacitance self-test items are defined by the component vendor,
260     * such as the tests on the RawData, short circuit, open circuit, interference, and row/column difference.
261     *
262     * @param devIndex Index of the input device. The value ranges from <b>0</b> to <b>31</b>.
263     * A maximum of 32 input devices are supported.
264     * @param testType Capacitance test type. For example, <b>0</b> indicates the basic capacitance test,
265     * <b>1</b> indicates the full capacitance self-check test, <b>2</b> indicates the MMI capacitance test,
266     * and <b>3</b> indicates the aging capacitance test.
267     * @param result Capacitance test result. The value is <b>SUCC</b> for a successful operation and is an error code
268     * for a failed operation.
269     * @param length Length of the capacitance test result.
270     *
271     * @return Returns <b>0</b> if the operation is successful.
272     * @return Returns a negative value if the operation fails.
273     *
274     * @since 3.2
275     * @version 1.0
276     */
277    RunCapacitanceTest([in] unsigned int devIndex, [in] unsigned int testType, [out] String result, [in] unsigned int length);
278
279    /**
280     * @brief Executes the extra command.
281     *
282     * @param devIndex Index of the input device. The value ranges from <b>0</b> to <b>31</b>.
283     * A maximum of 32 input devices are supported.
284     * @param cmd Extra command data packet, including the command codes and parameters.
285     * For details, see {@link ExtraCmd}.
286     *
287     * @return Returns <b>0</b> if the operation is successful.
288     * @return Returns a negative value if the operation fails.
289     *
290     * @since 3.2
291     * @version 1.0
292     */
293    RunExtraCommand([in] unsigned int devIndex, [in] struct ExtraCmd cmd);
294
295    /**
296     * @brief Registers an input event callback to the HDI for the input device indicated by <b>devIndex</b>.
297     *
298     * After this callback is successfully registered, the driver can report the input event data to the input service
299     * through this callback.
300     *
301     * @param devIndex Index of the input device. The value ranges from <b>0</b> to <b>31</b>.
302     * A maximum of 32 input devices are supported.
303     * @param eventPkgCallback Input event callback.
304     *
305     * @return Returns <b>0</b> if the operation is successful.
306     * @return Returns a negative value if the operation fails.
307     *
308     * @since 3.2
309     * @version 1.0
310     */
311    RegisterReportCallback([in] unsigned int devIndex, [in] IInputCallback eventPkgCallback);
312
313    /**
314     * @brief Unregisters the input event callback of the input device indicated by <b>devIndex</b>.
315     *
316     * @param devIndex Index of the input device. The value ranges from <b>0</b> to <b>31</b>.
317     * A maximum of 32 input devices are supported.
318     *
319     * @return Returns <b>0</b> if the operation is successful.
320     * @return Returns a negative value if the operation fails.
321     *
322     * @since 3.2
323     * @version 1.0
324     */
325    UnregisterReportCallback([in] unsigned int devIndex);
326
327    /**
328     * @brief Registers a hot plug callback to the HDI for input devices.
329     *
330     * All input devices can use this callback to report hot plug events.
331     *
332     * @param hotPlugCallback Hot plug event callback.
333     *
334     * @return Returns <b>0</b> if the operation is successful.
335     * @return Returns a negative value if the operation fails.
336     *
337     * @since 3.2
338     * @version 1.0
339     */
340    RegisterHotPlugCallback([in] IInputCallback hotPlugCallback);
341
342    /**
343     * @brief Unregisters the hot plug callback of input devices.
344     *
345     * @return Returns <b>0</b> if the operation is successful.
346     * @return Returns a negative value if the operation fails.
347     *
348     * @since 3.2
349     * @version 1.0
350     */
351    UnregisterHotPlugCallback();
352}
353/** @} */
354