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(const EndpointDescriptor
& rhs
); // Prevent copying
156 EndpointDescriptor(InterfaceDescriptor
& dev
, int endpoint
);
157 ~EndpointDescriptor();
159 uint8_t GetAddress() const;
160 EpType
GetType() const;
163 // Private struct for holding library specific
164 // information about interface descriptors
165 struct InterfaceDescriptorImpl
;
167 // Encapsulates an interface descriptor
169 // The inherited vector methods look up endpoints
170 class BXEXPORT InterfaceDescriptor
: public std::vector
<EndpointDescriptor
*>
172 friend class EndpointDescriptor
;
174 typedef std::vector
<EndpointDescriptor
*> base_type
;
176 const std::auto_ptr
<InterfaceDescriptorImpl
> m_impl
;
178 InterfaceDescriptor(const InterfaceDescriptor
& rhs
); // Prevent copying
180 InterfaceDescriptor(ConfigDescriptor
& cfgdesc
,
181 int iface
, int altsetting
);
182 ~InterfaceDescriptor();
183 uint8_t GetClass() const;
184 uint8_t GetNumber() const;
185 uint8_t GetAltSetting() const;
188 // Private struct for holding library specific
189 // information about config descriptors
191 struct ConfigDescriptorImpl
;
193 // Encapsulates a configuration descriptor
195 // The inherited map methods look up interface descriptors
196 class BXEXPORT ConfigDescriptor
: public std::map
<int, InterfaceDescriptor
*>
198 friend class InterfaceDescriptor
;
200 typedef std::map
<int, InterfaceDescriptor
*> base_type
;
202 const std::auto_ptr
<ConfigDescriptorImpl
> m_impl
;
204 ConfigDescriptor(const ConfigDescriptor
& rhs
); // Prevent copying
206 ConfigDescriptor(DeviceDescriptor
& dev
, int cfgnumber
);
208 uint8_t GetNumber() const;
211 // Private struct for holding library specific
212 // information about a device descriptor
213 struct DeviceDescriptorImpl
;
215 // Encapsulates a device descriptor
217 // The inherited map methods look up config descriptors
218 class BXEXPORT DeviceDescriptor
: public std::map
<int, ConfigDescriptor
*>
220 friend class ConfigDescriptor
;
222 typedef std::map
<int, ConfigDescriptor
*> base_type
;
224 const std::auto_ptr
<DeviceDescriptorImpl
> m_impl
;
226 DeviceDescriptor(const DeviceDescriptor
& rhs
); // Prevent copying
228 DeviceDescriptor(DeviceID
& devid
);
232 // Private struct for holding library specific
233 // information for devices.
234 struct DeviceListImpl
;
236 class BXEXPORT DeviceList
239 // Private implementation structure
240 const std::auto_ptr
<DeviceListImpl
> m_impl
;
242 DeviceList(const DeviceList
& rhs
); // Prevent copying
247 std::vector
<DeviceID
> MatchDevices(int vendor
, int product
,
248 const char *busname
, const char *devname
);
252 struct PrivateDeviceData
;
254 class BXEXPORT Device
258 const std::auto_ptr
<Usb::DeviceHandle
> m_handle
;
263 Device(const Device
& rhs
); // Prevent copying
265 Device(const Usb::DeviceID
& id
, int timeout
= USBWRAP_DEFAULT_TIMEOUT
);
268 /////////////////////////////
271 const Usb::DeviceID
& GetID() const { return m_id
; }
272 const Usb::DeviceHandle
* GetHandle() const { return &*m_handle
; }
273 int GetLastError() const { return m_lasterror
; } //< not thread safe...
274 //< use the error code stored in the exceptions to track
275 //< errors in threaded usage
276 void SetLastError(int err
) { m_lasterror
= err
; }
277 int GetDefaultTimeout() const { return m_timeout
; }
279 /////////////////////////////
280 // Device information
283 int FindInterface(int ifaceClass
);
285 /////////////////////////////
286 // Device manipulation
288 bool SetConfiguration(unsigned char cfg
);
289 bool ClearHalt(int ep
);
291 bool IsAttachKernelDriver(int iface
);
292 bool DetachKernelDriver(int iface
);
294 /////////////////////////////
297 bool BulkRead(int ep
, Barry::Data
&data
, int timeout
= -1);
298 bool BulkWrite(int ep
, const Barry::Data
&data
, int timeout
= -1);
299 bool BulkWrite(int ep
, const void *data
, size_t size
, int timeout
= -1);
300 bool InterruptRead(int ep
, Barry::Data
&data
, int timeout
= -1);
301 bool InterruptWrite(int ep
, const Barry::Data
&data
, int timeout
= -1);
303 void BulkDrain(int ep
, int timeout
= 100);
305 bool ControlMsg(int requesttype
, int request
, int value
,
306 int index
, char *bytes
, int size
, int timeout
);
308 /////////////////////////////
311 bool GetConfiguration(unsigned char &cfg
);
314 class BXEXPORT Interface
319 Interface(Device
&dev
, int iface
);
321 bool SetAltInterface(int altSetting
);
324 // Map of Endpoint numbers (not indexes) to endpoint descriptors
325 struct BXEXPORT EndpointPair
329 EndpointDescriptor::EpType type
;
332 bool IsTypeSet() const;
333 bool IsComplete() const;
337 class BXEXPORT EndpointPairings
: public std::vector
<EndpointPair
>
340 typedef std::vector
<EndpointPair
> base_type
;
344 EndpointPairings(const std::vector
<EndpointDescriptor
*>& eps
);
346 bool IsValid() const;
352 std::vector
<DeviceID
> m_list
;
353 std::vector
<DeviceID
>::iterator m_iter
;
355 // Due to USB libraries having different ownership ideas
356 // about device IDs, Match objects must be constructed
357 // with a device list.
358 Match(DeviceList
& devices
,
359 int vendor
, int product
,
360 const char *busname
= 0, const char *devname
= 0);
363 // searches for next match, and if found, fills devid with
364 // something you can pass on to DeviceDiscover, etc
365 // returns true if next is found, false if no more
366 bool next_device(Usb::DeviceID
& devid
);