7 Copyright (C) 2005-2012, Chris Frey
8 Portions Copyright (C) 2011, RealVNC Ltd.
10 This program is free software; you can redistribute it and/or modify
11 it under the terms of the GNU General Public License as published by
12 the Free Software Foundation; either version 2 of the License, or
13 (at your option) any later version.
15 This program is distributed in the hope that it will be useful,
16 but WITHOUT ANY WARRANTY; without even the implied warranty of
17 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
19 See the GNU General Public License in the COPYING file at the
20 root directory of this project for more details.
24 #ifndef __SB_USBWRAP_H__
25 #define __SB_USBWRAP_H__
35 #define USBWRAP_DEFAULT_TIMEOUT 30000
37 // Matches any product ID when calling DeviceList::MatchDevices
38 #define PRODUCT_ANY 0x10000
39 // Indicates an unknown product ID
40 #define PRODUCT_UNKNOWN 0x20000
42 namespace Barry
{ class Data
; }
44 /// Namespace for the libusb-related wrapper classes. This namespace
45 /// may change in the future.
48 /// \addtogroup exceptions
51 /// Thrown on low level USB errors.
52 class BXEXPORT Error
: public Barry::Error
57 Error(const std::string
&str
);
58 Error(int libusb_errcode
, const std::string
&str
);
60 // can return 0 in some case, if unknown error code
61 int libusb_errcode() const { return m_libusb_errcode
; }
63 // returns a translated system error code when using libusb 1.0
64 // returns 0 if unknown or unable to translate
65 int system_errcode() const;
68 class BXEXPORT Timeout
: public Error
71 Timeout(const std::string
&str
) : Error(str
) {}
72 Timeout(int errcode
, const std::string
&str
)
73 : Error(errcode
, str
) {}
78 // Private struct for holding library specific
79 // a unique identifier to a connected device.
82 class BXEXPORT DeviceID
85 std::tr1::shared_ptr
<DeviceIDImpl
> m_impl
;
87 // Takes ownership of impl
88 DeviceID(DeviceIDImpl
* impl
= NULL
);
90 const char* GetBusName() const;
91 uint16_t GetNumber() const;
92 const char* GetFilename() const;
93 uint16_t GetIdProduct() const;
95 // Utility function: returns a string that uniquely identifies
96 // the bus and device, regardless of which libusb you're using
97 std::string
GetUsbName() const;
100 // Private struct for holding a library specific
104 // Static functions for setting up USB
105 // The interface that usbwrap.cc uses
106 // to interact with the USB library
107 class BXEXPORT LibraryInterface
110 static std::string
GetLastErrorString(int libusb_errcode
);
112 /// Returns 0 if unable to translate libusb error code.
113 /// Note that this function assumes you already know that libusb_errcode
114 /// contains an actual error code, and so returns 0 (success)
115 /// for an unknown error. This means that "success" means error
116 /// if you use this function correctly, but if you pass in a success
117 /// code (>= 0) it will always return 0 as well.
118 static int TranslateErrcode(int libusb_errcode
);
120 /// Returns true on success... pass in a pointer to int
121 /// if the low level error code is important to you.
122 static bool Init(int *libusb_errno
= 0);
123 static void Uninit();
124 static void SetDataDump(bool data_dump_mode
);
127 // Forward declaration of descriptor types.
128 class BXEXPORT DeviceDescriptor
;
129 class BXEXPORT ConfigDescriptor
;
130 class BXEXPORT InterfaceDescriptor
;
132 // Private struct for holding library specific
133 // information about endpoint descriptors
134 struct EndpointDescriptorImpl
;
136 // Encapsulates an endpoint descriptor
137 class BXEXPORT EndpointDescriptor
149 const std::auto_ptr
<EndpointDescriptorImpl
> m_impl
;
154 EndpointDescriptor(InterfaceDescriptor
& dev
, int endpoint
);
155 ~EndpointDescriptor();
157 uint8_t GetAddress() const;
158 EpType
GetType() const;
161 // Private struct for holding library specific
162 // information about interface descriptors
163 struct InterfaceDescriptorImpl
;
165 // Encapsulates an interface descriptor
167 // The inherited vector methods look up endpoints
168 class BXEXPORT InterfaceDescriptor
: public std::vector
<EndpointDescriptor
*>
170 friend class EndpointDescriptor
;
172 typedef std::vector
<EndpointDescriptor
*> base_type
;
174 const std::auto_ptr
<InterfaceDescriptorImpl
> m_impl
;
176 InterfaceDescriptor(ConfigDescriptor
& cfgdesc
,
177 int interface
, int altsetting
);
178 ~InterfaceDescriptor();
179 uint8_t GetClass() const;
180 uint8_t GetNumber() const;
181 uint8_t GetAltSetting() const;
184 // Private struct for holding library specific
185 // information about config descriptors
187 struct ConfigDescriptorImpl
;
189 // Encapsulates a configuration descriptor
191 // The inherited map methods look up interface descriptors
192 class BXEXPORT ConfigDescriptor
: public std::map
<int, InterfaceDescriptor
*>
194 friend class InterfaceDescriptor
;
196 typedef std::map
<int, InterfaceDescriptor
*> base_type
;
198 const std::auto_ptr
<ConfigDescriptorImpl
> m_impl
;
200 ConfigDescriptor(DeviceDescriptor
& dev
, int cfgnumber
);
202 uint8_t GetNumber() const;
205 // Private struct for holding library specific
206 // information about a device descriptor
207 struct DeviceDescriptorImpl
;
209 // Encapsulates a device descriptor
211 // The inherited map methods look up config descriptors
212 class BXEXPORT DeviceDescriptor
: public std::map
<int, ConfigDescriptor
*>
214 friend class ConfigDescriptor
;
216 typedef std::map
<int, ConfigDescriptor
*> base_type
;
218 const std::auto_ptr
<DeviceDescriptorImpl
> m_impl
;
220 DeviceDescriptor(DeviceID
& devid
);
224 // Private struct for holding library specific
225 // information for devices.
226 struct DeviceListImpl
;
228 class BXEXPORT DeviceList
231 // Private implementation structure
232 const std::auto_ptr
<DeviceListImpl
> m_impl
;
237 std::vector
<DeviceID
> MatchDevices(int vendor
, int product
,
238 const char *busname
, const char *devname
);
242 struct PrivateDeviceData
;
244 class BXEXPORT Device
248 std::auto_ptr
<Usb::DeviceHandle
> m_handle
;
254 Device(const Usb::DeviceID
& id
, int timeout
= USBWRAP_DEFAULT_TIMEOUT
);
257 /////////////////////////////
260 const Usb::DeviceID
& GetID() const { return m_id
; }
261 const Usb::DeviceHandle
* GetHandle() const { return &*m_handle
; }
262 int GetLastError() const { return m_lasterror
; } //< not thread safe...
263 //< use the error code stored in the exceptions to track
264 //< errors in threaded usage
265 void SetLastError(int err
) { m_lasterror
= err
; }
266 int GetDefaultTimeout() const { return m_timeout
; }
268 /////////////////////////////
269 // Device information
272 int FindInterface(int ifaceClass
);
274 /////////////////////////////
275 // Device manipulation
277 bool SetConfiguration(unsigned char cfg
);
278 bool ClearHalt(int ep
);
280 bool IsAttachKernelDriver(int iface
);
281 bool DetachKernelDriver(int iface
);
283 /////////////////////////////
286 bool BulkRead(int ep
, Barry::Data
&data
, int timeout
= -1);
287 bool BulkWrite(int ep
, const Barry::Data
&data
, int timeout
= -1);
288 bool BulkWrite(int ep
, const void *data
, size_t size
, int timeout
= -1);
289 bool InterruptRead(int ep
, Barry::Data
&data
, int timeout
= -1);
290 bool InterruptWrite(int ep
, const Barry::Data
&data
, int timeout
= -1);
292 void BulkDrain(int ep
, int timeout
= 100);
294 bool ControlMsg(int requesttype
, int request
, int value
,
295 int index
, char *bytes
, int size
, int timeout
);
297 /////////////////////////////
300 bool GetConfiguration(unsigned char &cfg
);
303 class BXEXPORT Interface
308 Interface(Device
&dev
, int iface
);
310 bool SetAltInterface(int altSetting
);
313 // Map of Endpoint numbers (not indexes) to endpoint descriptors
314 struct BXEXPORT EndpointPair
318 EndpointDescriptor::EpType type
;
321 bool IsTypeSet() const;
322 bool IsComplete() const;
326 class BXEXPORT EndpointPairings
: public std::vector
<EndpointPair
>
329 typedef std::vector
<EndpointPair
> base_type
;
333 EndpointPairings(const std::vector
<EndpointDescriptor
*>& eps
);
335 bool IsValid() const;
341 std::vector
<DeviceID
> m_list
;
342 std::vector
<DeviceID
>::iterator m_iter
;
344 // Due to USB libraries having different ownership ideas
345 // about device IDs, Match objects must be constructed
346 // with a device list.
347 Match(DeviceList
& devices
,
348 int vendor
, int product
,
349 const char *busname
= 0, const char *devname
= 0);
352 // searches for next match, and if found, fills devid with
353 // something you can pass on to DeviceDiscover, etc
354 // returns true if next is found, false if no more
355 bool next_device(Usb::DeviceID
& devid
);