2 * Synchronous I/O functions for libusb
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
30 * @defgroup syncio Synchronous device I/O
32 * This page documents libusb's synchronous (blocking) API for USB device I/O.
33 * This interface is easy to use but has some limitations. More advanced users
34 * may wish to consider using the \ref asyncio "asynchronous I/O API" instead.
37 static void LIBUSB_CALL sync_transfer_cb(struct libusb_transfer *transfer)
39 int *completed = transfer->user_data;
41 usbi_dbg("actual_length=%d", transfer->actual_length);
42 /* caller interprets result and frees transfer */
45 static void sync_transfer_wait_for_completion(struct libusb_transfer *transfer)
47 int r, *completed = transfer->user_data;
48 struct libusb_context *ctx = HANDLE_CTX(transfer->dev_handle);
51 r = libusb_handle_events_completed(ctx, completed);
53 if (r == LIBUSB_ERROR_INTERRUPTED)
55 usbi_err(ctx, "libusb_handle_events failed: %s, cancelling transfer and retrying",
56 libusb_error_name(r));
57 libusb_cancel_transfer(transfer);
64 * Perform a USB control transfer.
66 * The direction of the transfer is inferred from the bmRequestType field of
69 * The wValue, wIndex and wLength fields values should be given in host-endian
72 * \param dev_handle a handle for the device to communicate with
73 * \param bmRequestType the request type field for the setup packet
74 * \param bRequest the request field for the setup packet
75 * \param wValue the value field for the setup packet
76 * \param wIndex the index field for the setup packet
77 * \param data a suitably-sized data buffer for either input or output
78 * (depending on direction bits within bmRequestType)
79 * \param wLength the length field for the setup packet. The data buffer should
80 * be at least this size.
81 * \param timeout timeout (in millseconds) that this function should wait
82 * before giving up due to no response being received. For an unlimited
83 * timeout, use value 0.
84 * \returns on success, the number of bytes actually transferred
85 * \returns LIBUSB_ERROR_TIMEOUT if the transfer timed out
86 * \returns LIBUSB_ERROR_PIPE if the control request was not supported by the
88 * \returns LIBUSB_ERROR_NO_DEVICE if the device has been disconnected
89 * \returns another LIBUSB_ERROR code on other failures
91 int API_EXPORTED libusb_control_transfer(libusb_device_handle *dev_handle,
92 uint8_t bmRequestType, uint8_t bRequest, uint16_t wValue, uint16_t wIndex,
93 unsigned char *data, uint16_t wLength, unsigned int timeout)
95 struct libusb_transfer *transfer = libusb_alloc_transfer(0);
96 unsigned char *buffer;
101 return LIBUSB_ERROR_NO_MEM;
103 buffer = (unsigned char*) malloc(LIBUSB_CONTROL_SETUP_SIZE + wLength);
105 libusb_free_transfer(transfer);
106 return LIBUSB_ERROR_NO_MEM;
109 libusb_fill_control_setup(buffer, bmRequestType, bRequest, wValue, wIndex,
111 if ((bmRequestType & LIBUSB_ENDPOINT_DIR_MASK) == LIBUSB_ENDPOINT_OUT)
112 memcpy(buffer + LIBUSB_CONTROL_SETUP_SIZE, data, wLength);
114 libusb_fill_control_transfer(transfer, dev_handle, buffer,
115 sync_transfer_cb, &completed, timeout);
116 transfer->flags = LIBUSB_TRANSFER_FREE_BUFFER;
117 r = libusb_submit_transfer(transfer);
119 libusb_free_transfer(transfer);
123 sync_transfer_wait_for_completion(transfer);
125 if ((bmRequestType & LIBUSB_ENDPOINT_DIR_MASK) == LIBUSB_ENDPOINT_IN)
126 memcpy(data, libusb_control_transfer_get_data(transfer),
127 transfer->actual_length);
129 switch (transfer->status) {
130 case LIBUSB_TRANSFER_COMPLETED:
131 r = transfer->actual_length;
133 case LIBUSB_TRANSFER_TIMED_OUT:
134 r = LIBUSB_ERROR_TIMEOUT;
136 case LIBUSB_TRANSFER_STALL:
137 r = LIBUSB_ERROR_PIPE;
139 case LIBUSB_TRANSFER_NO_DEVICE:
140 r = LIBUSB_ERROR_NO_DEVICE;
142 case LIBUSB_TRANSFER_OVERFLOW:
143 r = LIBUSB_ERROR_OVERFLOW;
145 case LIBUSB_TRANSFER_ERROR:
146 case LIBUSB_TRANSFER_CANCELLED:
150 usbi_warn(HANDLE_CTX(dev_handle),
151 "unrecognised status code %d", transfer->status);
152 r = LIBUSB_ERROR_OTHER;
155 libusb_free_transfer(transfer);
159 static int do_sync_bulk_transfer(struct libusb_device_handle *dev_handle,
160 unsigned char endpoint, unsigned char *buffer, int length,
161 int *transferred, unsigned int timeout, unsigned char type)
163 struct libusb_transfer *transfer = libusb_alloc_transfer(0);
168 return LIBUSB_ERROR_NO_MEM;
170 libusb_fill_bulk_transfer(transfer, dev_handle, endpoint, buffer, length,
171 sync_transfer_cb, &completed, timeout);
172 transfer->type = type;
174 r = libusb_submit_transfer(transfer);
176 libusb_free_transfer(transfer);
180 sync_transfer_wait_for_completion(transfer);
182 *transferred = transfer->actual_length;
183 switch (transfer->status) {
184 case LIBUSB_TRANSFER_COMPLETED:
187 case LIBUSB_TRANSFER_TIMED_OUT:
188 r = LIBUSB_ERROR_TIMEOUT;
190 case LIBUSB_TRANSFER_STALL:
191 r = LIBUSB_ERROR_PIPE;
193 case LIBUSB_TRANSFER_OVERFLOW:
194 r = LIBUSB_ERROR_OVERFLOW;
196 case LIBUSB_TRANSFER_NO_DEVICE:
197 r = LIBUSB_ERROR_NO_DEVICE;
199 case LIBUSB_TRANSFER_ERROR:
200 case LIBUSB_TRANSFER_CANCELLED:
204 usbi_warn(HANDLE_CTX(dev_handle),
205 "unrecognised status code %d", transfer->status);
206 r = LIBUSB_ERROR_OTHER;
209 libusb_free_transfer(transfer);
214 * Perform a USB bulk transfer. The direction of the transfer is inferred from
215 * the direction bits of the endpoint address.
217 * For bulk reads, the <tt>length</tt> field indicates the maximum length of
218 * data you are expecting to receive. If less data arrives than expected,
219 * this function will return that data, so be sure to check the
220 * <tt>transferred</tt> output parameter.
222 * You should also check the <tt>transferred</tt> parameter for bulk writes.
223 * Not all of the data may have been written.
225 * Also check <tt>transferred</tt> when dealing with a timeout error code.
226 * libusb may have to split your transfer into a number of chunks to satisfy
227 * underlying O/S requirements, meaning that the timeout may expire after
228 * the first few chunks have completed. libusb is careful not to lose any data
229 * that may have been transferred; do not assume that timeout conditions
230 * indicate a complete lack of I/O.
232 * \param dev_handle a handle for the device to communicate with
233 * \param endpoint the address of a valid endpoint to communicate with
234 * \param data a suitably-sized data buffer for either input or output
235 * (depending on endpoint)
236 * \param length for bulk writes, the number of bytes from data to be sent. for
237 * bulk reads, the maximum number of bytes to receive into the data buffer.
238 * \param transferred output location for the number of bytes actually
240 * \param timeout timeout (in millseconds) that this function should wait
241 * before giving up due to no response being received. For an unlimited
242 * timeout, use value 0.
244 * \returns 0 on success (and populates <tt>transferred</tt>)
245 * \returns LIBUSB_ERROR_TIMEOUT if the transfer timed out (and populates
246 * <tt>transferred</tt>)
247 * \returns LIBUSB_ERROR_PIPE if the endpoint halted
248 * \returns LIBUSB_ERROR_OVERFLOW if the device offered more data, see
249 * \ref packetoverflow
250 * \returns LIBUSB_ERROR_NO_DEVICE if the device has been disconnected
251 * \returns another LIBUSB_ERROR code on other failures
253 int API_EXPORTED libusb_bulk_transfer(struct libusb_device_handle *dev_handle,
254 unsigned char endpoint, unsigned char *data, int length, int *transferred,
255 unsigned int timeout)
257 return do_sync_bulk_transfer(dev_handle, endpoint, data, length,
258 transferred, timeout, LIBUSB_TRANSFER_TYPE_BULK);
262 * Perform a USB interrupt transfer. The direction of the transfer is inferred
263 * from the direction bits of the endpoint address.
265 * For interrupt reads, the <tt>length</tt> field indicates the maximum length
266 * of data you are expecting to receive. If less data arrives than expected,
267 * this function will return that data, so be sure to check the
268 * <tt>transferred</tt> output parameter.
270 * You should also check the <tt>transferred</tt> parameter for interrupt
271 * writes. Not all of the data may have been written.
273 * Also check <tt>transferred</tt> when dealing with a timeout error code.
274 * libusb may have to split your transfer into a number of chunks to satisfy
275 * underlying O/S requirements, meaning that the timeout may expire after
276 * the first few chunks have completed. libusb is careful not to lose any data
277 * that may have been transferred; do not assume that timeout conditions
278 * indicate a complete lack of I/O.
280 * The default endpoint bInterval value is used as the polling interval.
282 * \param dev_handle a handle for the device to communicate with
283 * \param endpoint the address of a valid endpoint to communicate with
284 * \param data a suitably-sized data buffer for either input or output
285 * (depending on endpoint)
286 * \param length for bulk writes, the number of bytes from data to be sent. for
287 * bulk reads, the maximum number of bytes to receive into the data buffer.
288 * \param transferred output location for the number of bytes actually
290 * \param timeout timeout (in millseconds) that this function should wait
291 * before giving up due to no response being received. For an unlimited
292 * timeout, use value 0.
294 * \returns 0 on success (and populates <tt>transferred</tt>)
295 * \returns LIBUSB_ERROR_TIMEOUT if the transfer timed out
296 * \returns LIBUSB_ERROR_PIPE if the endpoint halted
297 * \returns LIBUSB_ERROR_OVERFLOW if the device offered more data, see
298 * \ref packetoverflow
299 * \returns LIBUSB_ERROR_NO_DEVICE if the device has been disconnected
300 * \returns another LIBUSB_ERROR code on other error
302 int API_EXPORTED libusb_interrupt_transfer(
303 struct libusb_device_handle *dev_handle, unsigned char endpoint,
304 unsigned char *data, int length, int *transferred, unsigned int timeout)
306 return do_sync_bulk_transfer(dev_handle, endpoint, data, length,
307 transferred, timeout, LIBUSB_TRANSFER_TYPE_INTERRUPT);