1/*
2 * Copyright (c) 2021-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 Input
18 * @{
19 *
20 * @brief Provides driver interfaces for the input service.
21 *
22 * These driver interfaces can be used to open and close input device files, get input events, query device information,
23 * register callback functions, and control the feature status.
24 *
25 * @since 1.0
26 * @version 1.0
27 */
28
29/**
30 * @file input_manager.h
31 *
32 * @brief Declares the driver interfaces for managing input devices.
33 *
34 * @since 1.0
35 * @version 1.0
36 */
37
38#ifndef INPUT_MANAGER_H
39#define INPUT_MANAGER_H
40
41#include "input_controller.h"
42#include "input_reporter.h"
43#include "input_type.h"
44
45#ifdef __cplusplus
46extern "C" {
47#endif
48
49/**
50 * @brief Provides interfaces for managing input devices.
51 *
52 * The interfaces can be used to perform basic operations on the input devices, such as scanning online devices,
53 * opening and closing the device files, querying information about a specified input device, and obtaining information
54 * about all input devices in the device list.
55 */
56typedef struct {
57    /**
58     * @brief Scans all online input devices.
59     *
60     * @param staArr Indicates the pointer to the array storing information about the scanned input devices,
61     * including the device index and device type.
62     * @param arrLen Indicates the length of the array.
63     * @return Returns <b>INPUT SUCCESS</b> if the operation is successful; returns an error code defined in
64     * {@link RetStatus} otherwise.
65     * @since 1.0
66     * @version 1.0
67     */
68    int32_t (*ScanInputDevice)(InputDevDesc *staArr, uint32_t arrLen);
69
70    /**
71     * @brief Opens a specified input device file.
72     *
73     * @param devIndex Indicates the index of an input device. A maximum of 32 input devices are supported.
74     * The value ranges from 0 to 31, and value <b>0</b> represents the first input device.
75     * @return Returns <b>INPUT SUCCESS</b> if the operation is successful; returns an error code defined in
76     * {@link RetStatus} otherwise.
77     * @since 1.0
78     * @version 1.0
79     */
80    int32_t (*OpenInputDevice)(uint32_t devIndex);
81
82    /**
83     * @brief Closes a specified input device file.
84     *
85     * @param devIndex Indicates the index of an input device. A maximum of 32 input devices are supported.
86     * The value ranges from 0 to 31, and value <b>0</b> represents the first input device.
87     * @return Returns <b>INPUT SUCCESS</b> if the operation is successful; returns an error code defined in
88     * {@link RetStatus} otherwise.
89     * @since 1.0
90     * @version 1.0
91     */
92    int32_t (*CloseInputDevice)(uint32_t devIndex);
93
94    /**
95     * @brief Gets information about a specified input device.
96     *
97     * @param devIndex Indicates the index of an input device. A maximum of 32 input devices are supported.
98     * The value ranges from 0 to 31, and value <b>0</b> represents the first input device.
99     * @param devInfo Indicates the double pointer to information about the specified device.
100     * For details, see {@link DeviceInfo}.
101     * @return Returns <b>INPUT SUCCESS</b> if the operation is successful; returns an error code defined in
102     * {@link RetStatus} otherwise.
103     * @since 1.0
104     * @version 1.0
105     */
106    int32_t (*GetInputDevice)(uint32_t devIndex, InputDeviceInfo **devInfo);
107
108    /**
109     * @brief Gets information about all input devices in the device list.
110     *
111     * @param devNum Indicates the pointer to the total number of input devices which have been registered.
112     * @param devList Indicates the double pointer to information about all devices in the device list.
113     * For details, see {@link DeviceInfo}.
114     * @param size Indicates the number of elements in the <b>devList</b> array.
115     * @return Returns <b>INPUT SUCCESS</b> if the operation is successful; returns an error code defined in
116     * {@link RetStatus} otherwise.
117     * @since 1.0
118     * @version 1.0
119     */
120    int32_t (*GetInputDeviceList)(uint32_t *devNum, InputDeviceInfo **devList, uint32_t size);
121} InputManager;
122
123/**
124 * @brief Defines interfaces for providing driver capabilities of input devices.
125 */
126typedef struct {
127    InputManager *iInputManager;        /**< Device management interface for input devices */
128    InputController *iInputController;  /**< Service control interface for input devices */
129    InputReporter *iInputReporter;      /**< Data reporting interface for input devices */
130} IInputInterface;
131
132/**
133 * @brief Gets all interfaces for performing operations on input devices.
134 *
135 * @param interface Indicates the double pointer to the interfaces for performing operations on input devices.
136 * @return Returns <b>INPUT SUCCESS</b> if the operation is successful; returns an error code defined in
137 * {@link RetStatus} otherwise.
138 * @since 1.0
139 * @version 1.0
140 */
141int32_t GetInputInterface(IInputInterface **interface);
142
143/**
144 * @brief Releases all interfaces for performing operations on input devices.
145 *
146 * @param inputInterface Indicates the pointer to the interfaces for performing operations on input devices.
147 * @return Returns <b>INPUT SUCCESS</b> if the operation is successful; returns an error code defined in
148 * {@link RetStatus} otherwise.
149 * @since 1.0
150 * @version 1.0
151 */
152void ReleaseInputInterface(IInputInterface **inputInterface);
153
154#ifdef __cplusplus
155}
156#endif
157#endif
158/** @} */
159