2 * Synchronous I/O functions for libusbx
3 * Copyright © 2007-2008 Daniel Drake <dsd@gentoo.org>
5 * This library is free software; you can redistribute it and/or
6 * modify it under the terms of the GNU Lesser General Public
7 * License as published by the Free Software Foundation; either
8 * version 2.1 of the License, or (at your option) any later version.
10 * This library is distributed in the hope that it will be useful,
11 * but WITHOUT ANY WARRANTY; without even the implied warranty of
12 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
13 * Lesser General Public License for more details.
15 * You should have received a copy of the GNU Lesser General Public
16 * License along with this library; if not, write to the Free Software
17 * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
29 * @defgroup syncio Synchronous device I/O
31 * This page documents libusbx's synchronous (blocking) API for USB device I/O.
32 * This interface is easy to use but has some limitations. More advanced users
33 * may wish to consider using the \ref asyncio "asynchronous I/O API" instead.
36 static void LIBUSB_CALL ctrl_transfer_cb(struct libusb_transfer *transfer)
38 int *completed = transfer->user_data;
40 usbi_dbg("actual_length=%d", transfer->actual_length);
41 /* caller interprets result and frees transfer */
45 * Perform a USB control transfer.
47 * The direction of the transfer is inferred from the bmRequestType field of
50 * The wValue, wIndex and wLength fields values should be given in host-endian
53 * \param dev_handle a handle for the device to communicate with
54 * \param bmRequestType the request type field for the setup packet
55 * \param bRequest the request field for the setup packet
56 * \param wValue the value field for the setup packet
57 * \param wIndex the index field for the setup packet
58 * \param data a suitably-sized data buffer for either input or output
59 * (depending on direction bits within bmRequestType)
60 * \param wLength the length field for the setup packet. The data buffer should
61 * be at least this size.
62 * \param timeout timeout (in millseconds) that this function should wait
63 * before giving up due to no response being received. For an unlimited
64 * timeout, use value 0.
65 * \returns on success, the number of bytes actually transferred
66 * \returns LIBUSB_ERROR_TIMEOUT if the transfer timed out
67 * \returns LIBUSB_ERROR_PIPE if the control request was not supported by the
69 * \returns LIBUSB_ERROR_NO_DEVICE if the device has been disconnected
70 * \returns another LIBUSB_ERROR code on other failures
72 int API_EXPORTED libusb_control_transfer(libusb_device_handle *dev_handle,
73 uint8_t bmRequestType, uint8_t bRequest, uint16_t wValue, uint16_t wIndex,
74 unsigned char *data, uint16_t wLength, unsigned int timeout)
76 struct libusb_transfer *transfer = libusb_alloc_transfer(0);
77 unsigned char *buffer;
82 return LIBUSB_ERROR_NO_MEM;
84 buffer = (unsigned char*) malloc(LIBUSB_CONTROL_SETUP_SIZE + wLength);
86 libusb_free_transfer(transfer);
87 return LIBUSB_ERROR_NO_MEM;
90 libusb_fill_control_setup(buffer, bmRequestType, bRequest, wValue, wIndex,
92 if ((bmRequestType & LIBUSB_ENDPOINT_DIR_MASK) == LIBUSB_ENDPOINT_OUT)
93 memcpy(buffer + LIBUSB_CONTROL_SETUP_SIZE, data, wLength);
95 libusb_fill_control_transfer(transfer, dev_handle, buffer,
96 ctrl_transfer_cb, &completed, timeout);
97 transfer->flags = LIBUSB_TRANSFER_FREE_BUFFER;
98 r = libusb_submit_transfer(transfer);
100 libusb_free_transfer(transfer);
105 r = libusb_handle_events_completed(HANDLE_CTX(dev_handle), &completed);
107 if (r == LIBUSB_ERROR_INTERRUPTED)
109 if (libusb_cancel_transfer(transfer) == LIBUSB_SUCCESS) {
111 if (libusb_handle_events_completed(HANDLE_CTX(dev_handle), &completed) < 0)
114 libusb_free_transfer(transfer);
119 if ((bmRequestType & LIBUSB_ENDPOINT_DIR_MASK) == LIBUSB_ENDPOINT_IN)
120 memcpy(data, libusb_control_transfer_get_data(transfer),
121 transfer->actual_length);
123 switch (transfer->status) {
124 case LIBUSB_TRANSFER_COMPLETED:
125 r = transfer->actual_length;
127 case LIBUSB_TRANSFER_TIMED_OUT:
128 r = LIBUSB_ERROR_TIMEOUT;
130 case LIBUSB_TRANSFER_STALL:
131 r = LIBUSB_ERROR_PIPE;
133 case LIBUSB_TRANSFER_NO_DEVICE:
134 r = LIBUSB_ERROR_NO_DEVICE;
136 case LIBUSB_TRANSFER_OVERFLOW:
137 r = LIBUSB_ERROR_OVERFLOW;
139 case LIBUSB_TRANSFER_ERROR:
140 case LIBUSB_TRANSFER_CANCELLED:
144 usbi_warn(HANDLE_CTX(dev_handle),
145 "unrecognised status code %d", transfer->status);
146 r = LIBUSB_ERROR_OTHER;
149 libusb_free_transfer(transfer);
153 static void LIBUSB_CALL bulk_transfer_cb(struct libusb_transfer *transfer)
155 int *completed = transfer->user_data;
157 usbi_dbg("actual_length=%d", transfer->actual_length);
158 /* caller interprets results and frees transfer */
161 static int do_sync_bulk_transfer(struct libusb_device_handle *dev_handle,
162 unsigned char endpoint, unsigned char *buffer, int length,
163 int *transferred, unsigned int timeout, unsigned char type)
165 struct libusb_transfer *transfer = libusb_alloc_transfer(0);
170 return LIBUSB_ERROR_NO_MEM;
172 libusb_fill_bulk_transfer(transfer, dev_handle, endpoint, buffer, length,
173 bulk_transfer_cb, &completed, timeout);
174 transfer->type = type;
176 r = libusb_submit_transfer(transfer);
178 libusb_free_transfer(transfer);
183 r = libusb_handle_events_completed(HANDLE_CTX(dev_handle), &completed);
185 if (r == LIBUSB_ERROR_INTERRUPTED)
187 if (libusb_cancel_transfer(transfer) == LIBUSB_SUCCESS) {
189 if (libusb_handle_events_completed(HANDLE_CTX(dev_handle), &completed) < 0)
192 libusb_free_transfer(transfer);
197 *transferred = transfer->actual_length;
198 switch (transfer->status) {
199 case LIBUSB_TRANSFER_COMPLETED:
202 case LIBUSB_TRANSFER_TIMED_OUT:
203 r = LIBUSB_ERROR_TIMEOUT;
205 case LIBUSB_TRANSFER_STALL:
206 r = LIBUSB_ERROR_PIPE;
208 case LIBUSB_TRANSFER_OVERFLOW:
209 r = LIBUSB_ERROR_OVERFLOW;
211 case LIBUSB_TRANSFER_NO_DEVICE:
212 r = LIBUSB_ERROR_NO_DEVICE;
214 case LIBUSB_TRANSFER_ERROR:
215 case LIBUSB_TRANSFER_CANCELLED:
219 usbi_warn(HANDLE_CTX(dev_handle),
220 "unrecognised status code %d", transfer->status);
221 r = LIBUSB_ERROR_OTHER;
224 libusb_free_transfer(transfer);
229 * Perform a USB bulk transfer. The direction of the transfer is inferred from
230 * the direction bits of the endpoint address.
232 * For bulk reads, the <tt>length</tt> field indicates the maximum length of
233 * data you are expecting to receive. If less data arrives than expected,
234 * this function will return that data, so be sure to check the
235 * <tt>transferred</tt> output parameter.
237 * You should also check the <tt>transferred</tt> parameter for bulk writes.
238 * Not all of the data may have been written.
240 * Also check <tt>transferred</tt> when dealing with a timeout error code.
241 * libusbx may have to split your transfer into a number of chunks to satisfy
242 * underlying O/S requirements, meaning that the timeout may expire after
243 * the first few chunks have completed. libusbx is careful not to lose any data
244 * that may have been transferred; do not assume that timeout conditions
245 * indicate a complete lack of I/O.
247 * \param dev_handle a handle for the device to communicate with
248 * \param endpoint the address of a valid endpoint to communicate with
249 * \param data a suitably-sized data buffer for either input or output
250 * (depending on endpoint)
251 * \param length for bulk writes, the number of bytes from data to be sent. for
252 * bulk reads, the maximum number of bytes to receive into the data buffer.
253 * \param transferred output location for the number of bytes actually
255 * \param timeout timeout (in millseconds) that this function should wait
256 * before giving up due to no response being received. For an unlimited
257 * timeout, use value 0.
259 * \returns 0 on success (and populates <tt>transferred</tt>)
260 * \returns LIBUSB_ERROR_TIMEOUT if the transfer timed out (and populates
261 * <tt>transferred</tt>)
262 * \returns LIBUSB_ERROR_PIPE if the endpoint halted
263 * \returns LIBUSB_ERROR_OVERFLOW if the device offered more data, see
264 * \ref packetoverflow
265 * \returns LIBUSB_ERROR_NO_DEVICE if the device has been disconnected
266 * \returns another LIBUSB_ERROR code on other failures
268 int API_EXPORTED libusb_bulk_transfer(struct libusb_device_handle *dev_handle,
269 unsigned char endpoint, unsigned char *data, int length, int *transferred,
270 unsigned int timeout)
272 return do_sync_bulk_transfer(dev_handle, endpoint, data, length,
273 transferred, timeout, LIBUSB_TRANSFER_TYPE_BULK);
277 * Perform a USB interrupt transfer. The direction of the transfer is inferred
278 * from the direction bits of the endpoint address.
280 * For interrupt reads, the <tt>length</tt> field indicates the maximum length
281 * of data you are expecting to receive. If less data arrives than expected,
282 * this function will return that data, so be sure to check the
283 * <tt>transferred</tt> output parameter.
285 * You should also check the <tt>transferred</tt> parameter for interrupt
286 * writes. Not all of the data may have been written.
288 * Also check <tt>transferred</tt> when dealing with a timeout error code.
289 * libusbx may have to split your transfer into a number of chunks to satisfy
290 * underlying O/S requirements, meaning that the timeout may expire after
291 * the first few chunks have completed. libusbx is careful not to lose any data
292 * that may have been transferred; do not assume that timeout conditions
293 * indicate a complete lack of I/O.
295 * The default endpoint bInterval value is used as the polling interval.
297 * \param dev_handle a handle for the device to communicate with
298 * \param endpoint the address of a valid endpoint to communicate with
299 * \param data a suitably-sized data buffer for either input or output
300 * (depending on endpoint)
301 * \param length for bulk writes, the number of bytes from data to be sent. for
302 * bulk reads, the maximum number of bytes to receive into the data buffer.
303 * \param transferred output location for the number of bytes actually
305 * \param timeout timeout (in millseconds) that this function should wait
306 * before giving up due to no response being received. For an unlimited
307 * timeout, use value 0.
309 * \returns 0 on success (and populates <tt>transferred</tt>)
310 * \returns LIBUSB_ERROR_TIMEOUT if the transfer timed out
311 * \returns LIBUSB_ERROR_PIPE if the endpoint halted
312 * \returns LIBUSB_ERROR_OVERFLOW if the device offered more data, see
313 * \ref packetoverflow
314 * \returns LIBUSB_ERROR_NO_DEVICE if the device has been disconnected
315 * \returns another LIBUSB_ERROR code on other error
317 int API_EXPORTED libusb_interrupt_transfer(
318 struct libusb_device_handle *dev_handle, unsigned char endpoint,
319 unsigned char *data, int length, int *transferred, unsigned int timeout)
321 return do_sync_bulk_transfer(dev_handle, endpoint, data, length,
322 transferred, timeout, LIBUSB_TRANSFER_TYPE_INTERRUPT);