xref: /drivers/peripheral/input/README_zh.md (revision 094332d3) 
1# Input<a name="ZH-CN_TOPIC_0000001124789109"></a>
2
3-   [简介](#section11660541593)
4-   [目录](#section161941989596)
5    -   [接口说明](#section1551164914237)
6    -   [使用说明](#section129654513264)
7    -   [用例说明](#section129654513265)
8
9-   [相关仓](#section1371113476307)
10
11## 简介<a name="section11660541593"></a>
12
13该仓下主要包含Input模块HDI（Hardware Driver Interface）接口定义及其实现，对上层输入服务提供操作input设备的驱动能力接口，HDI接口主要包括如下三大类：
14
15-   InputManager：管理输入设备，包括输入设备的打开、关闭、设备列表信息获取等；
16-   InputReporter：负责输入事件的上报，包括注册、注销数据上报回调函数等；
17-   InputController：提供input设备的业务控制接口，包括获取器件信息及设备类型、设置电源状态等。
18
19**图 1**  INPUT模块HDI接口层框架图<a name="fig9489629122818"></a>  
20![](figures/hdi-architecture-of-the-input-module.png "hdi-architecture-of-the-input-module")
21
22## 目录<a name="section161941989596"></a>
23
24该仓下源代码目录结构如下所示
25
26```
27/drivers/peripheral/input
28├── hal                # input模块的hal层代码
29│   └── include       # input模块hal层内部的头文件
30│   └── src           # input模块hal层代码的具体实现
31├── interfaces         # input模块对上层服务提供的驱动能力接口
32│   └── include       # input模块对外提供的接口定义
33├── test               # input模块的测试代码
34│   └── unittest      # input模块的单元测试代码
35```
36
37### 接口说明<a name="section1551164914237"></a>
38
39Input驱动提供给系统服务Input Service可直接调用的驱动能力接口，按照属性分类三类：input设备管理模块、input数据上报模块、input业务控制模块，例如提供输入设备打开及关闭接口、注册设备监听的回调接口、设备信息查询接口、电源状态控制接口等。
40
41提供的部分接口说明如[表1 Input HDI接口列表](#table1513255710559)所示：
42
43**表 1**  Input HDI接口列表
44
45<a name="table1513255710559"></a>
46<table><thead align="left"><tr id="row171321857155517"><th class="cellrowborder" align="center" valign="top" width="12.031203120312032%" id="mcps1.2.4.1.1"><p id="p6132957115511"><a name="p6132957115511"></a><a name="p6132957115511"></a>头文件</p>
47</th>
48<th class="cellrowborder" align="center" valign="top" width="66.006600660066%" id="mcps1.2.4.1.2"><p id="p14132125715552"><a name="p14132125715552"></a><a name="p14132125715552"></a>接口名称</p>
49</th>
50<th class="cellrowborder" align="center" valign="top" width="21.96219621962196%" id="mcps1.2.4.1.3"><p id="p18132205755516"><a name="p18132205755516"></a><a name="p18132205755516"></a>功能描述</p>
51</th>
52</tr>
53</thead>
54<tbody><tr id="row13132357165514"><td class="cellrowborder" rowspan="4" align="left" valign="top" width="12.031203120312032%" headers="mcps1.2.4.1.1 "><p id="p15674038913"><a name="p15674038913"></a><a name="p15674038913"></a></p>
55<p id="p825185015460"><a name="p825185015460"></a><a name="p825185015460"></a>input_manager.h</p>
56<p id="p2133757135510"><a name="p2133757135510"></a><a name="p2133757135510"></a></p>
57</td>
58<td class="cellrowborder" valign="top" width="66.006600660066%" headers="mcps1.2.4.1.2 "><p id="p11132857135517"><a name="p11132857135517"></a><a name="p11132857135517"></a>int32_t (*OpenInputDevice)(uint32_t devIndex);</p>
59</td>
60<td class="cellrowborder" align="center" valign="top" width="21.96219621962196%" headers="mcps1.2.4.1.3 "><p id="p8233134675314"><a name="p8233134675314"></a><a name="p8233134675314"></a>打开input设备</p>
61</td>
62</tr>
63<tr id="row9132135715515"><td class="cellrowborder" valign="top" headers="mcps1.2.4.1.1 "><p id="p106067813482"><a name="p106067813482"></a><a name="p106067813482"></a>int32_t (*CloseInputDevice)(uint32_t devIndex);</p>
64</td>
65<td class="cellrowborder" align="center" valign="top" headers="mcps1.2.4.1.2 "><p id="p8233144617532"><a name="p8233144617532"></a><a name="p8233144617532"></a>关闭input设备</p>
66</td>
67</tr>
68<tr id="row2973185044814"><td class="cellrowborder" valign="top" headers="mcps1.2.4.1.1 "><p id="p1974125024812"><a name="p1974125024812"></a><a name="p1974125024812"></a>int32_t (*GetInputDevice)(uint32_t devIndex, DeviceInfo **devInfo);</p>
69</td>
70<td class="cellrowborder" align="center" valign="top" headers="mcps1.2.4.1.2 "><p id="p152331046155310"><a name="p152331046155310"></a><a name="p152331046155310"></a>获取指定ID的设备信息</p>
71</td>
72</tr>
73<tr id="row171330575555"><td class="cellrowborder" valign="top" headers="mcps1.2.4.1.1 "><p id="p913315573557"><a name="p913315573557"></a><a name="p913315573557"></a>int32_t (*GetInputDeviceList)(uint32_t *devNum, DeviceInfo **devList, uint32_t size);</p>
74</td>
75<td class="cellrowborder" align="center" valign="top" headers="mcps1.2.4.1.2 "><p id="p1523319466539"><a name="p1523319466539"></a><a name="p1523319466539"></a>获取所有设备列表信息</p>
76</td>
77</tr>
78<tr id="row1513316577554"><td class="cellrowborder" rowspan="3" align="left" valign="top" width="12.031203120312032%" headers="mcps1.2.4.1.1 "><p id="p14171441118"><a name="p14171441118"></a><a name="p14171441118"></a></p>
79<p id="p57063567463"><a name="p57063567463"></a><a name="p57063567463"></a>input_reporter.h</p>
80</td>
81<td class="cellrowborder" valign="top" width="66.006600660066%" headers="mcps1.2.4.1.2 "><p id="p14794193010499"><a name="p14794193010499"></a><a name="p14794193010499"></a>int32_t (*RegisterReportCallback)(uint32_t devIndex, InputReportEventCb *callback);</p>
82</td>
83<td class="cellrowborder" align="center" valign="top" width="21.96219621962196%" headers="mcps1.2.4.1.3 "><p id="p72331046145316"><a name="p72331046145316"></a><a name="p72331046145316"></a>注册input设备的回调</p>
84</td>
85</tr>
86<tr id="row171331657185514"><td class="cellrowborder" valign="top" headers="mcps1.2.4.1.1 "><p id="p123921240124910"><a name="p123921240124910"></a><a name="p123921240124910"></a>int32_t (*UnregisterReportCallback)(uint32_t devIndex);</p>
87</td>
88<td class="cellrowborder" align="center" valign="top" headers="mcps1.2.4.1.2 "><p id="p19233174675311"><a name="p19233174675311"></a><a name="p19233174675311"></a>注销input设备的回调</p>
89</td>
90</tr>
91<tr id="row41331557165518"><td class="cellrowborder" valign="top" headers="mcps1.2.4.1.1 "><p id="p11499124705012"><a name="p11499124705012"></a><a name="p11499124705012"></a>void (*ReportEventPkgCallback)(const EventPackage **pkgs, uint32_t count);</p>
92</td>
93<td class="cellrowborder" align="center" valign="top" headers="mcps1.2.4.1.2 "><p id="p52331246135315"><a name="p52331246135315"></a><a name="p52331246135315"></a>上报数据的回调函数</p>
94</td>
95</tr>
96<tr id="row1452521025813"><td class="cellrowborder" rowspan="9" align="left" valign="top" width="12.031203120312032%" headers="mcps1.2.4.1.1 "><p id="p1285144710118"><a name="p1285144710118"></a><a name="p1285144710118"></a></p>
97<p id="p854114711117"><a name="p854114711117"></a><a name="p854114711117"></a></p>
98<p id="p15741647517"><a name="p15741647517"></a><a name="p15741647517"></a></p>
99<p id="p7909447418"><a name="p7909447418"></a><a name="p7909447418"></a></p>
100<p id="p12525910165811"><a name="p12525910165811"></a><a name="p12525910165811"></a>input_controller.h</p>
101<p id="p942322013262"><a name="p942322013262"></a><a name="p942322013262"></a></p>
102<p id="p1040515339526"><a name="p1040515339526"></a><a name="p1040515339526"></a></p>
103<p id="p19405533115216"><a name="p19405533115216"></a><a name="p19405533115216"></a></p>
104</td>
105<td class="cellrowborder" valign="top" width="66.006600660066%" headers="mcps1.2.4.1.2 "><p id="p14402132815113"><a name="p14402132815113"></a><a name="p14402132815113"></a>int32_t (*SetPowerStatus)(uint32_t devIndex, uint32_t status);</p>
106</td>
107<td class="cellrowborder" align="center" valign="top" width="21.96219621962196%" headers="mcps1.2.4.1.3 "><p id="p1510016065413"><a name="p1510016065413"></a><a name="p1510016065413"></a>设置电源状态</p>
108</td>
109</tr>
110<tr id="row172902161193"><td class="cellrowborder" valign="top" headers="mcps1.2.4.1.1 "><p id="p2062643555111"><a name="p2062643555111"></a><a name="p2062643555111"></a>int32_t (*GetPowerStatus)(uint32_t devIndex, uint32_t *status);</p>
111</td>
112<td class="cellrowborder" align="center" valign="top" headers="mcps1.2.4.1.2 "><p id="p1323394615539"><a name="p1323394615539"></a><a name="p1323394615539"></a>获取电源状态</p>
113</td>
114</tr>
115<tr id="row1948179195"><td class="cellrowborder" valign="top" headers="mcps1.2.4.1.1 "><p id="p8207194414510"><a name="p8207194414510"></a><a name="p8207194414510"></a>int32_t (*GetDeviceType)(uint32_t devIndex, uint32_t *deviceType);</p>
116</td>
117<td class="cellrowborder" align="center" valign="top" headers="mcps1.2.4.1.2 "><p id="p18233154655317"><a name="p18233154655317"></a><a name="p18233154655317"></a>获取设备类型</p>
118</td>
119</tr>
120<tr id="row1331121813197"><td class="cellrowborder" valign="top" headers="mcps1.2.4.1.1 "><p id="p1321125217514"><a name="p1321125217514"></a><a name="p1321125217514"></a>int32_t (*GetChipInfo)(uint32_t devIndex, char *chipInfo, uint32_t length);</p>
121</td>
122<td class="cellrowborder" align="center" valign="top" headers="mcps1.2.4.1.2 "><p id="p14233104614536"><a name="p14233104614536"></a><a name="p14233104614536"></a>获取器件编码信息</p>
123</td>
124</tr>
125<tr id="row1393181951920"><td class="cellrowborder" valign="top" headers="mcps1.2.4.1.1 "><p id="p79410191191"><a name="p79410191191"></a><a name="p79410191191"></a>int32_t (*GetVendorName)(uint32_t devIndex, char *vendorName, uint32_t length);</p>
126</td>
127<td class="cellrowborder" align="center" valign="top" headers="mcps1.2.4.1.2 "><p id="p7233124695317"><a name="p7233124695317"></a><a name="p7233124695317"></a>获取模组厂商名</p>
128</td>
129</tr>
130<tr id="row8960121911198"><td class="cellrowborder" valign="top" headers="mcps1.2.4.1.1 "><p id="p17712110185218"><a name="p17712110185218"></a><a name="p17712110185218"></a>int32_t (*GetChipName)(uint32_t devIndex, char *chipName, uint32_t length);</p>
131</td>
132<td class="cellrowborder" align="center" valign="top" headers="mcps1.2.4.1.2 "><p id="p923316468539"><a name="p923316468539"></a><a name="p923316468539"></a>获取芯片厂商名</p>
133</td>
134</tr>
135<tr id="row10812112081919"><td class="cellrowborder" valign="top" headers="mcps1.2.4.1.1 "><p id="p20738171735219"><a name="p20738171735219"></a><a name="p20738171735219"></a>int32_t (*SetGestureMode)(uint32_t devIndex, uint32_t gestureMode);</p>
136</td>
137<td class="cellrowborder" align="center" valign="top" headers="mcps1.2.4.1.2 "><p id="p5233546175310"><a name="p5233546175310"></a><a name="p5233546175310"></a>设置手势模式</p>
138</td>
139</tr>
140<tr id="row12422102092613"><td class="cellrowborder" valign="top" headers="mcps1.2.4.1.1 "><p id="p56701925155215"><a name="p56701925155215"></a><a name="p56701925155215"></a>int32_t (*RunCapacitanceTest)(uint32_t devIndex, uint32_t testType, char *result, uint32_t length);</p>
141</td>
142<td class="cellrowborder" align="center" valign="top" headers="mcps1.2.4.1.2 "><p id="p13234346125310"><a name="p13234346125310"></a><a name="p13234346125310"></a>执行容值自检测试</p>
143</td>
144</tr>
145<tr id="row124041233155211"><td class="cellrowborder" valign="top" headers="mcps1.2.4.1.1 "><p id="p16405113375215"><a name="p16405113375215"></a><a name="p16405113375215"></a>int32_t (*RunExtraCommand)(uint32_t devIndex, InputExtraCmd *cmd);</p>
146</td>
147<td class="cellrowborder" align="center" valign="top" headers="mcps1.2.4.1.2 "><p id="p192341246185314"><a name="p192341246185314"></a><a name="p192341246185314"></a>执行拓展指令</p>
148</td>
149</tr>
150</tbody>
151</table>
152
153### 使用说明<a name="section129654513264"></a>
154
155该仓核心功能是提供Input驱动能力接口供上层输入系统服务调用，提供的驱动能力接口统一归属为HDI接口层。
156
157通过如下简要示例代码说明Input HDI接口的使用：
158
159```
160#include "input_manager.h"
161#define DEV_INDEX 1
162
163IInputInterface *g_inputInterface;
164InputReportEventCb g_callback;
165
166/* 定义数据上报的回调函数 */
167static void ReportEventPkgCallback(const EventPackage **pkgs, uint32_t count)
168{
169    if (pkgs == NULL || count > MAX_PKG_NUM) {
170        return;
171    }
172    for (uint32_t i = 0; i < count; i++) {
173        HDF_LOGI("%s: pkgs[%d] = 0x%x, 0x%x, %d", __func__, i, pkgs[i]->type, pkgs[i]->code, pkgs[i]->value);
174    }
175}
176
177int InputServiceSample(void)
178{
179    uint32_t devType = INIT_DEFAULT_VALUE;
180
181    /* 获取Input驱动能力接口 */
182    int ret = GetInputInterface(&g_inputInterface);
183    if (ret != INPUT_SUCCESS) {
184        HDF_LOGE("%s: get input interfaces failed, ret = %d", __func__, ret);
185        return ret;
186    }
187
188    INPUT_CHECK_NULL_POINTER(g_inputInterface, INPUT_NULL_PTR);
189    INPUT_CHECK_NULL_POINTER(g_inputInterface->iInputManager, INPUT_NULL_PTR);
190    /* 打开特定的input设备 */
191    ret = g_inputInterface->iInputManager->OpenInputDevice(DEV_INDEX);
192    if (ret) {
193        HDF_LOGE("%s: open input device failed, ret = %d", __func__, ret);
194 	return ret;
195    }
196
197    INPUT_CHECK_NULL_POINTER(g_inputInterface->iInputController, INPUT_NULL_PTR);
198    /* 获取对应input设备的类型 */
199    ret = g_inputInterface->iInputController->GetDeviceType(DEV_INDEX, &devType);
200    if (ret) {
201        HDF_LOGE("%s: get device type failed, ret: %d", __FUNCTION__, ret);
202        return ret;
203    }
204    HDF_LOGI("%s: device1's type is %u\n", __FUNCTION__, devType);
205
206    /* 给特定的input设备注册数据上报回调函数 */
207    g_callback.ReportEventPkgCallback = ReportEventPkgCallback;
208    INPUT_CHECK_NULL_POINTER(g_inputInterface->iInputReporter, INPUT_NULL_PTR);
209    ret  = g_inputInterface->iInputReporter->RegisterReportCallback(DEV_INDEX, &g_callback);
210    if (ret) {
211        HDF_LOGE("%s: register callback failed, ret: %d", __FUNCTION__, ret);
212	return ret;
213    }
214    HDF_LOGI("%s: wait 10s for testing, pls touch the panel now", __FUNCTION__);
215    OsalMSleep(KEEP_ALIVE_TIME_MS);
216
217    /* 注销特定input设备上的回调函数 */
218    ret  = g_inputInterface->iInputReporter->UnregisterReportCallback(DEV_INDEX);
219    if (ret) {
220        HDF_LOGE("%s: unregister callback failed, ret: %d", __FUNCTION__, ret);
221        return ret;
222    }
223
224    /* 关闭特定的input设备 */
225    ret = g_inputInterface->iInputManager->CloseInputDevice(DEV_INDEX);
226    if (ret) {
227        HDF_LOGE("%s: close device failed, ret: %d", __FUNCTION__, ret);
228	return ret;
229    }
230    return 0;
231}
232```
233
234### 用例说明<a name="section129654513265"></a>
235
236执行input相关用例，需要提前插入一个hid设备。
237
238相关用例说明：
239
240* drivers/peripheral/input/test中的用例
241
242* test/xts/hats/hdf/input中的用例
243
244## 相关仓<a name="section1371113476307"></a>
245
246[驱动子系统](https://gitee.com/openharmony/docs/blob/master/zh-cn/readme/%E9%A9%B1%E5%8A%A8%E5%AD%90%E7%B3%BB%E7%BB%9F.md)
247
248[drivers\_framework](https://gitee.com/openharmony/drivers_framework/blob/master/README_zh.md)
249
250[drivers\_adapter](https://gitee.com/openharmony/drivers_adapter/blob/master/README_zh.md)
251
252[drivers\_adapter\_khdf\_linux](https://gitee.com/openharmony/drivers_adapter_khdf_linux/blob/master/README_zh.md)
253
254[drivers\_peripheral](https://gitee.com/openharmony/drivers_peripheral)
255
256