-
Notifications
You must be signed in to change notification settings - Fork 0
/
Copy pathgroup__libusb__syncio.html
346 lines (338 loc) · 18.3 KB
/
group__libusb__syncio.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
<!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.13"/>
<meta name="viewport" content="width=device-width, initial-scale=1"/>
<title>libusb-1.0: Synchronous device I/O</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="search/search.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="search/searchdata.js"></script>
<script type="text/javascript" src="search/search.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 id="projectalign" style="padding-left: 0.5em;">
<div id="projectname">libusb-1.0
</div>
</td>
</tr>
</tbody>
</table>
</div>
<!-- end header part -->
<!-- Generated by Doxygen 1.8.13 -->
<script type="text/javascript">
var searchBox = new SearchBox("searchBox", "search",false,'Search');
</script>
<script type="text/javascript" src="menudata.js"></script>
<script type="text/javascript" src="menu.js"></script>
<script type="text/javascript">
$(function() {
initMenu('',true,false,'search.php','Search');
$(document).ready(function() { init_search(); });
});
</script>
<div id="main-nav"></div>
</div><!-- top -->
<!-- window showing the filter options -->
<div id="MSearchSelectWindow"
onmouseover="return searchBox.OnSearchSelectShow()"
onmouseout="return searchBox.OnSearchSelectHide()"
onkeydown="return searchBox.OnSearchSelectKey(event)">
</div>
<!-- iframe showing the search results (closed by default) -->
<div id="MSearchResultsWindow">
<iframe src="javascript:void(0)" frameborder="0"
name="MSearchResults" id="MSearchResults">
</iframe>
</div>
<div class="header">
<div class="summary">
<a href="#func-members">Functions</a> </div>
<div class="headertitle">
<div class="title">Synchronous device I/O</div> </div>
</div><!--header-->
<div class="contents">
<table class="memberdecls">
<tr class="heading"><td colspan="2"><h2 class="groupheader"><a name="func-members"></a>
Functions</h2></td></tr>
<tr class="memitem:ga21f4b1b8cba5747262b46a4b9a25872d"><td class="memItemLeft" align="right" valign="top">int API_EXPORTED </td><td class="memItemRight" valign="bottom"><a class="el" href="group__libusb__syncio.html#ga21f4b1b8cba5747262b46a4b9a25872d">libusb_control_transfer</a> (<a class="el" href="structlibusb__device__handle.html">libusb_device_handle</a> *dev_handle, uint8_t bmRequestType, uint8_t bRequest, uint16_t wValue, uint16_t wIndex, unsigned char *data, uint16_t wLength, unsigned int timeout)</td></tr>
<tr class="separator:ga21f4b1b8cba5747262b46a4b9a25872d"><td class="memSeparator" colspan="2"> </td></tr>
<tr class="memitem:ga62b7432a68aacc33f15087087f5a7743"><td class="memItemLeft" align="right" valign="top">int API_EXPORTED </td><td class="memItemRight" valign="bottom"><a class="el" href="group__libusb__syncio.html#ga62b7432a68aacc33f15087087f5a7743">libusb_bulk_transfer</a> (<a class="el" href="structlibusb__device__handle.html">libusb_device_handle</a> *dev_handle, unsigned char <a class="el" href="structendpoint.html">endpoint</a>, unsigned char *data, int length, int *transferred, unsigned int timeout)</td></tr>
<tr class="separator:ga62b7432a68aacc33f15087087f5a7743"><td class="memSeparator" colspan="2"> </td></tr>
<tr class="memitem:ga92d8946388c8f1edebb1399f5e3f84d7"><td class="memItemLeft" align="right" valign="top">int API_EXPORTED </td><td class="memItemRight" valign="bottom"><a class="el" href="group__libusb__syncio.html#ga92d8946388c8f1edebb1399f5e3f84d7">libusb_interrupt_transfer</a> (<a class="el" href="structlibusb__device__handle.html">libusb_device_handle</a> *dev_handle, unsigned char <a class="el" href="structendpoint.html">endpoint</a>, unsigned char *data, int length, int *transferred, unsigned int timeout)</td></tr>
<tr class="separator:ga92d8946388c8f1edebb1399f5e3f84d7"><td class="memSeparator" colspan="2"> </td></tr>
</table>
<a name="details" id="details"></a><h2 class="groupheader">Detailed Description</h2>
<p>This page documents libusb's synchronous (blocking) API for USB device I/O. This interface is easy to use but has some limitations. More advanced users may wish to consider using the <a class="el" href="group__libusb__asyncio.html">asynchronous I/O API</a> instead. </p>
<h2 class="groupheader">Function Documentation</h2>
<a id="ga62b7432a68aacc33f15087087f5a7743"></a>
<h2 class="memtitle"><span class="permalink"><a href="#ga62b7432a68aacc33f15087087f5a7743">◆ </a></span>libusb_bulk_transfer()</h2>
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">int API_EXPORTED libusb_bulk_transfer </td>
<td>(</td>
<td class="paramtype"><a class="el" href="structlibusb__device__handle.html">libusb_device_handle</a> * </td>
<td class="paramname"><em>dev_handle</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">unsigned char </td>
<td class="paramname"><em>endpoint</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">unsigned char * </td>
<td class="paramname"><em>data</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">int </td>
<td class="paramname"><em>length</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">int * </td>
<td class="paramname"><em>transferred</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">unsigned int </td>
<td class="paramname"><em>timeout</em> </td>
</tr>
<tr>
<td></td>
<td>)</td>
<td></td><td></td>
</tr>
</table>
</div><div class="memdoc">
<p>Perform a USB bulk transfer. The direction of the transfer is inferred from the direction bits of the endpoint address.</p>
<p>For bulk reads, the <code>length</code> field indicates the maximum length of data you are expecting to receive. If less data arrives than expected, this function will return that data, so be sure to check the <code>transferred</code> output parameter.</p>
<p>You should also check the <code>transferred</code> parameter for bulk writes. Not all of the data may have been written.</p>
<p>Also check <code>transferred</code> when dealing with a timeout error code. libusb may have to split your transfer into a number of chunks to satisfy underlying O/S requirements, meaning that the timeout may expire after the first few chunks have completed. libusb is careful not to lose any data that may have been transferred; do not assume that timeout conditions indicate a complete lack of I/O. See <a class="el" href="group__libusb__asyncio.html#asynctimeout">Timeouts</a> for more details.</p>
<dl class="params"><dt>Parameters</dt><dd>
<table class="params">
<tr><td class="paramname">dev_handle</td><td>a handle for the device to communicate with </td></tr>
<tr><td class="paramname">endpoint</td><td>the address of a valid endpoint to communicate with </td></tr>
<tr><td class="paramname">data</td><td>a suitably-sized data buffer for either input or output (depending on endpoint) </td></tr>
<tr><td class="paramname">length</td><td>for bulk writes, the number of bytes from data to be sent. for bulk reads, the maximum number of bytes to receive into the data buffer. </td></tr>
<tr><td class="paramname">transferred</td><td>output location for the number of bytes actually transferred. Since version 1.0.21 (<a class="el" href="group__libusb__misc.html#gaabe4bc36a83358685d36a6c853cbb4de">LIBUSB_API_VERSION</a> >= 0x01000105), it is legal to pass a NULL pointer if you do not wish to receive this information. </td></tr>
<tr><td class="paramname">timeout</td><td>timeout (in milliseconds) that this function should wait before giving up due to no response being received. For an unlimited timeout, use value 0.</td></tr>
</table>
</dd>
</dl>
<dl class="section return"><dt>Returns</dt><dd>0 on success (and populates <code>transferred</code>) </dd>
<dd>
LIBUSB_ERROR_TIMEOUT if the transfer timed out (and populates <code>transferred</code>) </dd>
<dd>
LIBUSB_ERROR_PIPE if the endpoint halted </dd>
<dd>
LIBUSB_ERROR_OVERFLOW if the device offered more data, see <a class="el" href="libusb_packetoverflow.html">Packets and overflows</a> </dd>
<dd>
LIBUSB_ERROR_NO_DEVICE if the device has been disconnected </dd>
<dd>
LIBUSB_ERROR_BUSY if called from event handling context </dd>
<dd>
LIBUSB_ERROR_INVALID_PARAM if the transfer size is larger than the operating system and/or hardware can support (see <a class="el" href="group__libusb__asyncio.html#asynclimits">Transfer length limitations</a>) </dd>
<dd>
another LIBUSB_ERROR code on other failures </dd></dl>
</div>
</div>
<a id="ga21f4b1b8cba5747262b46a4b9a25872d"></a>
<h2 class="memtitle"><span class="permalink"><a href="#ga21f4b1b8cba5747262b46a4b9a25872d">◆ </a></span>libusb_control_transfer()</h2>
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">int API_EXPORTED libusb_control_transfer </td>
<td>(</td>
<td class="paramtype"><a class="el" href="structlibusb__device__handle.html">libusb_device_handle</a> * </td>
<td class="paramname"><em>dev_handle</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">uint8_t </td>
<td class="paramname"><em>bmRequestType</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">uint8_t </td>
<td class="paramname"><em>bRequest</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">uint16_t </td>
<td class="paramname"><em>wValue</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">uint16_t </td>
<td class="paramname"><em>wIndex</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">unsigned char * </td>
<td class="paramname"><em>data</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">uint16_t </td>
<td class="paramname"><em>wLength</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">unsigned int </td>
<td class="paramname"><em>timeout</em> </td>
</tr>
<tr>
<td></td>
<td>)</td>
<td></td><td></td>
</tr>
</table>
</div><div class="memdoc">
<p>Perform a USB control transfer.</p>
<p>The direction of the transfer is inferred from the bmRequestType field of the setup packet.</p>
<p>The wValue, wIndex and wLength fields values should be given in host-endian byte order.</p>
<dl class="params"><dt>Parameters</dt><dd>
<table class="params">
<tr><td class="paramname">dev_handle</td><td>a handle for the device to communicate with </td></tr>
<tr><td class="paramname">bmRequestType</td><td>the request type field for the setup packet </td></tr>
<tr><td class="paramname">bRequest</td><td>the request field for the setup packet </td></tr>
<tr><td class="paramname">wValue</td><td>the value field for the setup packet </td></tr>
<tr><td class="paramname">wIndex</td><td>the index field for the setup packet </td></tr>
<tr><td class="paramname">data</td><td>a suitably-sized data buffer for either input or output (depending on direction bits within bmRequestType) </td></tr>
<tr><td class="paramname">wLength</td><td>the length field for the setup packet. The data buffer should be at least this size. </td></tr>
<tr><td class="paramname">timeout</td><td>timeout (in milliseconds) that this function should wait before giving up due to no response being received. For an unlimited timeout, use value 0. </td></tr>
</table>
</dd>
</dl>
<dl class="section return"><dt>Returns</dt><dd>on success, the number of bytes actually transferred </dd>
<dd>
LIBUSB_ERROR_TIMEOUT if the transfer timed out </dd>
<dd>
LIBUSB_ERROR_PIPE if the control request was not supported by the device </dd>
<dd>
LIBUSB_ERROR_NO_DEVICE if the device has been disconnected </dd>
<dd>
LIBUSB_ERROR_BUSY if called from event handling context </dd>
<dd>
LIBUSB_ERROR_INVALID_PARAM if the transfer size is larger than the operating system and/or hardware can support (see <a class="el" href="group__libusb__asyncio.html#asynclimits">Transfer length limitations</a>) </dd>
<dd>
another LIBUSB_ERROR code on other failures </dd></dl>
</div>
</div>
<a id="ga92d8946388c8f1edebb1399f5e3f84d7"></a>
<h2 class="memtitle"><span class="permalink"><a href="#ga92d8946388c8f1edebb1399f5e3f84d7">◆ </a></span>libusb_interrupt_transfer()</h2>
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">int API_EXPORTED libusb_interrupt_transfer </td>
<td>(</td>
<td class="paramtype"><a class="el" href="structlibusb__device__handle.html">libusb_device_handle</a> * </td>
<td class="paramname"><em>dev_handle</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">unsigned char </td>
<td class="paramname"><em>endpoint</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">unsigned char * </td>
<td class="paramname"><em>data</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">int </td>
<td class="paramname"><em>length</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">int * </td>
<td class="paramname"><em>transferred</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">unsigned int </td>
<td class="paramname"><em>timeout</em> </td>
</tr>
<tr>
<td></td>
<td>)</td>
<td></td><td></td>
</tr>
</table>
</div><div class="memdoc">
<p>Perform a USB interrupt transfer. The direction of the transfer is inferred from the direction bits of the endpoint address.</p>
<p>For interrupt reads, the <code>length</code> field indicates the maximum length of data you are expecting to receive. If less data arrives than expected, this function will return that data, so be sure to check the <code>transferred</code> output parameter.</p>
<p>You should also check the <code>transferred</code> parameter for interrupt writes. Not all of the data may have been written.</p>
<p>Also check <code>transferred</code> when dealing with a timeout error code. libusb may have to split your transfer into a number of chunks to satisfy underlying O/S requirements, meaning that the timeout may expire after the first few chunks have completed. libusb is careful not to lose any data that may have been transferred; do not assume that timeout conditions indicate a complete lack of I/O. See <a class="el" href="group__libusb__asyncio.html#asynctimeout">Timeouts</a> for more details.</p>
<p>The default endpoint bInterval value is used as the polling interval.</p>
<dl class="params"><dt>Parameters</dt><dd>
<table class="params">
<tr><td class="paramname">dev_handle</td><td>a handle for the device to communicate with </td></tr>
<tr><td class="paramname">endpoint</td><td>the address of a valid endpoint to communicate with </td></tr>
<tr><td class="paramname">data</td><td>a suitably-sized data buffer for either input or output (depending on endpoint) </td></tr>
<tr><td class="paramname">length</td><td>for bulk writes, the number of bytes from data to be sent. for bulk reads, the maximum number of bytes to receive into the data buffer. </td></tr>
<tr><td class="paramname">transferred</td><td>output location for the number of bytes actually transferred. Since version 1.0.21 (<a class="el" href="group__libusb__misc.html#gaabe4bc36a83358685d36a6c853cbb4de">LIBUSB_API_VERSION</a> >= 0x01000105), it is legal to pass a NULL pointer if you do not wish to receive this information. </td></tr>
<tr><td class="paramname">timeout</td><td>timeout (in milliseconds) that this function should wait before giving up due to no response being received. For an unlimited timeout, use value 0.</td></tr>
</table>
</dd>
</dl>
<dl class="section return"><dt>Returns</dt><dd>0 on success (and populates <code>transferred</code>) </dd>
<dd>
LIBUSB_ERROR_TIMEOUT if the transfer timed out </dd>
<dd>
LIBUSB_ERROR_PIPE if the endpoint halted </dd>
<dd>
LIBUSB_ERROR_OVERFLOW if the device offered more data, see <a class="el" href="libusb_packetoverflow.html">Packets and overflows</a> </dd>
<dd>
LIBUSB_ERROR_NO_DEVICE if the device has been disconnected </dd>
<dd>
LIBUSB_ERROR_BUSY if called from event handling context </dd>
<dd>
LIBUSB_ERROR_INVALID_PARAM if the transfer size is larger than the operating system and/or hardware can support (see <a class="el" href="group__libusb__asyncio.html#asynclimits">Transfer length limitations</a>) </dd>
<dd>
another LIBUSB_ERROR code on other error </dd></dl>
</div>
</div>
</div><!-- contents -->
<!-- start footer part -->
<hr class="footer"/><address class="footer"><small>
Generated by  <a href="http://www.doxygen.org/index.html">
<img class="footer" src="doxygen.png" alt="doxygen"/>
</a> 1.8.13
</small></address>
</body>
</html>