1<!-- HTML header for doxygen 1.8.8--> 2<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> 3<html xmlns="http://www.w3.org/1999/xhtml"> 4 <head> 5 <meta http-equiv="X-UA-Compatible" content="IE=edge"> 6 <!-- For Mobile Devices --> 7 <meta name="viewport" content="width=device-width, initial-scale=1"> 8 <meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/> 9 <meta name="generator" content="Doxygen 1.9.1"/> 10 <script type="text/javascript" src="https://code.jquery.com/jquery-2.1.1.min.js"></script> 11 <title>libevdev: Event handling</title> 12 <!--<link href="tabs.css" rel="stylesheet" type="text/css"/>--> 13 <script type="text/javascript" src="dynsections.js"></script> 14 <link href="search/search.css" rel="stylesheet" type="text/css"/> 15<script type="text/javascript" src="search/searchdata.js"></script> 16<script type="text/javascript" src="search/search.js"></script> 17 <link href="doxygen.css" rel="stylesheet" type="text/css" /> 18 <link href="bootstrap.css" rel="stylesheet" type="text/css"/> 19<link href="customdoxygen.css" rel="stylesheet" type="text/css"/> 20<link href="libevdevdoxygen.css" rel="stylesheet" type="text/css"/> 21 <script src="https://maxcdn.bootstrapcdn.com/bootstrap/3.3.1/js/bootstrap.min.js"></script> 22 <script type="text/javascript" src="doxy-boot.js"></script> 23 </head> 24 <body> 25 <nav class="navbar navbar-default" role="navigation"> 26 <div class="container"> 27 <div class="navbar-header"> 28 <a class="navbar-brand">libevdev 1.12.1</a> 29 </div> 30 </div> 31 </nav> 32 <div id="top"><!-- do not remove this div, it is closed by doxygen! --> 33 <div class="content" id="content"> 34 <div class="container"> 35 <div class="row"> 36 <div class="col-sm-12 panel panel-default" style="padding-bottom: 15px;"> 37 <div style="margin-bottom: 15px;"> 38<!-- end header part --> 39<!-- Generated by Doxygen 1.9.1 --> 40<script type="text/javascript"> 41/* @license magnet:?xt=urn:btih:cf05388f2679ee054f2beb29a391d25f4e673ac3&dn=gpl-2.0.txt GPL-v2 */ 42var searchBox = new SearchBox("searchBox", "search",false,'Search','.html'); 43/* @license-end */ 44</script> 45<script type="text/javascript" src="menudata.js"></script> 46<script type="text/javascript" src="menu.js"></script> 47<script type="text/javascript"> 48/* @license magnet:?xt=urn:btih:cf05388f2679ee054f2beb29a391d25f4e673ac3&dn=gpl-2.0.txt GPL-v2 */ 49$(function() { 50 initMenu('',true,false,'search.php','Search'); 51 $(document).ready(function() { init_search(); }); 52}); 53/* @license-end */</script> 54<div id="main-nav"></div> 55</div><!-- top --> 56<!-- window showing the filter options --> 57<div id="MSearchSelectWindow" 58 onmouseover="return searchBox.OnSearchSelectShow()" 59 onmouseout="return searchBox.OnSearchSelectHide()" 60 onkeydown="return searchBox.OnSearchSelectKey(event)"> 61</div> 62 63<!-- iframe showing the search results (closed by default) --> 64<div id="MSearchResultsWindow"> 65<iframe src="javascript:void(0)" frameborder="0" 66 name="MSearchResults" id="MSearchResults"> 67</iframe> 68</div> 69 70<div class="header"> 71 <div class="summary"> 72<a href="#enum-members">Enumerations</a> | 73<a href="#func-members">Functions</a> </div> 74 <div class="headertitle"> 75<div class="title">Event handling</div> </div> 76</div><!--header--> 77<div class="contents"> 78 79<p>Functions to handle events and fetch the current state of the event. 80<a href="#details">More...</a></p> 81<table class="memberdecls"> 82<tr class="heading"><td colspan="2"><h2 class="groupheader"><a name="enum-members"></a> 83Enumerations</h2></td></tr> 84<tr class="memitem:ga56c288d9f2e4c1632986c4e218c494e9"><td class="memItemLeft" align="right" valign="top">enum  </td><td class="memItemRight" valign="bottom"><a class="el" href="group__events.html#ga56c288d9f2e4c1632986c4e218c494e9">libevdev_read_flag</a> { <a class="el" href="group__events.html#gga56c288d9f2e4c1632986c4e218c494e9a1f13a19641d6dafcf01a86a6389800f8">LIBEVDEV_READ_FLAG_SYNC</a> 85, <a class="el" href="group__events.html#gga56c288d9f2e4c1632986c4e218c494e9ac0d6ee19551eecf76f1ede4f36252418">LIBEVDEV_READ_FLAG_NORMAL</a> 86, <a class="el" href="group__events.html#gga56c288d9f2e4c1632986c4e218c494e9a5198e5c9cc98b75f73f61b104d6a674c">LIBEVDEV_READ_FLAG_FORCE_SYNC</a> 87, <a class="el" href="group__events.html#gga56c288d9f2e4c1632986c4e218c494e9a0a348d44362a7e515b40a4ed4d528e19">LIBEVDEV_READ_FLAG_BLOCKING</a> 88 }</td></tr> 89<tr class="separator:ga56c288d9f2e4c1632986c4e218c494e9"><td class="memSeparator" colspan="2"> </td></tr> 90<tr class="memitem:ga4a96221b3c7f54dfb86035d952154e3a"><td class="memItemLeft" align="right" valign="top">enum  </td><td class="memItemRight" valign="bottom"><a class="el" href="group__events.html#ga4a96221b3c7f54dfb86035d952154e3a">libevdev_read_status</a> { <a class="el" href="group__events.html#gga4a96221b3c7f54dfb86035d952154e3aab053221fc1c9630eee7111b75aa0aec7">LIBEVDEV_READ_STATUS_SUCCESS</a> 91, <a class="el" href="group__events.html#gga4a96221b3c7f54dfb86035d952154e3aa8d70b14a38204fde4ad433023baa545a">LIBEVDEV_READ_STATUS_SYNC</a> 92 }</td></tr> 93<tr class="separator:ga4a96221b3c7f54dfb86035d952154e3a"><td class="memSeparator" colspan="2"> </td></tr> 94</table><table class="memberdecls"> 95<tr class="heading"><td colspan="2"><h2 class="groupheader"><a name="func-members"></a> 96Functions</h2></td></tr> 97<tr class="memitem:gabb96c864e836c0b98788f4ab771c3a76"><td class="memItemLeft" align="right" valign="top">int </td><td class="memItemRight" valign="bottom"><a class="el" href="group__events.html#gabb96c864e836c0b98788f4ab771c3a76">libevdev_next_event</a> (struct libevdev *dev, unsigned int flags, struct input_event *ev)</td></tr> 98<tr class="memdesc:gabb96c864e836c0b98788f4ab771c3a76"><td class="mdescLeft"> </td><td class="mdescRight">Get the next event from the device. <a href="group__events.html#gabb96c864e836c0b98788f4ab771c3a76">More...</a><br /></td></tr> 99<tr class="separator:gabb96c864e836c0b98788f4ab771c3a76"><td class="memSeparator" colspan="2"> </td></tr> 100<tr class="memitem:gae18fbfb59064c9c4b9d5db2d8cb23784"><td class="memItemLeft" align="right" valign="top">int </td><td class="memItemRight" valign="bottom"><a class="el" href="group__events.html#gae18fbfb59064c9c4b9d5db2d8cb23784">libevdev_has_event_pending</a> (struct libevdev *dev)</td></tr> 101<tr class="memdesc:gae18fbfb59064c9c4b9d5db2d8cb23784"><td class="mdescLeft"> </td><td class="mdescRight">Check if there are events waiting for us. <a href="group__events.html#gae18fbfb59064c9c4b9d5db2d8cb23784">More...</a><br /></td></tr> 102<tr class="separator:gae18fbfb59064c9c4b9d5db2d8cb23784"><td class="memSeparator" colspan="2"> </td></tr> 103</table> 104<a name="details" id="details"></a><h2 class="groupheader">Detailed Description</h2> 105<p>Functions to handle events and fetch the current state of the event. </p> 106<p>libevdev updates its internal state as the event is processed and forwarded to the caller. Thus, the libevdev state of the device should always be identical to the caller's state. It may however lag behind the actual state of the device. </p> 107<h2 class="groupheader">Enumeration Type Documentation</h2> 108<a id="ga56c288d9f2e4c1632986c4e218c494e9"></a> 109<h2 class="memtitle"><span class="permalink"><a href="#ga56c288d9f2e4c1632986c4e218c494e9">◆ </a></span>libevdev_read_flag</h2> 110 111<div class="memitem"> 112<div class="memproto"> 113 <table class="memname"> 114 <tr> 115 <td class="memname">enum <a class="el" href="group__events.html#ga56c288d9f2e4c1632986c4e218c494e9">libevdev_read_flag</a></td> 116 </tr> 117 </table> 118</div><div class="memdoc"> 119<table class="fieldtable"> 120<tr><th colspan="2">Enumerator</th></tr><tr><td class="fieldname"><a id="gga56c288d9f2e4c1632986c4e218c494e9a1f13a19641d6dafcf01a86a6389800f8"></a>LIBEVDEV_READ_FLAG_SYNC </td><td class="fielddoc"><p>Process data in sync mode. </p> 121</td></tr> 122<tr><td class="fieldname"><a id="gga56c288d9f2e4c1632986c4e218c494e9ac0d6ee19551eecf76f1ede4f36252418"></a>LIBEVDEV_READ_FLAG_NORMAL </td><td class="fielddoc"><p>Process data in normal mode. </p> 123</td></tr> 124<tr><td class="fieldname"><a id="gga56c288d9f2e4c1632986c4e218c494e9a5198e5c9cc98b75f73f61b104d6a674c"></a>LIBEVDEV_READ_FLAG_FORCE_SYNC </td><td class="fielddoc"><p>Pretend the next event is a SYN_DROPPED and require the caller to sync. </p> 125</td></tr> 126<tr><td class="fieldname"><a id="gga56c288d9f2e4c1632986c4e218c494e9a0a348d44362a7e515b40a4ed4d528e19"></a>LIBEVDEV_READ_FLAG_BLOCKING </td><td class="fielddoc"><p>The fd is not in O_NONBLOCK and a read may block. </p> 127</td></tr> 128</table> 129 130</div> 131</div> 132<a id="ga4a96221b3c7f54dfb86035d952154e3a"></a> 133<h2 class="memtitle"><span class="permalink"><a href="#ga4a96221b3c7f54dfb86035d952154e3a">◆ </a></span>libevdev_read_status</h2> 134 135<div class="memitem"> 136<div class="memproto"> 137 <table class="memname"> 138 <tr> 139 <td class="memname">enum <a class="el" href="group__events.html#ga4a96221b3c7f54dfb86035d952154e3a">libevdev_read_status</a></td> 140 </tr> 141 </table> 142</div><div class="memdoc"> 143<table class="fieldtable"> 144<tr><th colspan="2">Enumerator</th></tr><tr><td class="fieldname"><a id="gga4a96221b3c7f54dfb86035d952154e3aab053221fc1c9630eee7111b75aa0aec7"></a>LIBEVDEV_READ_STATUS_SUCCESS </td><td class="fielddoc"><p><a class="el" href="group__events.html#gabb96c864e836c0b98788f4ab771c3a76" title="Get the next event from the device.">libevdev_next_event()</a> has finished without an error and an event is available for processing. </p> 145<dl class="section see"><dt>See also</dt><dd><a class="el" href="group__events.html#gabb96c864e836c0b98788f4ab771c3a76" title="Get the next event from the device.">libevdev_next_event</a> </dd></dl> 146</td></tr> 147<tr><td class="fieldname"><a id="gga4a96221b3c7f54dfb86035d952154e3aa8d70b14a38204fde4ad433023baa545a"></a>LIBEVDEV_READ_STATUS_SYNC </td><td class="fielddoc"><p>Depending on the <a class="el" href="group__events.html#gabb96c864e836c0b98788f4ab771c3a76" title="Get the next event from the device.">libevdev_next_event()</a> read flag: </p> 148<ul> 149<li>libevdev received a SYN_DROPPED from the device, and the caller should now resync the device, or,</li> 150<li>an event has been read in sync mode.</li> 151</ul> 152<dl class="section see"><dt>See also</dt><dd><a class="el" href="group__events.html#gabb96c864e836c0b98788f4ab771c3a76" title="Get the next event from the device.">libevdev_next_event</a> </dd></dl> 153</td></tr> 154</table> 155 156</div> 157</div> 158<h2 class="groupheader">Function Documentation</h2> 159<a id="gae18fbfb59064c9c4b9d5db2d8cb23784"></a> 160<h2 class="memtitle"><span class="permalink"><a href="#gae18fbfb59064c9c4b9d5db2d8cb23784">◆ </a></span>libevdev_has_event_pending()</h2> 161 162<div class="memitem"> 163<div class="memproto"> 164 <table class="memname"> 165 <tr> 166 <td class="memname">int libevdev_has_event_pending </td> 167 <td>(</td> 168 <td class="paramtype">struct libevdev * </td> 169 <td class="paramname"><em>dev</em></td><td>)</td> 170 <td></td> 171 </tr> 172 </table> 173</div><div class="memdoc"> 174 175<p>Check if there are events waiting for us. </p> 176<p>This function does not read an event off the fd and may not access the fd at all. If there are events queued internally this function will return non-zero. If the internal queue is empty, this function will poll the file descriptor for data.</p> 177<p>This is a convenience function for simple processes, most complex programs are expected to use select(2) or poll(2) on the file descriptor. The kernel guarantees that if data is available, it is a multiple of sizeof(struct input_event), and thus calling <a class="el" href="group__events.html#gabb96c864e836c0b98788f4ab771c3a76" title="Get the next event from the device.">libevdev_next_event()</a> when select(2) or poll(2) return is safe. You do not need <a class="el" href="group__events.html#gae18fbfb59064c9c4b9d5db2d8cb23784" title="Check if there are events waiting for us.">libevdev_has_event_pending()</a> if you're using select(2) or poll(2).</p> 178<dl class="params"><dt>Parameters</dt><dd> 179 <table class="params"> 180 <tr><td class="paramname">dev</td><td>The evdev device, already initialized with <a class="el" href="group__init.html#ga6658ac490d68c307ff8b8d1536c12b44" title="Set the fd for this struct and initialize internal data.">libevdev_set_fd()</a> </td></tr> 181 </table> 182 </dd> 183</dl> 184<dl class="section return"><dt>Returns</dt><dd>On failure, a negative errno is returned. </dd></dl> 185<dl class="retval"><dt>Return values</dt><dd> 186 <table class="retval"> 187 <tr><td class="paramname">0</td><td>No event is currently available </td></tr> 188 <tr><td class="paramname">1</td><td>One or more events are available on the fd</td></tr> 189 </table> 190 </dd> 191</dl> 192<dl class="section note"><dt>Note</dt><dd>This function is signal-safe. </dd></dl> 193 194</div> 195</div> 196<a id="gabb96c864e836c0b98788f4ab771c3a76"></a> 197<h2 class="memtitle"><span class="permalink"><a href="#gabb96c864e836c0b98788f4ab771c3a76">◆ </a></span>libevdev_next_event()</h2> 198 199<div class="memitem"> 200<div class="memproto"> 201 <table class="memname"> 202 <tr> 203 <td class="memname">int libevdev_next_event </td> 204 <td>(</td> 205 <td class="paramtype">struct libevdev * </td> 206 <td class="paramname"><em>dev</em>, </td> 207 </tr> 208 <tr> 209 <td class="paramkey"></td> 210 <td></td> 211 <td class="paramtype">unsigned int </td> 212 <td class="paramname"><em>flags</em>, </td> 213 </tr> 214 <tr> 215 <td class="paramkey"></td> 216 <td></td> 217 <td class="paramtype">struct input_event * </td> 218 <td class="paramname"><em>ev</em> </td> 219 </tr> 220 <tr> 221 <td></td> 222 <td>)</td> 223 <td></td><td></td> 224 </tr> 225 </table> 226</div><div class="memdoc"> 227 228<p>Get the next event from the device. </p> 229<p>This function operates in two different modes: normal mode or sync mode.</p> 230<p>In normal mode (when flags has <a class="el" href="group__events.html#gga56c288d9f2e4c1632986c4e218c494e9ac0d6ee19551eecf76f1ede4f36252418">LIBEVDEV_READ_FLAG_NORMAL</a> set), this function returns <a class="el" href="group__events.html#gga4a96221b3c7f54dfb86035d952154e3aab053221fc1c9630eee7111b75aa0aec7">LIBEVDEV_READ_STATUS_SUCCESS</a> and returns the event in the argument <code>ev</code>. If no events are available at this time, it returns -EAGAIN and ev is undefined.</p> 231<p>If the current event is an EV_SYN SYN_DROPPED event, this function returns <a class="el" href="group__events.html#gga4a96221b3c7f54dfb86035d952154e3aa8d70b14a38204fde4ad433023baa545a">LIBEVDEV_READ_STATUS_SYNC</a> and ev is set to the EV_SYN event. The caller should now call this function with the <a class="el" href="group__events.html#gga56c288d9f2e4c1632986c4e218c494e9a1f13a19641d6dafcf01a86a6389800f8">LIBEVDEV_READ_FLAG_SYNC</a> flag set, to get the set of events that make up the device state delta. This function returns <a class="el" href="group__events.html#gga4a96221b3c7f54dfb86035d952154e3aa8d70b14a38204fde4ad433023baa545a">LIBEVDEV_READ_STATUS_SYNC</a> for each event part of that delta, until it returns -EAGAIN once all events have been synced. For more details on what libevdev does to sync after a SYN_DROPPED event, see <a class="el" href="syn_dropped.html">SYN_DROPPED handling</a>.</p> 232<p>If a device needs to be synced by the caller but the caller does not call with the <a class="el" href="group__events.html#gga56c288d9f2e4c1632986c4e218c494e9a1f13a19641d6dafcf01a86a6389800f8">LIBEVDEV_READ_FLAG_SYNC</a> flag set, all events from the diff are dropped after libevdev updates its internal state and event processing continues as normal. Note that the current slot and the state of touch points may have updated during the SYN_DROPPED event, it is strongly recommended that a caller ignoring all sync events calls <a class="el" href="group__mt.html#gad22e2420be668b56ef486cde2e98c5dd" title="Get the currently active slot.">libevdev_get_current_slot()</a> and checks the ABS_MT_TRACKING_ID values for all slots.</p> 233<p>If a device has changed state without events being enqueued in libevdev, e.g. after changing the file descriptor, use the <a class="el" href="group__events.html#gga56c288d9f2e4c1632986c4e218c494e9a5198e5c9cc98b75f73f61b104d6a674c">LIBEVDEV_READ_FLAG_FORCE_SYNC</a> flag. This triggers an internal sync of the device and <a class="el" href="group__events.html#gabb96c864e836c0b98788f4ab771c3a76" title="Get the next event from the device.">libevdev_next_event()</a> returns <a class="el" href="group__events.html#gga4a96221b3c7f54dfb86035d952154e3aa8d70b14a38204fde4ad433023baa545a">LIBEVDEV_READ_STATUS_SYNC</a>. Any state changes are available as events as described above. If <a class="el" href="group__events.html#gga56c288d9f2e4c1632986c4e218c494e9a5198e5c9cc98b75f73f61b104d6a674c">LIBEVDEV_READ_FLAG_FORCE_SYNC</a> is set, the value of ev is undefined.</p> 234<dl class="params"><dt>Parameters</dt><dd> 235 <table class="params"> 236 <tr><td class="paramname">dev</td><td>The evdev device, already initialized with <a class="el" href="group__init.html#ga6658ac490d68c307ff8b8d1536c12b44" title="Set the fd for this struct and initialize internal data.">libevdev_set_fd()</a> </td></tr> 237 <tr><td class="paramname">flags</td><td>Set of flags to determine behaviour. If <a class="el" href="group__events.html#gga56c288d9f2e4c1632986c4e218c494e9ac0d6ee19551eecf76f1ede4f36252418">LIBEVDEV_READ_FLAG_NORMAL</a> is set, the next event is read in normal mode. If <a class="el" href="group__events.html#gga56c288d9f2e4c1632986c4e218c494e9a1f13a19641d6dafcf01a86a6389800f8">LIBEVDEV_READ_FLAG_SYNC</a> is set, the next event is read in sync mode. </td></tr> 238 <tr><td class="paramname">ev</td><td>On success, set to the current event. </td></tr> 239 </table> 240 </dd> 241</dl> 242<dl class="section return"><dt>Returns</dt><dd>On failure, a negative errno is returned. </dd></dl> 243<dl class="retval"><dt>Return values</dt><dd> 244 <table class="retval"> 245 <tr><td class="paramname">LIBEVDEV_READ_STATUS_SUCCESS</td><td>One or more events were read of the device and ev points to the next event in the queue </td></tr> 246 <tr><td class="paramname">-EAGAIN</td><td>No events are currently available on the device </td></tr> 247 <tr><td class="paramname">LIBEVDEV_READ_STATUS_SYNC</td><td>A SYN_DROPPED event was received, or a synced event was returned and ev points to the SYN_DROPPED event</td></tr> 248 </table> 249 </dd> 250</dl> 251<dl class="section note"><dt>Note</dt><dd>This function is signal-safe. </dd></dl> 252 253</div> 254</div> 255</div><!-- contents --> 256<!-- HTML footer for doxygen 1.8.8--> 257<!-- start footer part --> 258</div> 259</div> 260</div> 261</div> 262</div> 263<hr class="footer"/><address class="footer"><small> 264Generated by  <a href="http://www.doxygen.org/index.html"> 265<img class="footer" src="doxygen.png" alt="doxygen"/> 266</a> 1.9.1 267</small></address> 268</body> 269</html> 270
