peripherals  1.4.2
RoadNarrows Robotics Hardware Peripherals Package
usbext.h
Go to the documentation of this file.
1 ////////////////////////////////////////////////////////////////////////////////
2 //
3 // Package: RoadNarrows Robotics Peripherals
4 //
5 // File: usbext.h
6 //
7 /*! \file
8  *
9  * $LastChangedDate: 2013-02-20 10:20:40 -0700 (Wed, 20 Feb 2013) $
10  * $Rev: 2697 $
11  *
12  * \brief USB extensions and capatabilities.
13  *
14  * \author Robin Knight (robin.knight@roadnarrows.com)
15  * \author Daniel Packard (daniel@roadnarrows.com)
16  *
17  * \copyright
18  * \h_copy 2013-2017. RoadNarrows LLC.\n
19  * http://www.roadnarrows.com\n
20  * All Rights Reserved
21  */
22 // Permission is hereby granted, without written agreement and without
23 // license or royalty fees, to use, copy, modify, and distribute this
24 // software and its documentation for any purpose, provided that
25 // (1) The above copyright notice and the following two paragraphs
26 // appear in all copies of the source code and (2) redistributions
27 // including binaries reproduces these notices in the supporting
28 // documentation. Substantial modifications to this software may be
29 // copyrighted by their authors and need not follow the licensing terms
30 // described here, provided that the new terms are clearly indicated in
31 // all files where they apply.
32 //
33 // IN NO EVENT SHALL THE AUTHOR, ROADNARROWS LLC, OR ANY MEMBERS/EMPLOYEES
34 // OF ROADNARROW LLC OR DISTRIBUTORS OF THIS SOFTWARE BE LIABLE TO ANY
35 // PARTY FOR DIRECT, INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL
36 // DAMAGES ARISING OUT OF THE USE OF THIS SOFTWARE AND ITS DOCUMENTATION,
37 // EVEN IF THE AUTHORS OR ANY OF THE ABOVE PARTIES HAVE BEEN ADVISED OF
38 // THE POSSIBILITY OF SUCH DAMAGE.
39 //
40 // THE AUTHOR AND ROADNARROWS LLC SPECIFICALLY DISCLAIM ANY WARRANTIES,
41 // INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND
42 // FITNESS FOR A PARTICULAR PURPOSE. THE SOFTWARE PROVIDED HEREUNDER IS ON AN
43 // "AS IS" BASIS, AND THE AUTHORS AND DISTRIBUTORS HAVE NO OBLIGATION TO
44 // PROVIDE MAINTENANCE, SUPPORT, UPDATES, ENHANCEMENTS, OR MODIFICATIONS.
45 //
46 ////////////////////////////////////////////////////////////////////////////////
47 
48 #ifndef _USBEXT_H
49 #define _USBEXT_H
50 
51 #include <sys/time.h>
52 
53 #include <libusb-1.0/libusb.h>
54 
55 #include "rnr/rnrconfig.h"
56 
57 C_DECLS_BEGIN
58 
59 #ifdef ARCH_overo
60 
61 /*!
62  * \brief Returns a constant NULL-terminated string with the ASCII name of a
63  * libusb error code.
64  *
65  * \param error_code A libusb error code.
66  *
67  * \return const char *
68  */
69 INLINE_IN_H const char *libusb_error_name(int error_code)
70 {
71  switch( error_code )
72  {
73  case LIBUSB_SUCCESS:
74  return "LIBUSB_SUCCESS";
75  case LIBUSB_ERROR_IO:
76  return "LIBUSB_ERROR_IO";
77  case LIBUSB_ERROR_INVALID_PARAM:
78  return "LIBUSB_ERROR_INVALID_PARAM";
79  case LIBUSB_ERROR_ACCESS:
80  return "LIBUSB_ERROR_ACCESS";
81  case LIBUSB_ERROR_NO_DEVICE:
82  return "LIBUSB_ERROR_NO_DEVICE";
83  case LIBUSB_ERROR_NOT_FOUND:
84  return "LIBUSB_ERROR_NOT_FOUND";
85  case LIBUSB_ERROR_BUSY:
86  return "LIBUSB_ERROR_BUSY";
87  case LIBUSB_ERROR_TIMEOUT:
88  return "LIBUSB_ERROR_TIMEOUT";
89  case LIBUSB_ERROR_OVERFLOW:
90  return "LIBUSB_ERROR_OVERFLOW";
91  case LIBUSB_ERROR_PIPE:
92  return "LIBUSB_ERROR_PIPE";
93  case LIBUSB_ERROR_INTERRUPTED:
94  return "LIBUSB_ERROR_INTERRUPTED";
95  case LIBUSB_ERROR_NO_MEM:
96  return "LIBUSB_ERROR_NO_MEM";
97  case LIBUSB_ERROR_NOT_SUPPORTED:
98  return "LIBUSB_ERROR_NOT_SUPPORTED";
99  case LIBUSB_ERROR_OTHER:
100  default:
101  return "LIBUSB_ERROR_OTHER";
102  }
103 }
104 
105 /*!
106  * Handle any pending events.
107  *
108  * libusb determines "pending events" by checking if any timeouts have expired
109  * and by checking the set of file descriptors for activity.
110  *
111  * If a zero timeval is passed, this function will handle any already-pending
112  * events and then immediately return in non-blocking style.
113  *
114  * If a non-zero timeval is passed and no events are currently pending, this
115  * function will block waiting for events to handle up until the specified
116  * timeout. If an event arrives or a signal is raised, this function will
117  * return early.
118  *
119  * If the parameter completed is not NULL then after obtaining the event
120  * handling lock this function will return immediately if the integer pointed
121  * to is not 0. This allows for race free waiting for the completion of a
122  * specific transfer.
123  *
124  * \param ctx The context to operate on, or NULL for the default context.
125  * \param tv The maximum time to block waiting for events, or an all
126  * zero timeval struct for non-blocking mode.
127  * \param completed Pointer to completion integer to check, or NULL.\n
128  * NOT USED.
129  *
130  * \return Returns 0 on success, or a LIBUSB_ERROR code on failure.
131  */
132 INLINE_IN_H int libusb_handle_events_timeout_completed(libusb_context *ctx,
133  struct timeval *tv,
134  int *completed)
135 {
136  return libusb_handle_events_timeout(ctx, tv);
137 }
138 
139 #endif // ARCH_overo
140 
141 C_DECLS_END
142 
143 #endif // _USBEXT_H