<!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>libusbx-1.0 API Reference</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 class="current"><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><!-- top -->
<div class="header">
<div class="headertitle">
<div class="title">libusbx-1.0 API Reference </div> </div>
</div><!--header-->
<div class="contents">
<div class="textblock"><h1><a class="anchor" id="intro"></a>
Introduction</h1>
<p>libusbx is an open source library that allows you to communicate with USB devices from userspace. For more info, see the <a href="http://libusbx.org">libusbx homepage</a>.</p>
<p>This documentation is aimed at application developers wishing to communicate with USB peripherals from their own software. After reviewing this documentation, feedback and questions can be sent to the <a href="http://mailing-list.libusbx.org">libusbx-devel mailing list</a>.</p>
<p>This documentation assumes knowledge of how to operate USB devices from a software standpoint (descriptors, configurations, interfaces, endpoints, control/bulk/interrupt/isochronous transfers, etc). Full information can be found in the <a href="http://www.usb.org/developers/docs/">USB 3.0 Specification</a> which is available for free download. You can probably find less verbose introductions by searching the web.</p>
<h1><a class="anchor" id="features"></a>
Library features</h1>
<ul>
<li>All transfer types supported (control/bulk/interrupt/isochronous)</li>
<li>2 transfer interfaces:<ol type="1">
<li>Synchronous (simple)</li>
<li>Asynchronous (more complicated, but more powerful)</li>
</ol>
</li>
<li>Thread safe (although the asynchronous interface means that you usually won't need to thread)</li>
<li>Lightweight with lean API</li>
<li>Compatible with libusb-0.1 through the libusb-compat-0.1 translation layer</li>
<li>Hotplug support (on some platforms). See <a class="el" href="hotplug.html">Device hotplug event notification</a>.</li>
</ul>
<h1><a class="anchor" id="gettingstarted"></a>
Getting Started</h1>
<p>To begin reading the API documentation, start with the Modules page which links to the different categories of libusbx's functionality.</p>
<p>One decision you will have to make is whether to use the synchronous or the asynchronous data transfer interface. The <a class="el" href="io.html">Synchronous and asynchronous device I/O</a> documentation provides some insight into this topic.</p>
<p>Some example programs can be found in the libusbx source distribution under the "examples" subdirectory. The libusbx homepage includes a list of real-life project examples which use libusbx.</p>
<h1><a class="anchor" id="errorhandling"></a>
Error handling</h1>
<p>libusbx functions typically return 0 on success or a negative error code on failure. These negative error codes relate to LIBUSB_ERROR constants which are listed on the <a class="el" href="group__misc.html">miscellaneous</a> documentation page.</p>
<h1><a class="anchor" id="msglog"></a>
Debug message logging</h1>
<p>libusbx uses stderr for all logging. By default, logging is set to NONE, which means that no output will be produced. However, unless the library has been compiled with logging disabled, then any application calls to <a class="el" href="group__lib.html#ga5f8376b7a863a5a8d5b8824feb8a427a" title="Set log message verbosity. ">libusb_set_debug()</a>, or the setting of the environmental variable LIBUSB_DEBUG outside of the application, can result in logging being produced. Your application should therefore not close stderr, but instead direct it to the null device if its output is undesireable.</p>
<p>The <a class="el" href="group__lib.html#ga5f8376b7a863a5a8d5b8824feb8a427a" title="Set log message verbosity. ">libusb_set_debug()</a> function can be used to enable logging of certain messages. Under standard configuration, libusbx doesn't really log much so you are advised to use this function to enable all error/warning/ informational messages. It will help debug problems with your software.</p>
<p>The logged messages are unstructured. There is no one-to-one correspondence between messages being logged and success or failure return codes from libusbx functions. There is no format to the messages, so you should not try to capture or parse them. They are not and will not be localized. These messages are not intended to being passed to your application user; instead, you should interpret the error codes returned from libusbx functions and provide appropriate notification to the user. The messages are simply there to aid you as a programmer, and if you're confused because you're getting a strange error code from a libusbx function, enabling message logging may give you a suitable explanation.</p>
<p>The LIBUSB_DEBUG environment variable can be used to enable message logging at run-time. This environment variable should be set to a log level number, which is interpreted the same as the <a class="el" href="group__lib.html#ga5f8376b7a863a5a8d5b8824feb8a427a" title="Set log message verbosity. ">libusb_set_debug()</a> parameter. When this environment variable is set, the message logging verbosity level is fixed and <a class="el" href="group__lib.html#ga5f8376b7a863a5a8d5b8824feb8a427a" title="Set log message verbosity. ">libusb_set_debug()</a> effectively does nothing.</p>
<p>libusbx can be compiled without any logging functions, useful for embedded systems. In this case, <a class="el" href="group__lib.html#ga5f8376b7a863a5a8d5b8824feb8a427a" title="Set log message verbosity. ">libusb_set_debug()</a> and the LIBUSB_DEBUG environment variable have no effects.</p>
<p>libusbx can also be compiled with verbose debugging messages always. When the library is compiled in this way, all messages of all verbosities are always logged. <a class="el" href="group__lib.html#ga5f8376b7a863a5a8d5b8824feb8a427a" title="Set log message verbosity. ">libusb_set_debug()</a> and the LIBUSB_DEBUG environment variable have no effects.</p>
<h1><a class="anchor" id="remarks"></a>
Other remarks</h1>
<p>libusbx does have imperfections. The <a class="el" href="caveats.html">caveats</a> page attempts to document these. </p>
</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>
