src/usbwrap.h

   1 ///
   2 /// \file       usbwrap.h
   3 ///             USB API wrapper
   4 ///
   5
   6 /*
   7     Copyright (C) 2005-2013, Chris Frey
   8     Portions Copyright (C) 2011, RealVNC Ltd.
   9
  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.
  14
  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.
  18
  19     See the GNU General Public License in the COPYING file at the
  20     root directory of this project for more details.
  21 */
  22
  23
  24 #ifndef __SB_USBWRAP_H__
  25 #define __SB_USBWRAP_H__
  26
  27 #include "dll.h"
  28
  29 #include <memory>
  30 #include <tr1/memory>
  31 #include <vector>
  32 #include <map>
  33 #include "error.h"
  34
  35 #define USBWRAP_DEFAULT_TIMEOUT 30000
  36
  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
  41
  42 namespace Barry { class Data; }
  43
  44 /// Namespace for the libusb-related wrapper classes.  This namespace
  45 /// may change in the future.
  46 namespace Usb {
  47
  48 /// \addtogroup exceptions
  49 /// @{
  50
  51 /// Thrown on low level USB errors.
  52 class BXEXPORT Error : public Barry::Error
  53 {
  54         int m_libusb_errcode;
  55
  56 public:
  57         Error(const std::string &str);
  58         Error(int libusb_errcode, const std::string &str);
  59
  60         // can return 0 in some case, if unknown error code
  61         int libusb_errcode() const { return m_libusb_errcode; }
  62
  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;
  66 };
  67
  68 class BXEXPORT Timeout : public Error
  69 {
  70 public:
  71         Timeout(const std::string &str) : Error(str) {}
  72         Timeout(int errcode, const std::string &str)
  73                 : Error(errcode, str) {}
  74 };
  75
  76 /// @}
  77
  78 // Private struct for holding library specific
  79 // a unique identifier to a connected device.
  80 class DeviceIDImpl;
  81
  82 class BXEXPORT DeviceID
  83 {
  84 public:
  85         std::tr1::shared_ptr<DeviceIDImpl> m_impl;
  86 public:
  87         // Takes ownership of impl
  88         DeviceID(DeviceIDImpl* impl = NULL);
  89         ~DeviceID();
  90         const char* GetBusName() const;
  91         uint16_t GetNumber() const;
  92         const char* GetFilename() const;
  93         uint16_t GetIdProduct() const;
  94
  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;
  98 };
  99
 100 // Private struct for holding a library specific
 101 // device handle
 102 struct DeviceHandle;
 103
 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
 108 {
 109 public:
 110         static std::string GetLastErrorString(int libusb_errcode);
 111
 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);
 119
 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);
 125 };
 126
 127 // Forward declaration of descriptor types.
 128 class BXEXPORT DeviceDescriptor;
 129 class BXEXPORT ConfigDescriptor;
 130 class BXEXPORT InterfaceDescriptor;
 131
 132 // Private struct for holding library specific
 133 // information about endpoint descriptors
 134 struct EndpointDescriptorImpl;
 135
 136 // Encapsulates an endpoint descriptor
 137 class BXEXPORT EndpointDescriptor
 138 {
 139 public:
 140         enum EpType
 141         {
 142                 ControlType = 0,
 143                 IsochronousType = 1,
 144                 BulkType = 2,
 145                 InterruptType = 3,
 146                 InvalidType = 0xff
 147         };
 148 private:
 149         const std::auto_ptr<EndpointDescriptorImpl> m_impl;
 150         bool m_read;
 151         uint8_t m_addr;
 152         EpType m_type;
 153 private:
 154         EndpointDescriptor(const EndpointDescriptor& rhs); // Prevent copying
 155 public:
 156         EndpointDescriptor(InterfaceDescriptor& dev, int endpoint);
 157         ~EndpointDescriptor();
 158         bool IsRead() const;
 159         uint8_t GetAddress() const;
 160         EpType GetType() const;
 161 };
 162
 163 // Private struct for holding library specific
 164 // information about interface descriptors
 165 struct InterfaceDescriptorImpl;
 166
 167 // Encapsulates an interface descriptor
 168 //
 169 // The inherited vector methods look up endpoints
 170 class BXEXPORT InterfaceDescriptor : public std::vector<EndpointDescriptor*>
 171 {
 172         friend class EndpointDescriptor;
 173 public:
 174         typedef std::vector<EndpointDescriptor*> base_type;
 175 private:
 176         const std::auto_ptr<InterfaceDescriptorImpl> m_impl;
 177 private:
 178         InterfaceDescriptor(const InterfaceDescriptor& rhs); // Prevent copying
 179 public:
 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;
 186 };
 187
 188 // Private struct for holding library specific
 189 // information about config descriptors
 190
 191 struct ConfigDescriptorImpl;
 192
 193 // Encapsulates a configuration descriptor
 194 //
 195 // The inherited map methods look up interface descriptors
 196 class BXEXPORT ConfigDescriptor : public std::map<int, InterfaceDescriptor*>
 197 {
 198         friend class InterfaceDescriptor;
 199 public:
 200         typedef std::map<int, InterfaceDescriptor*> base_type;
 201 private:
 202         const std::auto_ptr<ConfigDescriptorImpl> m_impl;
 203 private:
 204         ConfigDescriptor(const ConfigDescriptor& rhs); // Prevent copying
 205 public:
 206         ConfigDescriptor(DeviceDescriptor& dev, int cfgnumber);
 207         ~ConfigDescriptor();
 208         uint8_t GetNumber() const;
 209 };
 210
 211 // Private struct for holding library specific
 212 // information about a device descriptor
 213 struct DeviceDescriptorImpl;
 214
 215 // Encapsulates a device descriptor
 216 //
 217 // The inherited map methods look up config descriptors
 218 class BXEXPORT DeviceDescriptor : public std::map<int, ConfigDescriptor*>
 219 {
 220         friend class ConfigDescriptor;
 221 public:
 222         typedef std::map<int, ConfigDescriptor*> base_type;
 223 private:
 224         const std::auto_ptr<DeviceDescriptorImpl> m_impl;
 225 private:
 226         DeviceDescriptor(const DeviceDescriptor& rhs); // Prevent copying
 227 public:
 228         DeviceDescriptor(DeviceID& devid);
 229         ~DeviceDescriptor();
 230 };
 231
 232 // Private struct for holding library specific
 233 // information for devices.
 234 struct DeviceListImpl;
 235
 236 class BXEXPORT DeviceList
 237 {
 238 private:
 239         // Private implementation structure
 240         const std::auto_ptr<DeviceListImpl> m_impl;
 241 private:
 242         DeviceList(const DeviceList& rhs); // Prevent copying
 243 public:
 244         DeviceList();
 245         ~DeviceList();
 246
 247         std::vector<DeviceID> MatchDevices(int vendor, int product,
 248                                            const char *busname, const char *devname);
 249
 250 };
 251
 252 struct PrivateDeviceData;
 253
 254 class BXEXPORT Device
 255 {
 256 private:
 257         Usb::DeviceID m_id;
 258         const std::auto_ptr<Usb::DeviceHandle> m_handle;
 259
 260         int m_timeout;
 261         int m_lasterror;
 262 private:
 263         Device(const Device& rhs); // Prevent copying
 264 public:
 265         Device(const Usb::DeviceID& id, int timeout = USBWRAP_DEFAULT_TIMEOUT);
 266         ~Device();
 267
 268         /////////////////////////////
 269         // Data access
 270
 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; }
 278
 279         /////////////////////////////
 280         // Device information
 281
 282         int GetPowerLevel();
 283         int FindInterface(int ifaceClass);
 284         std::string GetSimpleSerialNumber();
 285
 286         /////////////////////////////
 287         // Device manipulation
 288
 289         bool SetConfiguration(unsigned char cfg);
 290         bool ClearHalt(int ep);
 291         bool Reset();
 292         bool IsAttachKernelDriver(int iface);
 293         bool DetachKernelDriver(int iface);
 294
 295         /////////////////////////////
 296         // IO functions
 297
 298         bool BulkRead(int ep, Barry::Data &data, int timeout = -1);
 299         bool BulkWrite(int ep, const Barry::Data &data, int timeout = -1);
 300         bool BulkWrite(int ep, const void *data, size_t size, int timeout = -1);
 301         bool InterruptRead(int ep, Barry::Data &data, int timeout = -1);
 302         bool InterruptWrite(int ep, const Barry::Data &data, int timeout = -1);
 303
 304         void BulkDrain(int ep, int timeout = 100);
 305
 306         bool ControlMsg(int requesttype, int request, int value,
 307                         int index, char *bytes, int size, int timeout);
 308
 309         /////////////////////////////
 310         // Combo functions
 311
 312         bool GetConfiguration(unsigned char &cfg);
 313 };
 314
 315 class BXEXPORT Interface
 316 {
 317         Device &m_dev;
 318         int m_iface;
 319 public:
 320         Interface(Device &dev, int iface);
 321         ~Interface();
 322         bool SetAltInterface(int altSetting);
 323 };
 324
 325 // Map of Endpoint numbers (not indexes) to endpoint descriptors
 326 struct BXEXPORT EndpointPair
 327 {
 328         unsigned char read;
 329         unsigned char write;
 330         EndpointDescriptor::EpType type;
 331
 332         EndpointPair();
 333         bool IsTypeSet() const;
 334         bool IsComplete() const;
 335         bool IsBulk() const;
 336 };
 337
 338 class BXEXPORT EndpointPairings : public std::vector<EndpointPair>
 339 {
 340 public:
 341         typedef std::vector<EndpointPair> base_type;
 342 private:
 343         bool m_valid;
 344 public:
 345         EndpointPairings(const std::vector<EndpointDescriptor*>& eps);
 346         ~EndpointPairings();
 347         bool IsValid() const;
 348 };
 349
 350 class BXEXPORT Match
 351 {
 352 private:
 353         std::vector<DeviceID> m_list;
 354         std::vector<DeviceID>::iterator m_iter;
 355 public:
 356         // Due to USB libraries having different ownership ideas
 357         // about device IDs, Match objects must be constructed
 358         // with a device list.
 359         Match(DeviceList& devices,
 360               int vendor, int product,
 361               const char *busname = 0, const char *devname = 0);
 362         ~Match();
 363
 364         // searches for next match, and if found, fills devid with
 365         // something you can pass on to DeviceDiscover, etc
 366         // returns true if next is found, false if no more
 367         bool next_device(Usb::DeviceID& devid);
 368 };
 369
 370 }
 371
 372 #endif