<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<title>libusb: Polling and timing</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>
<link href="doxygen.css" rel="stylesheet" type="text/css"/>
</head>
<body>
<!-- Generated by Doxygen 1.6.3 -->
<script type="text/javascript">
<!--
function changeDisplayState (e){
var num=this.id.replace(/[^[0-9]/g,'');
var button=this.firstChild;
var sectionDiv=document.getElementById('dynsection'+num);
if (sectionDiv.style.display=='none'||sectionDiv.style.display==''){
sectionDiv.style.display='block';
button.src='open.gif';
}else{
sectionDiv.style.display='none';
button.src='closed.gif';
}
}
function initDynSections(){
var divs=document.getElementsByTagName('div');
var sectionCounter=1;
for(var i=0;i<divs.length-1;i++){
if(divs[i].className=='dynheader'&&divs[i+1].className=='dynsection'){
var header=divs[i];
var section=divs[i+1];
var button=header.firstChild;
if (button!='IMG'){
divs[i].insertBefore(document.createTextNode(' '),divs[i].firstChild);
button=document.createElement('img');
divs[i].insertBefore(button,divs[i].firstChild);
}
header.style.cursor='pointer';
header.onclick=changeDisplayState;
header.id='dynheader'+sectionCounter;
button.src='closed.gif';
section.id='dynsection'+sectionCounter;
section.style.display='none';
section.style.marginLeft='14px';
sectionCounter++;
}
}
}
window.onload = initDynSections;
-->
</script>
<div class="navigation" id="top">
<div class="tabs">
<ul>
<li><a href="index.html"><span>Main Page</span></a></li>
<li><a href="pages.html"><span>Related Pages</span></a></li>
<li><a href="modules.html"><span>Modules</span></a></li>
<li><a href="annotated.html"><span>Data Structures</span></a></li>
<li><a href="files.html"><span>Files</span></a></li>
</ul>
</div>
</div>
<div class="contents">
<h1>Polling and timing</h1>
<p>This page documents libusb's functions for polling events and timing.
<a href="#_details">More...</a></p>
<table border="0" cellpadding="0" cellspacing="0">
<tr><td colspan="2"><h2>Data Structures</h2></td></tr>
<tr><td class="memItemLeft" align="right" valign="top">struct </td><td class="memItemRight" valign="bottom"><a class="el" href="structlibusb__pollfd.html">libusb_pollfd</a></td></tr>
<tr><td class="mdescLeft"> </td><td class="mdescRight">File descriptor for polling. <a href="structlibusb__pollfd.html#_details">More...</a><br/></td></tr>
<tr><td colspan="2"><h2>Typedefs</h2></td></tr>
<tr><td class="memItemLeft" align="right" valign="top">typedef void(* </td><td class="memItemRight" valign="bottom"><a class="el" href="group__poll.html#gabc8d353d64d262fa9f20ca01ba47dfcb">libusb_pollfd_added_cb</a> )(int fd, short events, void *user_data)</td></tr>
<tr><td class="mdescLeft"> </td><td class="mdescRight">Callback function, invoked when a new file descriptor should be added to the set of file descriptors monitored for events. <a href="#gabc8d353d64d262fa9f20ca01ba47dfcb"></a><br/></td></tr>
<tr><td class="memItemLeft" align="right" valign="top">typedef void(* </td><td class="memItemRight" valign="bottom"><a class="el" href="group__poll.html#gafb48e26cc97667f1891f6d27f2c81ef6">libusb_pollfd_removed_cb</a> )(int fd, void *user_data)</td></tr>
<tr><td class="mdescLeft"> </td><td class="mdescRight">Callback function, invoked when a file descriptor should be removed from the set of file descriptors being monitored for events. <a href="#gafb48e26cc97667f1891f6d27f2c81ef6"></a><br/></td></tr>
<tr><td colspan="2"><h2>Functions</h2></td></tr>
<tr><td class="memItemLeft" align="right" valign="top">int </td><td class="memItemRight" valign="bottom"><a class="el" href="group__poll.html#ga6e5a116d5c9498ca4a0e29587fec1a05">libusb_try_lock_events</a> (<a class="el" href="group__lib.html#ga4ec088aa7b79c4a9599e39bf36a72833">libusb_context</a> *ctx)</td></tr>
<tr><td class="mdescLeft"> </td><td class="mdescRight">Attempt to acquire the event handling lock. <a href="#ga6e5a116d5c9498ca4a0e29587fec1a05"></a><br/></td></tr>
<tr><td class="memItemLeft" align="right" valign="top">void </td><td class="memItemRight" valign="bottom"><a class="el" href="group__poll.html#gaa72153938dc4f34decfacbc6cc6237ef">libusb_lock_events</a> (<a class="el" href="group__lib.html#ga4ec088aa7b79c4a9599e39bf36a72833">libusb_context</a> *ctx)</td></tr>
<tr><td class="mdescLeft"> </td><td class="mdescRight">Acquire the event handling lock, blocking until successful acquisition if it is contended. <a href="#gaa72153938dc4f34decfacbc6cc6237ef"></a><br/></td></tr>
<tr><td class="memItemLeft" align="right" valign="top">void </td><td class="memItemRight" valign="bottom"><a class="el" href="group__poll.html#gacefbeabdd3409490dc4678f00779c165">libusb_unlock_events</a> (<a class="el" href="group__lib.html#ga4ec088aa7b79c4a9599e39bf36a72833">libusb_context</a> *ctx)</td></tr>
<tr><td class="mdescLeft"> </td><td class="mdescRight">Release the lock previously acquired with <a class="el" href="group__poll.html#ga6e5a116d5c9498ca4a0e29587fec1a05" title="Attempt to acquire the event handling lock.">libusb_try_lock_events()</a> or <a class="el" href="group__poll.html#gaa72153938dc4f34decfacbc6cc6237ef" title="Acquire the event handling lock, blocking until successful acquisition if it is contended...">libusb_lock_events()</a>. <a href="#gacefbeabdd3409490dc4678f00779c165"></a><br/></td></tr>
<tr><td class="memItemLeft" align="right" valign="top">int </td><td class="memItemRight" valign="bottom"><a class="el" href="group__poll.html#ga63592b28c265185d9469d1e6920d8373">libusb_event_handling_ok</a> (<a class="el" href="group__lib.html#ga4ec088aa7b79c4a9599e39bf36a72833">libusb_context</a> *ctx)</td></tr>
<tr><td class="mdescLeft"> </td><td class="mdescRight">Determine if it is still OK for this thread to be doing event handling. <a href="#ga63592b28c265185d9469d1e6920d8373"></a><br/></td></tr>
<tr><td class="memItemLeft" align="right" valign="top">int </td><td class="memItemRight" valign="bottom"><a class="el" href="group__poll.html#ga3a0a6e8be310c20f1ca68722149f9dbf">libusb_event_handler_active</a> (<a class="el" href="group__lib.html#ga4ec088aa7b79c4a9599e39bf36a72833">libusb_context</a> *ctx)</td></tr>
<tr><td class="mdescLeft"> </td><td class="mdescRight">Determine if an active thread is handling events (i.e. <a href="#ga3a0a6e8be310c20f1ca68722149f9dbf"></a><br/></td></tr>
<tr><td class="memItemLeft" align="right" valign="top">void </td><td class="memItemRight" valign="bottom"><a class="el" href="group__poll.html#ga150865a3f35c38173d688efa7ee52929">libusb_lock_event_waiters</a> (<a class="el" href="group__lib.html#ga4ec088aa7b79c4a9599e39bf36a72833">libusb_context</a> *ctx)</td></tr>
<tr><td class="mdescLeft"> </td><td class="mdescRight">Acquire the event waiters lock. <a href="#ga150865a3f35c38173d688efa7ee52929"></a><br/></td></tr>
<tr><td class="memItemLeft" align="right" valign="top">void </td><td class="memItemRight" valign="bottom"><a class="el" href="group__poll.html#ga41d7716458c11ee02d0deb19a31233ed">libusb_unlock_event_waiters</a> (<a class="el" href="group__lib.html#ga4ec088aa7b79c4a9599e39bf36a72833">libusb_context</a> *ctx)</td></tr>
<tr><td class="mdescLeft"> </td><td class="mdescRight">Release the event waiters lock. <a href="#ga41d7716458c11ee02d0deb19a31233ed"></a><br/></td></tr>
<tr><td class="memItemLeft" align="right" valign="top">int </td><td class="memItemRight" valign="bottom"><a class="el" href="group__poll.html#gae22755d523560be2867be7d09034ca50">libusb_wait_for_event</a> (<a class="el" href="group__lib.html#ga4ec088aa7b79c4a9599e39bf36a72833">libusb_context</a> *ctx, struct timeval *tv)</td></tr>
<tr><td class="mdescLeft"> </td><td class="mdescRight">Wait for another thread to signal completion of an event. <a href="#gae22755d523560be2867be7d09034ca50"></a><br/></td></tr>
<tr><td class="memItemLeft" align="right" valign="top">int </td><td class="memItemRight" valign="bottom"><a class="el" href="group__poll.html#ga6deff4c7d3a6c04bb9ec9fd259b48933">libusb_handle_events_timeout</a> (<a class="el" href="group__lib.html#ga4ec088aa7b79c4a9599e39bf36a72833">libusb_context</a> *ctx, struct timeval *tv)</td></tr>
<tr><td class="mdescLeft"> </td><td class="mdescRight">Handle any pending events. <a href="#ga6deff4c7d3a6c04bb9ec9fd259b48933"></a><br/></td></tr>
<tr><td class="memItemLeft" align="right" valign="top">int </td><td class="memItemRight" valign="bottom"><a class="el" href="group__poll.html#ga4989086e3f0327f3886a4c474ec7c327">libusb_handle_events</a> (<a class="el" href="group__lib.html#ga4ec088aa7b79c4a9599e39bf36a72833">libusb_context</a> *ctx)</td></tr>
<tr><td class="mdescLeft"> </td><td class="mdescRight">Handle any pending events in blocking mode. <a href="#ga4989086e3f0327f3886a4c474ec7c327"></a><br/></td></tr>
<tr><td class="memItemLeft" align="right" valign="top">int </td><td class="memItemRight" valign="bottom"><a class="el" href="group__poll.html#ga71da081f97afa3bf68aed8e372254e8f">libusb_handle_events_locked</a> (<a class="el" href="group__lib.html#ga4ec088aa7b79c4a9599e39bf36a72833">libusb_context</a> *ctx, struct timeval *tv)</td></tr>
<tr><td class="mdescLeft"> </td><td class="mdescRight">Handle any pending events by polling file descriptors, without checking if any other threads are already doing so. <a href="#ga71da081f97afa3bf68aed8e372254e8f"></a><br/></td></tr>
<tr><td class="memItemLeft" align="right" valign="top">int </td><td class="memItemRight" valign="bottom"><a class="el" href="group__poll.html#gae7a654315636bebf404c1784429f06df">libusb_pollfds_handle_timeouts</a> (<a class="el" href="group__lib.html#ga4ec088aa7b79c4a9599e39bf36a72833">libusb_context</a> *ctx)</td></tr>
<tr><td class="mdescLeft"> </td><td class="mdescRight">Determines whether your application must apply special timing considerations when monitoring libusb's file descriptors. <a href="#gae7a654315636bebf404c1784429f06df"></a><br/></td></tr>
<tr><td class="memItemLeft" align="right" valign="top">int </td><td class="memItemRight" valign="bottom"><a class="el" href="group__poll.html#ga5bc6f5bc71a43845244912da6679f634">libusb_get_next_timeout</a> (<a class="el" href="group__lib.html#ga4ec088aa7b79c4a9599e39bf36a72833">libusb_context</a> *ctx, struct timeval *tv)</td></tr>
<tr><td class="mdescLeft"> </td><td class="mdescRight">Determine the next internal timeout that libusb needs to handle. <a href="#ga5bc6f5bc71a43845244912da6679f634"></a><br/></td></tr>
<tr><td class="memItemLeft" align="right" valign="top">void </td><td class="memItemRight" valign="bottom"><a class="el" href="group__poll.html#ga1b7b2deb193f2e9ffda5e727361d7e67">libusb_set_pollfd_notifiers</a> (<a class="el" href="group__lib.html#ga4ec088aa7b79c4a9599e39bf36a72833">libusb_context</a> *ctx, <a class="el" href="group__poll.html#gabc8d353d64d262fa9f20ca01ba47dfcb">libusb_pollfd_added_cb</a> added_cb, <a class="el" href="group__poll.html#gafb48e26cc97667f1891f6d27f2c81ef6">libusb_pollfd_removed_cb</a> removed_cb, void *user_data)</td></tr>
<tr><td class="mdescLeft"> </td><td class="mdescRight">Register notification functions for file descriptor additions/removals. <a href="#ga1b7b2deb193f2e9ffda5e727361d7e67"></a><br/></td></tr>
<tr><td class="memItemLeft" align="right" valign="top">struct <a class="el" href="structlibusb__pollfd.html">libusb_pollfd</a> ** </td><td class="memItemRight" valign="bottom"><a class="el" href="group__poll.html#gab1a72869a926552b27a6c667695df3a2">libusb_get_pollfds</a> (<a class="el" href="group__lib.html#ga4ec088aa7b79c4a9599e39bf36a72833">libusb_context</a> *ctx)</td></tr>
<tr><td class="mdescLeft"> </td><td class="mdescRight">Retrieve a list of file descriptors that should be polled by your main loop as libusb event sources. <a href="#gab1a72869a926552b27a6c667695df3a2"></a><br/></td></tr>
</table>
<hr/><a name="_details"></a><h2>Detailed Description</h2>
<p>This page documents libusb's functions for polling events and timing. </p>
<p>These functions are only necessary for users of the <a class="el" href="group__asyncio.html">asynchronous API</a>. If you are only using the simpler <a class="el" href="group__syncio.html">synchronous API</a> then you do not need to ever call these functions.</p>
<p>The justification for the functionality described here has already been discussed in the <a class="el" href="group__asyncio.html#asyncevent">event handling</a> section of the asynchronous API documentation. In summary, libusb does not create internal threads for event processing and hence relies on your application calling into libusb at certain points in time so that pending events can be handled. In order to know precisely when libusb needs to be called into, libusb offers you a set of pollable file descriptors and information about when the next timeout expires.</p>
<p>If you are using the asynchronous I/O API, you must take one of the two following options, otherwise your I/O will not complete.</p>
<h2><a class="anchor" id="pollsimple">
The simple option</a></h2>
<p>If your application revolves solely around libusb and does not need to handle other event sources, you can have a program structure as follows: </p>
<div class="fragment"><pre class="fragment"><span class="comment">// initialize libusb</span>
<span class="comment">// find and open device</span>
<span class="comment">// maybe fire off some initial async I/O</span>
<span class="keywordflow">while</span> (user_has_not_requested_exit)
<a class="code" href="group__poll.html#ga4989086e3f0327f3886a4c474ec7c327" title="Handle any pending events in blocking mode.">libusb_handle_events</a>(ctx);
<span class="comment">// clean up and exit</span>
</pre></div><p>With such a simple main loop, you do not have to worry about managing sets of file descriptors or handling timeouts. <a class="el" href="group__poll.html#ga4989086e3f0327f3886a4c474ec7c327" title="Handle any pending events in blocking mode.">libusb_handle_events()</a> will handle those details internally.</p>
<h2><a class="anchor" id="pollmain">
The more advanced option</a></h2>
<p>In more advanced applications, you will already have a main loop which is monitoring other event sources: network sockets, X11 events, mouse movements, etc. Through exposing a set of file descriptors, libusb is designed to cleanly integrate into such main loops.</p>
<p>In addition to polling file descriptors for the other event sources, you take a set of file descriptors from libusb and monitor those too. When you detect activity on libusb's file descriptors, you call <a class="el" href="group__poll.html#ga6deff4c7d3a6c04bb9ec9fd259b48933" title="Handle any pending events.">libusb_handle_events_timeout()</a> in non-blocking mode.</p>
<p>What's more, libusb may also need to handle events at specific moments in time. No file descriptor activity is generated at these times, so your own application needs to be continually aware of when the next one of these moments occurs (through calling <a class="el" href="group__poll.html#ga5bc6f5bc71a43845244912da6679f634" title="Determine the next internal timeout that libusb needs to handle.">libusb_get_next_timeout()</a>), and then it needs to call <a class="el" href="group__poll.html#ga6deff4c7d3a6c04bb9ec9fd259b48933" title="Handle any pending events.">libusb_handle_events_timeout()</a> in non-blocking mode when these moments occur. This means that you need to adjust your poll()/select() timeout accordingly.</p>
<p>libusb provides you with a set of file descriptors to poll and expects you to poll all of them, treating them as a single entity. The meaning of each file descriptor in the set is an internal implementation detail, platform-dependent and may vary from release to release. Don't try and interpret the meaning of the file descriptors, just do as libusb indicates, polling all of them at once.</p>
<p>In pseudo-code, you want something that looks like: </p>
<div class="fragment"><pre class="fragment"><span class="comment">// initialise libusb</span>
<a class="code" href="group__poll.html#gab1a72869a926552b27a6c667695df3a2" title="Retrieve a list of file descriptors that should be polled by your main loop as libusb...">libusb_get_pollfds</a>(ctx)
while (user has not requested application exit) {
<a class="code" href="group__poll.html#ga5bc6f5bc71a43845244912da6679f634" title="Determine the next internal timeout that libusb needs to handle.">libusb_get_next_timeout</a>(ctx);
poll(on libusb file descriptors plus any other event sources of interest,
<span class="keyword">using</span> a timeout no larger than the value libusb just suggested)
<span class="keywordflow">if</span> (poll() indicated activity on libusb file descriptors)
<a class="code" href="group__poll.html#ga6deff4c7d3a6c04bb9ec9fd259b48933" title="Handle any pending events.">libusb_handle_events_timeout</a>(ctx, 0);
<span class="keywordflow">if</span> (time has elapsed to or beyond the libusb timeout)
<a class="code" href="group__poll.html#ga6deff4c7d3a6c04bb9ec9fd259b48933" title="Handle any pending events.">libusb_handle_events_timeout</a>(ctx, 0);
<span class="comment">// handle events from other sources here</span>
}
<span class="comment">// clean up and exit</span>
</pre></div><h3><a class="anchor" id="polltime">
Notes on time-based events</a></h3>
<p>The above complication with having to track time and call into libusb at specific moments is a bit of a headache. For maximum compatibility, you do need to write your main loop as above, but you may decide that you can restrict the supported platforms of your application and get away with a more simplistic scheme.</p>
<p>These time-based event complications are <b>not</b> required on the following platforms:</p>
<ul>
<li>Darwin</li>
<li>Linux, provided that the following version requirements are satisfied:<ul>
<li>Linux v2.6.27 or newer, compiled with timerfd support</li>
<li>glibc v2.9 or newer</li>
<li>libusb v1.0.5 or newer</li>
</ul>
</li>
</ul>
<p>Under these configurations, <a class="el" href="group__poll.html#ga5bc6f5bc71a43845244912da6679f634" title="Determine the next internal timeout that libusb needs to handle.">libusb_get_next_timeout()</a> will <em>always</em> return 0, so your main loop can be simplified to: </p>
<div class="fragment"><pre class="fragment"><span class="comment">// initialise libusb</span>
<a class="code" href="group__poll.html#gab1a72869a926552b27a6c667695df3a2" title="Retrieve a list of file descriptors that should be polled by your main loop as libusb...">libusb_get_pollfds</a>(ctx)
while (user has not requested application exit) {
poll(on libusb file descriptors plus any other event sources of interest,
<span class="keyword">using</span> any timeout that you like)
<span class="keywordflow">if</span> (poll() indicated activity on libusb file descriptors)
<a class="code" href="group__poll.html#ga6deff4c7d3a6c04bb9ec9fd259b48933" title="Handle any pending events.">libusb_handle_events_timeout</a>(ctx, 0);
<span class="comment">// handle events from other sources here</span>
}
<span class="comment">// clean up and exit</span>
</pre></div><p>Do remember that if you simplify your main loop to the above, you will lose compatibility with some platforms (including legacy Linux platforms, and <em>any future platforms supported by libusb which may have time-based event requirements</em>). The resultant problems will likely appear as strange bugs in your application.</p>
<p>You can use the <a class="el" href="group__poll.html#gae7a654315636bebf404c1784429f06df" title="Determines whether your application must apply special timing considerations when...">libusb_pollfds_handle_timeouts()</a> function to do a runtime check to see if it is safe to ignore the time-based event complications. If your application has taken the shortcut of ignoring libusb's next timeout in your main loop, then you are advised to check the return value of <a class="el" href="group__poll.html#gae7a654315636bebf404c1784429f06df" title="Determines whether your application must apply special timing considerations when...">libusb_pollfds_handle_timeouts()</a> during application startup, and to abort if the platform does suffer from these timing complications.</p>
<h3><a class="anchor" id="fdsetchange">
Changes in the file descriptor set</a></h3>
<p>The set of file descriptors that libusb uses as event sources may change during the life of your application. Rather than having to repeatedly call <a class="el" href="group__poll.html#gab1a72869a926552b27a6c667695df3a2" title="Retrieve a list of file descriptors that should be polled by your main loop as libusb...">libusb_get_pollfds()</a>, you can set up notification functions for when the file descriptor set changes using <a class="el" href="group__poll.html#ga1b7b2deb193f2e9ffda5e727361d7e67" title="Register notification functions for file descriptor additions/removals.">libusb_set_pollfd_notifiers()</a>.</p>
<h3><a class="anchor" id="mtissues">
Multi-threaded considerations</a></h3>
<p>Unfortunately, the situation is complicated further when multiple threads come into play. If two threads are monitoring the same file descriptors, the fact that only one thread will be woken up when an event occurs causes some headaches.</p>
<p>The events lock, event waiters lock, and <a class="el" href="group__poll.html#ga71da081f97afa3bf68aed8e372254e8f" title="Handle any pending events by polling file descriptors, without checking if any other...">libusb_handle_events_locked()</a> entities are added to solve these problems. You do not need to be concerned with these entities otherwise.</p>
<p>See the extra documentation: <a class="el" href="mtasync.html">Multi-threaded applications and asynchronous I/O</a> </p>
<hr/><h2>Typedef Documentation</h2>
<a class="anchor" id="gabc8d353d64d262fa9f20ca01ba47dfcb"></a><!-- doxytag: member="libusb.h::libusb_pollfd_added_cb" ref="gabc8d353d64d262fa9f20ca01ba47dfcb" args=")(int fd, short events, void *user_data)" -->
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">typedef void(* <a class="el" href="group__poll.html#gabc8d353d64d262fa9f20ca01ba47dfcb">libusb_pollfd_added_cb</a>)(int fd, short events, void *user_data)</td>
</tr>
</table>
</div>
<div class="memdoc">
<p>Callback function, invoked when a new file descriptor should be added to the set of file descriptors monitored for events. </p>
<dl><dt><b>Parameters:</b></dt><dd>
<table border="0" cellspacing="2" cellpadding="0">
<tr><td valign="top"></td><td valign="top"><em>fd</em> </td><td>the new file descriptor </td></tr>
<tr><td valign="top"></td><td valign="top"><em>events</em> </td><td>events to monitor for, see <a class="el" href="structlibusb__pollfd.html">libusb_pollfd</a> for a description </td></tr>
<tr><td valign="top"></td><td valign="top"><em>user_data</em> </td><td>User data pointer specified in <a class="el" href="group__poll.html#ga1b7b2deb193f2e9ffda5e727361d7e67" title="Register notification functions for file descriptor additions/removals.">libusb_set_pollfd_notifiers()</a> call </td></tr>
</table>
</dd>
</dl>
<dl class="see"><dt><b>See also:</b></dt><dd><a class="el" href="group__poll.html#ga1b7b2deb193f2e9ffda5e727361d7e67" title="Register notification functions for file descriptor additions/removals.">libusb_set_pollfd_notifiers()</a> </dd></dl>
</div>
</div>
<a class="anchor" id="gafb48e26cc97667f1891f6d27f2c81ef6"></a><!-- doxytag: member="libusb.h::libusb_pollfd_removed_cb" ref="gafb48e26cc97667f1891f6d27f2c81ef6" args=")(int fd, void *user_data)" -->
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">typedef void(* <a class="el" href="group__poll.html#gafb48e26cc97667f1891f6d27f2c81ef6">libusb_pollfd_removed_cb</a>)(int fd, void *user_data)</td>
</tr>
</table>
</div>
<div class="memdoc">
<p>Callback function, invoked when a file descriptor should be removed from the set of file descriptors being monitored for events. </p>
<p>After returning from this callback, do not use that file descriptor again. </p>
<dl><dt><b>Parameters:</b></dt><dd>
<table border="0" cellspacing="2" cellpadding="0">
<tr><td valign="top"></td><td valign="top"><em>fd</em> </td><td>the file descriptor to stop monitoring </td></tr>
<tr><td valign="top"></td><td valign="top"><em>user_data</em> </td><td>User data pointer specified in <a class="el" href="group__poll.html#ga1b7b2deb193f2e9ffda5e727361d7e67" title="Register notification functions for file descriptor additions/removals.">libusb_set_pollfd_notifiers()</a> call </td></tr>
</table>
</dd>
</dl>
<dl class="see"><dt><b>See also:</b></dt><dd><a class="el" href="group__poll.html#ga1b7b2deb193f2e9ffda5e727361d7e67" title="Register notification functions for file descriptor additions/removals.">libusb_set_pollfd_notifiers()</a> </dd></dl>
</div>
</div>
<hr/><h2>Function Documentation</h2>
<a class="anchor" id="ga6e5a116d5c9498ca4a0e29587fec1a05"></a><!-- doxytag: member="io.c::libusb_try_lock_events" ref="ga6e5a116d5c9498ca4a0e29587fec1a05" args="(libusb_context *ctx)" -->
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">int libusb_try_lock_events </td>
<td>(</td>
<td class="paramtype"><a class="el" href="group__lib.html#ga4ec088aa7b79c4a9599e39bf36a72833">libusb_context</a> * </td>
<td class="paramname"> <em>ctx</em></td>
<td> ) </td>
<td></td>
</tr>
</table>
</div>
<div class="memdoc">
<p>Attempt to acquire the event handling lock. </p>
<p>This lock is used to ensure that only one thread is monitoring libusb event sources at any one time.</p>
<p>You only need to use this lock if you are developing an application which calls poll() or select() on libusb's file descriptors directly. If you stick to libusb's event handling loop functions (e.g. <a class="el" href="group__poll.html#ga4989086e3f0327f3886a4c474ec7c327" title="Handle any pending events in blocking mode.">libusb_handle_events()</a>) then you do not need to be concerned with this locking.</p>
<p>While holding this lock, you are trusted to actually be handling events. If you are no longer handling events, you must call <a class="el" href="group__poll.html#gacefbeabdd3409490dc4678f00779c165" title="Release the lock previously acquired with libusb_try_lock_events() or libusb_lock_events()...">libusb_unlock_events()</a> as soon as possible.</p>
<dl><dt><b>Parameters:</b></dt><dd>
<table border="0" cellspacing="2" cellpadding="0">
<tr><td valign="top"></td><td valign="top"><em>ctx</em> </td><td>the context to operate on, or NULL for the default context </td></tr>
</table>
</dd>
</dl>
<dl class="return"><dt><b>Returns:</b></dt><dd>0 if the lock was obtained successfully </dd>
<dd>
1 if the lock was not obtained (i.e. another thread holds the lock) </dd></dl>
<dl class="see"><dt><b>See also:</b></dt><dd><a class="el" href="mtasync.html">Multi-threaded applications and asynchronous I/O</a> </dd></dl>
</div>
</div>
<a class="anchor" id="gaa72153938dc4f34decfacbc6cc6237ef"></a><!-- doxytag: member="io.c::libusb_lock_events" ref="gaa72153938dc4f34decfacbc6cc6237ef" args="(libusb_context *ctx)" -->
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">void libusb_lock_events </td>
<td>(</td>
<td class="paramtype"><a class="el" href="group__lib.html#ga4ec088aa7b79c4a9599e39bf36a72833">libusb_context</a> * </td>
<td class="paramname"> <em>ctx</em></td>
<td> ) </td>
<td></td>
</tr>
</table>
</div>
<div class="memdoc">
<p>Acquire the event handling lock, blocking until successful acquisition if it is contended. </p>
<p>This lock is used to ensure that only one thread is monitoring libusb event sources at any one time.</p>
<p>You only need to use this lock if you are developing an application which calls poll() or select() on libusb's file descriptors directly. If you stick to libusb's event handling loop functions (e.g. <a class="el" href="group__poll.html#ga4989086e3f0327f3886a4c474ec7c327" title="Handle any pending events in blocking mode.">libusb_handle_events()</a>) then you do not need to be concerned with this locking.</p>
<p>While holding this lock, you are trusted to actually be handling events. If you are no longer handling events, you must call <a class="el" href="group__poll.html#gacefbeabdd3409490dc4678f00779c165" title="Release the lock previously acquired with libusb_try_lock_events() or libusb_lock_events()...">libusb_unlock_events()</a> as soon as possible.</p>
<dl><dt><b>Parameters:</b></dt><dd>
<table border="0" cellspacing="2" cellpadding="0">
<tr><td valign="top"></td><td valign="top"><em>ctx</em> </td><td>the context to operate on, or NULL for the default context </td></tr>
</table>
</dd>
</dl>
<dl class="see"><dt><b>See also:</b></dt><dd><a class="el" href="mtasync.html">Multi-threaded applications and asynchronous I/O</a> </dd></dl>
</div>
</div>
<a class="anchor" id="gacefbeabdd3409490dc4678f00779c165"></a><!-- doxytag: member="io.c::libusb_unlock_events" ref="gacefbeabdd3409490dc4678f00779c165" args="(libusb_context *ctx)" -->
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">void libusb_unlock_events </td>
<td>(</td>
<td class="paramtype"><a class="el" href="group__lib.html#ga4ec088aa7b79c4a9599e39bf36a72833">libusb_context</a> * </td>
<td class="paramname"> <em>ctx</em></td>
<td> ) </td>
<td></td>
</tr>
</table>
</div>
<div class="memdoc">
<p>Release the lock previously acquired with <a class="el" href="group__poll.html#ga6e5a116d5c9498ca4a0e29587fec1a05" title="Attempt to acquire the event handling lock.">libusb_try_lock_events()</a> or <a class="el" href="group__poll.html#gaa72153938dc4f34decfacbc6cc6237ef" title="Acquire the event handling lock, blocking until successful acquisition if it is contended...">libusb_lock_events()</a>. </p>
<p>Releasing this lock will wake up any threads blocked on <a class="el" href="group__poll.html#gae22755d523560be2867be7d09034ca50" title="Wait for another thread to signal completion of an event.">libusb_wait_for_event()</a>.</p>
<dl><dt><b>Parameters:</b></dt><dd>
<table border="0" cellspacing="2" cellpadding="0">
<tr><td valign="top"></td><td valign="top"><em>ctx</em> </td><td>the context to operate on, or NULL for the default context </td></tr>
</table>
</dd>
</dl>
<dl class="see"><dt><b>See also:</b></dt><dd><a class="el" href="mtasync.html">Multi-threaded applications and asynchronous I/O</a> </dd></dl>
</div>
</div>
<a class="anchor" id="ga63592b28c265185d9469d1e6920d8373"></a><!-- doxytag: member="io.c::libusb_event_handling_ok" ref="ga63592b28c265185d9469d1e6920d8373" args="(libusb_context *ctx)" -->
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">int libusb_event_handling_ok </td>
<td>(</td>
<td class="paramtype"><a class="el" href="group__lib.html#ga4ec088aa7b79c4a9599e39bf36a72833">libusb_context</a> * </td>
<td class="paramname"> <em>ctx</em></td>
<td> ) </td>
<td></td>
</tr>
</table>
</div>
<div class="memdoc">
<p>Determine if it is still OK for this thread to be doing event handling. </p>
<p>Sometimes, libusb needs to temporarily pause all event handlers, and this is the function you should use before polling file descriptors to see if this is the case.</p>
<p>If this function instructs your thread to give up the events lock, you should just continue the usual logic that is documented in <a class="el" href="mtasync.html">Multi-threaded applications and asynchronous I/O</a>. On the next iteration, your thread will fail to obtain the events lock, and will hence become an event waiter.</p>
<p>This function should be called while the events lock is held: you don't need to worry about the results of this function if your thread is not the current event handler.</p>
<dl><dt><b>Parameters:</b></dt><dd>
<table border="0" cellspacing="2" cellpadding="0">
<tr><td valign="top"></td><td valign="top"><em>ctx</em> </td><td>the context to operate on, or NULL for the default context </td></tr>
</table>
</dd>
</dl>
<dl class="return"><dt><b>Returns:</b></dt><dd>1 if event handling can start or continue </dd>
<dd>
0 if this thread must give up the events lock </dd></dl>
<dl class="see"><dt><b>See also:</b></dt><dd><a class="el" href="mtasync.html#fullstory">Multi-threaded I/O: the full story</a> </dd></dl>
</div>
</div>
<a class="anchor" id="ga3a0a6e8be310c20f1ca68722149f9dbf"></a><!-- doxytag: member="io.c::libusb_event_handler_active" ref="ga3a0a6e8be310c20f1ca68722149f9dbf" args="(libusb_context *ctx)" -->
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">int libusb_event_handler_active </td>
<td>(</td>
<td class="paramtype"><a class="el" href="group__lib.html#ga4ec088aa7b79c4a9599e39bf36a72833">libusb_context</a> * </td>
<td class="paramname"> <em>ctx</em></td>
<td> ) </td>
<td></td>
</tr>
</table>
</div>
<div class="memdoc">
<p>Determine if an active thread is handling events (i.e. </p>
<p>if anyone is holding the event handling lock).</p>
<dl><dt><b>Parameters:</b></dt><dd>
<table border="0" cellspacing="2" cellpadding="0">
<tr><td valign="top"></td><td valign="top"><em>ctx</em> </td><td>the context to operate on, or NULL for the default context </td></tr>
</table>
</dd>
</dl>
<dl class="return"><dt><b>Returns:</b></dt><dd>1 if a thread is handling events </dd>
<dd>
0 if there are no threads currently handling events </dd></dl>
<dl class="see"><dt><b>See also:</b></dt><dd><a class="el" href="mtasync.html">Multi-threaded applications and asynchronous I/O</a> </dd></dl>
</div>
</div>
<a class="anchor" id="ga150865a3f35c38173d688efa7ee52929"></a><!-- doxytag: member="io.c::libusb_lock_event_waiters" ref="ga150865a3f35c38173d688efa7ee52929" args="(libusb_context *ctx)" -->
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">void libusb_lock_event_waiters </td>
<td>(</td>
<td class="paramtype"><a class="el" href="group__lib.html#ga4ec088aa7b79c4a9599e39bf36a72833">libusb_context</a> * </td>
<td class="paramname"> <em>ctx</em></td>
<td> ) </td>
<td></td>
</tr>
</table>
</div>
<div class="memdoc">
<p>Acquire the event waiters lock. </p>
<p>This lock is designed to be obtained under the situation where you want to be aware when events are completed, but some other thread is event handling so calling <a class="el" href="group__poll.html#ga4989086e3f0327f3886a4c474ec7c327" title="Handle any pending events in blocking mode.">libusb_handle_events()</a> is not allowed.</p>
<p>You then obtain this lock, re-check that another thread is still handling events, then call <a class="el" href="group__poll.html#gae22755d523560be2867be7d09034ca50" title="Wait for another thread to signal completion of an event.">libusb_wait_for_event()</a>.</p>
<p>You only need to use this lock if you are developing an application which calls poll() or select() on libusb's file descriptors directly, <b>and</b> may potentially be handling events from 2 threads simultaenously. If you stick to libusb's event handling loop functions (e.g. <a class="el" href="group__poll.html#ga4989086e3f0327f3886a4c474ec7c327" title="Handle any pending events in blocking mode.">libusb_handle_events()</a>) then you do not need to be concerned with this locking.</p>
<dl><dt><b>Parameters:</b></dt><dd>
<table border="0" cellspacing="2" cellpadding="0">
<tr><td valign="top"></td><td valign="top"><em>ctx</em> </td><td>the context to operate on, or NULL for the default context </td></tr>
</table>
</dd>
</dl>
<dl class="see"><dt><b>See also:</b></dt><dd><a class="el" href="mtasync.html">Multi-threaded applications and asynchronous I/O</a> </dd></dl>
</div>
</div>
<a class="anchor" id="ga41d7716458c11ee02d0deb19a31233ed"></a><!-- doxytag: member="io.c::libusb_unlock_event_waiters" ref="ga41d7716458c11ee02d0deb19a31233ed" args="(libusb_context *ctx)" -->
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">void libusb_unlock_event_waiters </td>
<td>(</td>
<td class="paramtype"><a class="el" href="group__lib.html#ga4ec088aa7b79c4a9599e39bf36a72833">libusb_context</a> * </td>
<td class="paramname"> <em>ctx</em></td>
<td> ) </td>
<td></td>
</tr>
</table>
</div>
<div class="memdoc">
<p>Release the event waiters lock. </p>
<dl><dt><b>Parameters:</b></dt><dd>
<table border="0" cellspacing="2" cellpadding="0">
<tr><td valign="top"></td><td valign="top"><em>ctx</em> </td><td>the context to operate on, or NULL for the default context </td></tr>
</table>
</dd>
</dl>
<dl class="see"><dt><b>See also:</b></dt><dd><a class="el" href="mtasync.html">Multi-threaded applications and asynchronous I/O</a> </dd></dl>
</div>
</div>
<a class="anchor" id="gae22755d523560be2867be7d09034ca50"></a><!-- doxytag: member="io.c::libusb_wait_for_event" ref="gae22755d523560be2867be7d09034ca50" args="(libusb_context *ctx, struct timeval *tv)" -->
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">int libusb_wait_for_event </td>
<td>(</td>
<td class="paramtype"><a class="el" href="group__lib.html#ga4ec088aa7b79c4a9599e39bf36a72833">libusb_context</a> * </td>
<td class="paramname"> <em>ctx</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">struct timeval * </td>
<td class="paramname"> <em>tv</em></td><td> </td>
</tr>
<tr>
<td></td>
<td>)</td>
<td></td><td></td><td></td>
</tr>
</table>
</div>
<div class="memdoc">
<p>Wait for another thread to signal completion of an event. </p>
<p>Must be called with the event waiters lock held, see <a class="el" href="group__poll.html#ga150865a3f35c38173d688efa7ee52929" title="Acquire the event waiters lock.">libusb_lock_event_waiters()</a>.</p>
<p>This function will block until any of the following conditions are met:</p>
<ol type="1">
<li>The timeout expires</li>
<li>A transfer completes</li>
<li>A thread releases the event handling lock through <a class="el" href="group__poll.html#gacefbeabdd3409490dc4678f00779c165" title="Release the lock previously acquired with libusb_try_lock_events() or libusb_lock_events()...">libusb_unlock_events()</a></li>
</ol>
<p>Condition 1 is obvious. Condition 2 unblocks your thread <em>after</em> the callback for the transfer has completed. Condition 3 is important because it means that the thread that was previously handling events is no longer doing so, so if any events are to complete, another thread needs to step up and start event handling.</p>
<p>This function releases the event waiters lock before putting your thread to sleep, and reacquires the lock as it is being woken up.</p>
<dl><dt><b>Parameters:</b></dt><dd>
<table border="0" cellspacing="2" cellpadding="0">
<tr><td valign="top"></td><td valign="top"><em>ctx</em> </td><td>the context to operate on, or NULL for the default context </td></tr>
<tr><td valign="top"></td><td valign="top"><em>tv</em> </td><td>maximum timeout for this blocking function. A NULL value indicates unlimited timeout. </td></tr>
</table>
</dd>
</dl>
<dl class="return"><dt><b>Returns:</b></dt><dd>0 after a transfer completes or another thread stops event handling </dd>
<dd>
1 if the timeout expired </dd></dl>
<dl class="see"><dt><b>See also:</b></dt><dd><a class="el" href="mtasync.html">Multi-threaded applications and asynchronous I/O</a> </dd></dl>
</div>
</div>
<a class="anchor" id="ga6deff4c7d3a6c04bb9ec9fd259b48933"></a><!-- doxytag: member="io.c::libusb_handle_events_timeout" ref="ga6deff4c7d3a6c04bb9ec9fd259b48933" args="(libusb_context *ctx, struct timeval *tv)" -->
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">int libusb_handle_events_timeout </td>
<td>(</td>
<td class="paramtype"><a class="el" href="group__lib.html#ga4ec088aa7b79c4a9599e39bf36a72833">libusb_context</a> * </td>
<td class="paramname"> <em>ctx</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">struct timeval * </td>
<td class="paramname"> <em>tv</em></td><td> </td>
</tr>
<tr>
<td></td>
<td>)</td>
<td></td><td></td><td></td>
</tr>
</table>
</div>
<div class="memdoc">
<p>Handle any pending events. </p>
<p>libusb determines "pending events" by checking if any timeouts have expired and by checking the set of file descriptors for activity.</p>
<p>If a zero timeval is passed, this function will handle any already-pending events and then immediately return in non-blocking style.</p>
<p>If a non-zero timeval is passed and no events are currently pending, this function will block waiting for events to handle up until the specified timeout. If an event arrives or a signal is raised, this function will return early.</p>
<dl><dt><b>Parameters:</b></dt><dd>
<table border="0" cellspacing="2" cellpadding="0">
<tr><td valign="top"></td><td valign="top"><em>ctx</em> </td><td>the context to operate on, or NULL for the default context </td></tr>
<tr><td valign="top"></td><td valign="top"><em>tv</em> </td><td>the maximum time to block waiting for events, or zero for non-blocking mode </td></tr>
</table>
</dd>
</dl>
<dl class="return"><dt><b>Returns:</b></dt><dd>0 on success, or a LIBUSB_ERROR code on failure </dd></dl>
</div>
</div>
<a class="anchor" id="ga4989086e3f0327f3886a4c474ec7c327"></a><!-- doxytag: member="io.c::libusb_handle_events" ref="ga4989086e3f0327f3886a4c474ec7c327" args="(libusb_context *ctx)" -->
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">int libusb_handle_events </td>
<td>(</td>
<td class="paramtype"><a class="el" href="group__lib.html#ga4ec088aa7b79c4a9599e39bf36a72833">libusb_context</a> * </td>
<td class="paramname"> <em>ctx</em></td>
<td> ) </td>
<td></td>
</tr>
</table>
</div>
<div class="memdoc">
<p>Handle any pending events in blocking mode. </p>
<p>There is currently a timeout hardcoded at 60 seconds but we plan to make it unlimited in future. For finer control over whether this function is blocking or non-blocking, or for control over the timeout, use <a class="el" href="group__poll.html#ga6deff4c7d3a6c04bb9ec9fd259b48933" title="Handle any pending events.">libusb_handle_events_timeout()</a> instead.</p>
<dl><dt><b>Parameters:</b></dt><dd>
<table border="0" cellspacing="2" cellpadding="0">
<tr><td valign="top"></td><td valign="top"><em>ctx</em> </td><td>the context to operate on, or NULL for the default context </td></tr>
</table>
</dd>
</dl>
<dl class="return"><dt><b>Returns:</b></dt><dd>0 on success, or a LIBUSB_ERROR code on failure </dd></dl>
</div>
</div>
<a class="anchor" id="ga71da081f97afa3bf68aed8e372254e8f"></a><!-- doxytag: member="io.c::libusb_handle_events_locked" ref="ga71da081f97afa3bf68aed8e372254e8f" args="(libusb_context *ctx, struct timeval *tv)" -->
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">int libusb_handle_events_locked </td>
<td>(</td>
<td class="paramtype"><a class="el" href="group__lib.html#ga4ec088aa7b79c4a9599e39bf36a72833">libusb_context</a> * </td>
<td class="paramname"> <em>ctx</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">struct timeval * </td>
<td class="paramname"> <em>tv</em></td><td> </td>
</tr>
<tr>
<td></td>
<td>)</td>
<td></td><td></td><td></td>
</tr>
</table>
</div>
<div class="memdoc">
<p>Handle any pending events by polling file descriptors, without checking if any other threads are already doing so. </p>
<p>Must be called with the event lock held, see <a class="el" href="group__poll.html#gaa72153938dc4f34decfacbc6cc6237ef" title="Acquire the event handling lock, blocking until successful acquisition if it is contended...">libusb_lock_events()</a>.</p>
<p>This function is designed to be called under the situation where you have taken the event lock and are calling poll()/select() directly on libusb's file descriptors (as opposed to using <a class="el" href="group__poll.html#ga4989086e3f0327f3886a4c474ec7c327" title="Handle any pending events in blocking mode.">libusb_handle_events()</a> or similar). You detect events on libusb's descriptors, so you then call this function with a zero timeout value (while still holding the event lock).</p>
<dl><dt><b>Parameters:</b></dt><dd>
<table border="0" cellspacing="2" cellpadding="0">
<tr><td valign="top"></td><td valign="top"><em>ctx</em> </td><td>the context to operate on, or NULL for the default context </td></tr>
<tr><td valign="top"></td><td valign="top"><em>tv</em> </td><td>the maximum time to block waiting for events, or zero for non-blocking mode </td></tr>
</table>
</dd>
</dl>
<dl class="return"><dt><b>Returns:</b></dt><dd>0 on success, or a LIBUSB_ERROR code on failure </dd></dl>
<dl class="see"><dt><b>See also:</b></dt><dd><a class="el" href="mtasync.html">Multi-threaded applications and asynchronous I/O</a> </dd></dl>
</div>
</div>
<a class="anchor" id="gae7a654315636bebf404c1784429f06df"></a><!-- doxytag: member="io.c::libusb_pollfds_handle_timeouts" ref="gae7a654315636bebf404c1784429f06df" args="(libusb_context *ctx)" -->
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">int libusb_pollfds_handle_timeouts </td>
<td>(</td>
<td class="paramtype"><a class="el" href="group__lib.html#ga4ec088aa7b79c4a9599e39bf36a72833">libusb_context</a> * </td>
<td class="paramname"> <em>ctx</em></td>
<td> ) </td>
<td></td>
</tr>
</table>
</div>
<div class="memdoc">
<p>Determines whether your application must apply special timing considerations when monitoring libusb's file descriptors. </p>
<p>This function is only useful for applications which retrieve and poll libusb's file descriptors in their own main loop (<a class="el" href="group__poll.html#pollmain">The more advanced option</a>).</p>
<p>Ordinarily, libusb's event handler needs to be called into at specific moments in time (in addition to times when there is activity on the file descriptor set). The usual approach is to use <a class="el" href="group__poll.html#ga5bc6f5bc71a43845244912da6679f634" title="Determine the next internal timeout that libusb needs to handle.">libusb_get_next_timeout()</a> to learn about when the next timeout occurs, and to adjust your poll()/select() timeout accordingly so that you can make a call into the library at that time.</p>
<p>Some platforms supported by libusb do not come with this baggage - any events relevant to timing will be represented by activity on the file descriptor set, and <a class="el" href="group__poll.html#ga5bc6f5bc71a43845244912da6679f634" title="Determine the next internal timeout that libusb needs to handle.">libusb_get_next_timeout()</a> will always return 0. This function allows you to detect whether you are running on such a platform.</p>
<p>Since v1.0.5.</p>
<dl><dt><b>Parameters:</b></dt><dd>
<table border="0" cellspacing="2" cellpadding="0">
<tr><td valign="top"></td><td valign="top"><em>ctx</em> </td><td>the context to operate on, or NULL for the default context </td></tr>
</table>
</dd>
</dl>
<dl class="return"><dt><b>Returns:</b></dt><dd>0 if you must call into libusb at times determined by <a class="el" href="group__poll.html#ga5bc6f5bc71a43845244912da6679f634" title="Determine the next internal timeout that libusb needs to handle.">libusb_get_next_timeout()</a>, or 1 if all timeout events are handled internally or through regular activity on the file descriptors. </dd></dl>
<dl class="see"><dt><b>See also:</b></dt><dd><a class="el" href="group__poll.html#pollmain">Polling libusb file descriptors for event handling</a> </dd></dl>
</div>
</div>
<a class="anchor" id="ga5bc6f5bc71a43845244912da6679f634"></a><!-- doxytag: member="io.c::libusb_get_next_timeout" ref="ga5bc6f5bc71a43845244912da6679f634" args="(libusb_context *ctx, struct timeval *tv)" -->
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">int libusb_get_next_timeout </td>
<td>(</td>
<td class="paramtype"><a class="el" href="group__lib.html#ga4ec088aa7b79c4a9599e39bf36a72833">libusb_context</a> * </td>
<td class="paramname"> <em>ctx</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">struct timeval * </td>
<td class="paramname"> <em>tv</em></td><td> </td>
</tr>
<tr>
<td></td>
<td>)</td>
<td></td><td></td><td></td>
</tr>
</table>
</div>
<div class="memdoc">
<p>Determine the next internal timeout that libusb needs to handle. </p>
<p>You only need to use this function if you are calling poll() or select() or similar on libusb's file descriptors yourself - you do not need to use it if you are calling <a class="el" href="group__poll.html#ga4989086e3f0327f3886a4c474ec7c327" title="Handle any pending events in blocking mode.">libusb_handle_events()</a> or a variant directly.</p>
<p>You should call this function in your main loop in order to determine how long to wait for select() or poll() to return results. libusb needs to be called into at this timeout, so you should use it as an upper bound on your select() or poll() call.</p>
<p>When the timeout has expired, call into <a class="el" href="group__poll.html#ga6deff4c7d3a6c04bb9ec9fd259b48933" title="Handle any pending events.">libusb_handle_events_timeout()</a> (perhaps in non-blocking mode) so that libusb can handle the timeout.</p>
<p>This function may return 1 (success) and an all-zero timeval. If this is the case, it indicates that libusb has a timeout that has already expired so you should call <a class="el" href="group__poll.html#ga6deff4c7d3a6c04bb9ec9fd259b48933" title="Handle any pending events.">libusb_handle_events_timeout()</a> or similar immediately. A return code of 0 indicates that there are no pending timeouts.</p>
<p>On some platforms, this function will always returns 0 (no pending timeouts). See <a class="el" href="group__poll.html#polltime">Notes on time-based events</a>.</p>
<dl><dt><b>Parameters:</b></dt><dd>
<table border="0" cellspacing="2" cellpadding="0">
<tr><td valign="top"></td><td valign="top"><em>ctx</em> </td><td>the context to operate on, or NULL for the default context </td></tr>
<tr><td valign="top"></td><td valign="top"><em>tv</em> </td><td>output location for a relative time against the current clock in which libusb must be called into in order to process timeout events </td></tr>
</table>
</dd>
</dl>
<dl class="return"><dt><b>Returns:</b></dt><dd>0 if there are no pending timeouts, 1 if a timeout was returned, or LIBUSB_ERROR_OTHER on failure </dd></dl>
</div>
</div>
<a class="anchor" id="ga1b7b2deb193f2e9ffda5e727361d7e67"></a><!-- doxytag: member="io.c::libusb_set_pollfd_notifiers" ref="ga1b7b2deb193f2e9ffda5e727361d7e67" args="(libusb_context *ctx, libusb_pollfd_added_cb added_cb, libusb_pollfd_removed_cb removed_cb, void *user_data)" -->
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">void libusb_set_pollfd_notifiers </td>
<td>(</td>
<td class="paramtype"><a class="el" href="group__lib.html#ga4ec088aa7b79c4a9599e39bf36a72833">libusb_context</a> * </td>
<td class="paramname"> <em>ctx</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype"><a class="el" href="group__poll.html#gabc8d353d64d262fa9f20ca01ba47dfcb">libusb_pollfd_added_cb</a> </td>
<td class="paramname"> <em>added_cb</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype"><a class="el" href="group__poll.html#gafb48e26cc97667f1891f6d27f2c81ef6">libusb_pollfd_removed_cb</a> </td>
<td class="paramname"> <em>removed_cb</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">void * </td>
<td class="paramname"> <em>user_data</em></td><td> </td>
</tr>
<tr>
<td></td>
<td>)</td>
<td></td><td></td><td></td>
</tr>
</table>
</div>
<div class="memdoc">
<p>Register notification functions for file descriptor additions/removals. </p>
<p>These functions will be invoked for every new or removed file descriptor that libusb uses as an event source.</p>
<p>To remove notifiers, pass NULL values for the function pointers.</p>
<p>Note that file descriptors may have been added even before you register these notifiers (e.g. at <a class="el" href="group__lib.html#ga9517c37281bba0b51cc62eba728be48b" title="Initialize libusb.">libusb_init()</a> time).</p>
<p>Additionally, note that the removal notifier may be called during <a class="el" href="group__lib.html#ga86532f222d4f1332a5f8f5eef9a92da9" title="Deinitialize libusb.">libusb_exit()</a> (e.g. when it is closing file descriptors that were opened and added to the poll set at <a class="el" href="group__lib.html#ga9517c37281bba0b51cc62eba728be48b" title="Initialize libusb.">libusb_init()</a> time). If you don't want this, remove the notifiers immediately before calling <a class="el" href="group__lib.html#ga86532f222d4f1332a5f8f5eef9a92da9" title="Deinitialize libusb.">libusb_exit()</a>.</p>
<dl><dt><b>Parameters:</b></dt><dd>
<table border="0" cellspacing="2" cellpadding="0">
<tr><td valign="top"></td><td valign="top"><em>ctx</em> </td><td>the context to operate on, or NULL for the default context </td></tr>
<tr><td valign="top"></td><td valign="top"><em>added_cb</em> </td><td>pointer to function for addition notifications </td></tr>
<tr><td valign="top"></td><td valign="top"><em>removed_cb</em> </td><td>pointer to function for removal notifications </td></tr>
<tr><td valign="top"></td><td valign="top"><em>user_data</em> </td><td>User data to be passed back to callbacks (useful for passing context information) </td></tr>
</table>
</dd>
</dl>
</div>
</div>
<a class="anchor" id="gab1a72869a926552b27a6c667695df3a2"></a><!-- doxytag: member="io.c::libusb_get_pollfds" ref="gab1a72869a926552b27a6c667695df3a2" args="(libusb_context *ctx)" -->
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">struct <a class="el" href="structlibusb__pollfd.html">libusb_pollfd</a>** libusb_get_pollfds </td>
<td>(</td>
<td class="paramtype"><a class="el" href="group__lib.html#ga4ec088aa7b79c4a9599e39bf36a72833">libusb_context</a> * </td>
<td class="paramname"> <em>ctx</em></td>
<td> ) </td>
<td><code> [read]</code></td>
</tr>
</table>
</div>
<div class="memdoc">
<p>Retrieve a list of file descriptors that should be polled by your main loop as libusb event sources. </p>
<p>The returned list is NULL-terminated and should be freed with free() when done. The actual list contents must not be touched.</p>
<dl><dt><b>Parameters:</b></dt><dd>
<table border="0" cellspacing="2" cellpadding="0">
<tr><td valign="top"></td><td valign="top"><em>ctx</em> </td><td>the context to operate on, or NULL for the default context </td></tr>
</table>
</dd>
</dl>
<dl class="return"><dt><b>Returns:</b></dt><dd>a NULL-terminated list of <a class="el" href="structlibusb__pollfd.html" title="File descriptor for polling.">libusb_pollfd</a> structures, or NULL on error </dd></dl>
</div>
</div>
</div>
<hr class="footer"/><address style="text-align: right;"><small>Generated on Wed Apr 28 09:03:59 2010 for libusb by
<a href="http://www.doxygen.org/index.html">
<img class="footer" src="doxygen.png" alt="doxygen"/></a> 1.6.3 </small></address>
</body>
</html>
