libusb/sync.c

   1 /*
   2  * Synchronous I/O functions for libusb
   3  * Copyright (C) 2007-2008 Daniel Drake <dsd@gentoo.org>
   4  *
   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.
   9  *
  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.
  14  *
  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
  18  */
  19
  20 #include <config.h>
  21 #include <errno.h>
  22 #include <stdint.h>
  23 #include <stdlib.h>
  24 #include <string.h>
  25
  26 #include "libusbi.h"
  27
  28 /**
  29  * @defgroup syncio Synchronous device I/O
  30  *
  31  * This page documents libusb'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.
  34  */
  35
  36 static void ctrl_transfer_cb(struct libusb_transfer *transfer)
  37 {
  38         int *completed = transfer->user_data;
  39         *completed = 1;
  40         usbi_dbg("actual_length=%d", transfer->actual_length);
  41         /* caller interprets result and frees transfer */
  42 }
  43
  44 /* FIXME: does this support partial transfers? */
  45 /** \ingroup syncio
  46  * Perform a USB control transfer. The direction of the transfer is inferred
  47  * from the bmRequestType field of the setup packet.
  48  *
  49  * \param dev_handle a handle for the device to communicate with
  50  * \param bmRequestType the request type field for the setup packet
  51  * \param bRequest the request field for the setup packet
  52  * \param wValue the value field for the setup packet
  53  * \param wIndex the index field for the setup packet
  54  * \param data a suitably-sized data buffer for either input or output
  55  * (depending on direction bits within bmRequestType)
  56  * \param wLength the length field for the setup packet. The data buffer should
  57  * be at least this size.
  58  * \param timeout timeout (in millseconds) that this function should wait
  59  * before giving up due to no response being received. For no timeout, use
  60  * value 0.
  61  * \returns 0 on success
  62  * \returns -ETIMEDOUT if the transfer timed out
  63  * \returns other negative code on error
  64  */
  65 API_EXPORTED int libusb_control_transfer(libusb_device_handle *dev_handle,
  66         uint8_t bmRequestType, uint8_t bRequest, uint16_t wValue, uint16_t wIndex,
  67         unsigned char *data, uint16_t wLength, unsigned int timeout)
  68 {
  69         struct libusb_transfer *transfer = libusb_alloc_transfer(0);
  70         unsigned char *buffer;
  71         int completed = 0;
  72         int r;
  73
  74         if (!transfer)
  75                 return -ENOMEM;
  76
  77         buffer = malloc(LIBUSB_CONTROL_SETUP_SIZE + wLength);
  78         if (!buffer) {
  79                 libusb_free_transfer(transfer);
  80                 return -ENOMEM;
  81         }
  82
  83         libusb_fill_control_setup(buffer, bmRequestType, bRequest, wValue, wIndex,
  84                 wLength);
  85         if ((bmRequestType & LIBUSB_ENDPOINT_DIR_MASK) == LIBUSB_ENDPOINT_OUT)
  86                 memcpy(buffer + LIBUSB_CONTROL_SETUP_SIZE, data, wLength);
  87
  88         libusb_fill_control_transfer(transfer, dev_handle, buffer,
  89                 ctrl_transfer_cb, &completed, timeout);
  90         r = libusb_submit_transfer(transfer);
  91         if (r < 0) {
  92                 libusb_free_transfer(transfer);
  93                 return r;
  94         }
  95
  96         while (!completed) {
  97                 r = libusb_handle_events();
  98                 if (r < 0) {
  99                         libusb_cancel_transfer(transfer);
 100                         while (!completed)
 101                                 if (libusb_handle_events() < 0)
 102                                         break;
 103                         libusb_free_transfer(transfer);
 104                         return r;
 105                 }
 106         }
 107
 108         if ((bmRequestType & LIBUSB_ENDPOINT_DIR_MASK) == LIBUSB_ENDPOINT_IN)
 109                 memcpy(data, libusb_control_transfer_get_data(transfer),
 110                         transfer->actual_length);
 111
 112         switch (transfer->status) {
 113         case LIBUSB_TRANSFER_COMPLETED:
 114                 r = transfer->actual_length;
 115                 break;
 116         case LIBUSB_TRANSFER_TIMED_OUT:
 117                 r = -ETIMEDOUT;
 118                 break;
 119         default:
 120                 usbi_warn("unrecognised status code %d", transfer->status);
 121                 r = -1;
 122         }
 123
 124         libusb_free_transfer(transfer);
 125         return r;
 126 }
 127
 128 static void bulk_transfer_cb(struct libusb_transfer *transfer)
 129 {
 130         int *completed = transfer->user_data;
 131         *completed = 1;
 132         usbi_dbg("actual_length=%d", transfer->actual_length);
 133         /* caller interprets results and frees transfer */
 134 }
 135
 136 static int do_sync_bulk_transfer(struct libusb_device_handle *dev_handle,
 137         unsigned char endpoint, unsigned char *buffer, int length,
 138         int *transferred, unsigned int timeout, unsigned char endpoint_type)
 139 {
 140         struct libusb_transfer *transfer = libusb_alloc_transfer(0);
 141         int completed = 0;
 142         int r;
 143
 144         if (!transfer)
 145                 return -ENOMEM;
 146
 147         libusb_fill_bulk_transfer(transfer, dev_handle, endpoint, buffer, length,
 148                 bulk_transfer_cb, &completed, timeout);
 149         transfer->endpoint_type = endpoint_type;
 150
 151         r = libusb_submit_transfer(transfer);
 152         if (r < 0) {
 153                 libusb_free_transfer(transfer);
 154                 return r;
 155         }
 156
 157         while (!completed) {
 158                 r = libusb_handle_events();
 159                 if (r < 0) {
 160                         libusb_cancel_transfer(transfer);
 161                         while (!completed)
 162                                 if (libusb_handle_events() < 0)
 163                                         break;
 164                         libusb_free_transfer(transfer);
 165                         return r;
 166                 }
 167         }
 168
 169         *transferred = transfer->actual_length;
 170         switch (transfer->status) {
 171         case LIBUSB_TRANSFER_COMPLETED:
 172                 r = 0;
 173                 break;
 174         case LIBUSB_TRANSFER_TIMED_OUT:
 175                 r = -ETIMEDOUT;
 176                 break;
 177         default:
 178                 usbi_warn("unrecognised status code %d", transfer->status);
 179                 r = -1;
 180         }
 181
 182         libusb_free_transfer(transfer);
 183         return r;
 184 }
 185
 186 /** \ingroup syncio
 187  * Perform a USB bulk transfer. The direction of the transfer is inferred from
 188  * the direction bits of the endpoint address.
 189  *
 190  * For bulk reads, the <tt>length</tt> field indicates the maximum length of
 191  * data you are expecting to receive. If less data arrives than expected,
 192  * this function will return that data, so be sure to check the
 193  * <tt>transferred</tt> output parameter.
 194  *
 195  * You should also check the <tt>transferred</tt> parameter for bulk writes.
 196  * Not all of the data may have been written.
 197  *
 198  * Also check <tt>transferred</tt> when dealing with a timeout error code.
 199  * libusb may have to split your transfer into a number of chunks to satisfy
 200  * underlying O/S requirements, meaning that the timeout may expire after
 201  * the first few chunks have completed. libusb is careful not to lose any data
 202  * that may have been transferred; do not assume that timeout conditions
 203  * indicate a complete lack of I/O.
 204  *
 205  * \param dev_handle a handle for the device to communicate with
 206  * \param endpoint the address of a valid endpoint to communicate with
 207  * \param data a suitably-sized data buffer for either input or output
 208  * (depending on endpoint)
 209  * \param length for bulk writes, the number of bytes from data to be sent. for
 210  * bulk reads, the maximum number of bytes to receive into the data buffer.
 211  * \param transferred output location for the number of bytes actually
 212  * transferred.
 213  * \param timeout timeout (in millseconds) that this function should wait
 214  * before giving up due to no response being received. For no timeout, use
 215  * value 0.
 216  *
 217  * \returns 0 on success (and populates <tt>transferred</tt>)
 218  * \returns -ETIMEDOUT if the transfer timed out (and populates
 219  * <tt>transferred</tt>)
 220  * \returns other negative code on error
 221  */
 222 API_EXPORTED int libusb_bulk_transfer(struct libusb_device_handle *dev_handle,
 223         unsigned char endpoint, unsigned char *data, int length, int *transferred,
 224         unsigned int timeout)
 225 {
 226         return do_sync_bulk_transfer(dev_handle, endpoint, data, length,
 227                 transferred, timeout, LIBUSB_ENDPOINT_TYPE_BULK);
 228 }
 229
 230 /** \ingroup syncio
 231  * Perform a USB interrupt transfer. The direction of the transfer is inferred
 232  * from the direction bits of the endpoint address.
 233  *
 234  * For interrupt reads, the <tt>length</tt> field indicates the maximum length
 235  * of data you are expecting to receive. If less data arrives than expected,
 236  * this function will return that data, so be sure to check the
 237  * <tt>transferred</tt> output parameter.
 238  *
 239  * You should also check the <tt>transferred</tt> parameter for interrupt
 240  * writes. Not all of the data may have been written.
 241  *
 242  * Also check <tt>transferred</tt> when dealing with a timeout error code.
 243  * libusb may have to split your transfer into a number of chunks to satisfy
 244  * underlying O/S requirements, meaning that the timeout may expire after
 245  * the first few chunks have completed. libusb is careful not to lose any data
 246  * that may have been transferred; do not assume that timeout conditions
 247  * indicate a complete lack of I/O.
 248  *
 249  * The default endpoint bInterval value is used as the polling interval.
 250  *
 251  * \param dev_handle a handle for the device to communicate with
 252  * \param endpoint the address of a valid endpoint to communicate with
 253  * \param data a suitably-sized data buffer for either input or output
 254  * (depending on endpoint)
 255  * \param length for bulk writes, the number of bytes from data to be sent. for
 256  * bulk reads, the maximum number of bytes to receive into the data buffer.
 257  * \param transferred output location for the number of bytes actually
 258  * transferred.
 259  * \param timeout timeout (in millseconds) that this function should wait
 260  * before giving up due to no response being received. For no timeout, use
 261  * value 0.
 262  *
 263  * \returns 0 on success (and populates <tt>transferred</tt>)
 264  * \returns -ETIMEDOUT if the transfer timed out
 265  * \returns other negative code on error
 266  */
 267 API_EXPORTED int libusb_interrupt_transfer(
 268         struct libusb_device_handle *dev_handle, unsigned char endpoint,
 269         unsigned char *data, int length, int *transferred, unsigned int timeout)
 270 {
 271         return do_sync_bulk_transfer(dev_handle, endpoint, data, length,
 272                 transferred, timeout, LIBUSB_ENDPOINT_TYPE_INTERRUPT);
 273 }
 274