<!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"/>
<meta http-equiv="X-UA-Compatible" content="IE=9"/>
<meta name="generator" content="Doxygen 1.8.5"/>
<title>Device hotplug event notification</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="jquery.js"></script>
<script type="text/javascript" src="dynsections.js"></script>
<link href="doxygen.css" rel="stylesheet" type="text/css" />
</head>
<body>
<div id="top"><!-- do not remove this div, it is closed by doxygen! -->
<div id="titlearea">
<table cellspacing="0" cellpadding="0">
<tbody>
<tr style="height: 56px;">
<td style="padding-left: 0.5em;">
<div id="projectbrief">eXpand your USB potential</div>
</td>
</tr>
</tbody>
</table>
</div>
<!-- end header part -->
<!-- Generated by Doxygen 1.8.5 -->
<div id="navrow1" class="tabs">
<ul class="tablist">
<li><a href="index.html"><span>Main Page</span></a></li>
<li class="current"><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><!-- top -->
<div class="header">
<div class="headertitle">
<div class="title">Device hotplug event notification </div> </div>
</div><!--header-->
<div class="contents">
<div class="textblock"><h1><a class="anchor" id="intro"></a>
Introduction</h1>
<p>Version 1.0.16, <a class="el" href="group__misc.html#gaa83ecded256e0767220bcc21cc92365d">LIBUSBX_API_VERSION</a> >= 0x01000102, has added support for hotplug events on <b>some</b> platforms (you should test if your platform supports hotplug notification by calling <a class="el" href="group__misc.html#ga9b8e324d28c624cd0b8e7ba21607b8db">libusb_has_capability()</a> with parameter <a class="el" href="group__misc.html#ggaab1b3fa0728c06fafbee897795889bd5a8b1bbccc648a6677cb9030a6ba827438">LIBUSB_CAP_HAS_HOTPLUG</a>).</p>
<p>This interface allows you to request notification for the arrival and departure of matching USB devices.</p>
<p>To receive hotplug notification you register a callback by calling <a class="el" href="group__hotplug.html#gae6c5f1add6cc754005549c7259dc35ea">libusb_hotplug_register_callback()</a>. This function will optionally return a handle that can be passed to <a class="el" href="group__hotplug.html#ga3d038cee3d9d96c4c4daf811f05f6ad3">libusb_hotplug_deregister_callback()</a>.</p>
<p>A callback function must return an int (0 or 1) indicating whether the callback is expecting additional events. Returning 0 will rearm the callback and 1 will cause the callback to be deregistered. Note that when callbacks are called from <a class="el" href="group__hotplug.html#gae6c5f1add6cc754005549c7259dc35ea" title="Register a hotplug callback function. ">libusb_hotplug_register_callback()</a> because of the <a class="el" href="group__hotplug.html#gga95ce2ec85dec177854c423cea2853c52a01a1c0c9f4e6852cb6df713f2e8a7f6b">LIBUSB_HOTPLUG_ENUMERATE</a> flag, the callback return value is ignored, iow you cannot cause a callback to be deregistered by returning 1 when it is called from <a class="el" href="group__hotplug.html#gae6c5f1add6cc754005549c7259dc35ea" title="Register a hotplug callback function. ">libusb_hotplug_register_callback()</a>.</p>
<p>Callbacks for a particular context are automatically deregistered by <a class="el" href="group__lib.html#ga86532f222d4f1332a5f8f5eef9a92da9" title="Deinitialize libusb. ">libusb_exit()</a>.</p>
<p>As of 1.0.16 there are two supported hotplug events:</p>
<ul>
<li>LIBUSB_HOTPLUG_EVENT_DEVICE_ARRIVED: A device has arrived and is ready to use</li>
<li>LIBUSB_HOTPLUG_EVENT_DEVICE_LEFT: A device has left and is no longer available</li>
</ul>
<p>A hotplug event can listen for either or both of these events.</p>
<p>Note: If you receive notification that a device has left and you have any a libusb_device_handles for the device it is up to you to call <a class="el" href="group__dev.html#ga779bc4f1316bdb0ac383bddbd538620e" title="Close a device handle. ">libusb_close()</a> on each handle to free up any remaining resources associated with the device. Once a device has left any libusb_device_handle associated with the device are invalid and will remain so even if the device comes back.</p>
<p>When handling a LIBUSB_HOTPLUG_EVENT_DEVICE_ARRIVED event it is considered safe to call any libusbx function that takes a libusb_device. On the other hand, when handling a LIBUSB_HOTPLUG_EVENT_DEVICE_LEFT event the only safe function is <a class="el" href="group__desc.html#ga5e9ab08d490a7704cf3a9b0439f16f00" title="Get the USB device descriptor for a given device. ">libusb_get_device_descriptor()</a>.</p>
<p>The following code provides an example of the usage of the hotplug interface: </p>
<div class="fragment"><div class="line"><span class="keyword">static</span> <span class="keywordtype">int</span> count = 0;</div>
<div class="line"></div>
<div class="line"><span class="keywordtype">int</span> hotplug_callback(<span class="keyword">struct</span> <a class="code" href="group__lib.html#ga4ec088aa7b79c4a9599e39bf36a72833">libusb_context</a> *ctx, <span class="keyword">struct</span> <a class="code" href="group__dev.html#ga77eedd00d01eb7569b880e861a971c2b">libusb_device</a> *dev,</div>
<div class="line"> <a class="code" href="group__hotplug.html#ga556d598ca379618a41bbec3597f55dcf">libusb_hotplug_event</a> event, <span class="keywordtype">void</span> *user_data) {</div>
<div class="line"> <span class="keyword">static</span> <a class="code" href="group__dev.html#ga7df95821d20d27b5597f1d783749d6a4">libusb_device_handle</a> *handle = NULL;</div>
<div class="line"> <span class="keyword">struct </span><a class="code" href="structlibusb__device__descriptor.html">libusb_device_descriptor</a> desc;</div>
<div class="line"> <span class="keywordtype">int</span> rc;</div>
<div class="line"></div>
<div class="line"> (void)<a class="code" href="group__desc.html#ga5e9ab08d490a7704cf3a9b0439f16f00">libusb_get_device_descriptor</a>(dev, &desc);</div>
<div class="line"></div>
<div class="line"> <span class="keywordflow">if</span> (<a class="code" href="group__hotplug.html#gga556d598ca379618a41bbec3597f55dcfac012270cba6e08dafe7e3bec204dffd6">LIBUSB_HOTPLUG_EVENT_DEVICE_ARRIVED</a> == event) {</div>
<div class="line"> rc = <a class="code" href="group__dev.html#ga8163100afdf933fabed0db7fa81c89d1">libusb_open</a>(dev, &handle);</div>
<div class="line"> <span class="keywordflow">if</span> (<a class="code" href="group__misc.html#ggab2323aa0f04bc22038e7e1740b2f29efa576d8d63f6e24b2e57cb2ca63b304f15">LIBUSB_SUCCESS</a> != rc) {</div>
<div class="line"> printf(<span class="stringliteral">"Could not open USB device\n"</span>);</div>
<div class="line"> }</div>
<div class="line"> } <span class="keywordflow">else</span> <span class="keywordflow">if</span> (<a class="code" href="group__hotplug.html#gga556d598ca379618a41bbec3597f55dcfac8234e02b673893ed549329ef3180a27">LIBUSB_HOTPLUG_EVENT_DEVICE_LEFT</a> == event) {</div>
<div class="line"> <span class="keywordflow">if</span> (handle) {</div>
<div class="line"> <a class="code" href="group__dev.html#ga779bc4f1316bdb0ac383bddbd538620e">libusb_close</a>(handle);</div>
<div class="line"> handle = NULL;</div>
<div class="line"> }</div>
<div class="line"> } <span class="keywordflow">else</span> {</div>
<div class="line"> printf(<span class="stringliteral">"Unhandled event %d\n"</span>, event);</div>
<div class="line"> }</div>
<div class="line"> count++;</div>
<div class="line"></div>
<div class="line"> <span class="keywordflow">return</span> 0;</div>
<div class="line">}</div>
<div class="line"></div>
<div class="line"><span class="keywordtype">int</span> main (<span class="keywordtype">void</span>) {</div>
<div class="line"> <a class="code" href="group__hotplug.html#ga4868157346bbf2c70b6af0cb0a6c0094">libusb_hotplug_callback_handle</a> handle;</div>
<div class="line"> <span class="keywordtype">int</span> rc;</div>
<div class="line"></div>
<div class="line"> <a class="code" href="group__lib.html#ga9517c37281bba0b51cc62eba728be48b">libusb_init</a>(NULL);</div>
<div class="line"></div>
<div class="line"> rc = <a class="code" href="group__hotplug.html#gae6c5f1add6cc754005549c7259dc35ea">libusb_hotplug_register_callback</a>(NULL, <a class="code" href="group__hotplug.html#gga556d598ca379618a41bbec3597f55dcfac012270cba6e08dafe7e3bec204dffd6">LIBUSB_HOTPLUG_EVENT_DEVICE_ARRIVED</a> |</div>
<div class="line"> <a class="code" href="group__hotplug.html#gga556d598ca379618a41bbec3597f55dcfac8234e02b673893ed549329ef3180a27">LIBUSB_HOTPLUG_EVENT_DEVICE_LEFT</a>, 0, 0x045a, 0x5005,</div>
<div class="line"> <a class="code" href="group__hotplug.html#ga6d4f5e524a3b7ab4a25b751073335d4c">LIBUSB_HOTPLUG_MATCH_ANY</a>, hotplug_callback, NULL,</div>
<div class="line"> &handle);</div>
<div class="line"> <span class="keywordflow">if</span> (<a class="code" href="group__misc.html#ggab2323aa0f04bc22038e7e1740b2f29efa576d8d63f6e24b2e57cb2ca63b304f15">LIBUSB_SUCCESS</a> != rc) {</div>
<div class="line"> printf(<span class="stringliteral">"Error creating a hotplug callback\n"</span>);</div>
<div class="line"> <a class="code" href="group__lib.html#ga86532f222d4f1332a5f8f5eef9a92da9">libusb_exit</a>(NULL);</div>
<div class="line"> <span class="keywordflow">return</span> EXIT_FAILURE;</div>
<div class="line"> }</div>
<div class="line"></div>
<div class="line"> <span class="keywordflow">while</span> (count < 2) {</div>
<div class="line"> usleep(10000);</div>
<div class="line"> }</div>
<div class="line"></div>
<div class="line"> <a class="code" href="group__hotplug.html#ga3d038cee3d9d96c4c4daf811f05f6ad3">libusb_hotplug_deregister_callback</a>(handle);</div>
<div class="line"> <a class="code" href="group__lib.html#ga86532f222d4f1332a5f8f5eef9a92da9">libusb_exit</a>(NULL);</div>
<div class="line"></div>
<div class="line"> <span class="keywordflow">return</span> 0;</div>
<div class="line">}</div>
</div><!-- fragment --> </div></div><!-- contents -->
<!-- start footer part -->
<hr class="footer"/><address class="footer"><small>
Generated on Sat Oct 19 2013 16:44:34 by  <a href="http://www.doxygen.org/index.html">
<img class="footer" src="doxygen.png" alt="doxygen"/>
</a> 1.8.5
</small></address>
</body>
</html>
