src/usbwrap.h

   1 ///
   2 /// \file       usbwrap.h
   3 ///             USB API wrapper
   4 ///
   5
   6 /*
   7     Copyright (C) 2005-2011, 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 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
  96 // Private struct for holding a library specific
  97 // device handle
  98 struct DeviceHandle;
  99
 100 // Static functions for setting up USB
 101 // The interface that usbwrap.cc uses
 102 // to interact with the USB library
 103 class BXEXPORT LibraryInterface
 104 {
 105 public:
 106         static std::string GetLastErrorString(int libusb_errcode);
 107         static int TranslateErrcode(int libusb_errcode);
 108         static int Init();
 109         static void Uninit();
 110         static void SetDataDump(bool data_dump_mode);
 111 };
 112
 113 // Forward declaration of descriptor types.
 114 class BXEXPORT DeviceDescriptor;
 115 class BXEXPORT ConfigDescriptor;
 116 class BXEXPORT InterfaceDescriptor;
 117
 118 // Private struct for holding library specific
 119 // information about endpoint descriptors
 120 struct EndpointDescriptorImpl;
 121
 122 // Encapsulates an endpoint descriptor
 123 class BXEXPORT EndpointDescriptor
 124 {
 125 public:
 126         enum EpType
 127         {
 128                 ControlType = 0,
 129                 IsochronousType = 1,
 130                 BulkType = 2,
 131                 InterruptType = 3,
 132                 InvalidType = 0xff
 133         };
 134 private:
 135         const std::auto_ptr<EndpointDescriptorImpl> m_impl;
 136         bool m_read;
 137         uint8_t m_addr;
 138         EpType m_type;
 139 public:
 140         EndpointDescriptor(InterfaceDescriptor& dev, int endpoint);
 141         ~EndpointDescriptor();
 142         bool IsRead() const;
 143         uint8_t GetAddress() const;
 144         EpType GetType() const;
 145 };
 146
 147 // Private struct for holding library specific
 148 // information about interface descriptors
 149 struct InterfaceDescriptorImpl;
 150
 151 // Encapsulates an interface descriptor
 152 //
 153 // The inherited vector methods look up endpoints
 154 class BXEXPORT InterfaceDescriptor : public std::vector<EndpointDescriptor*>
 155 {
 156         friend class EndpointDescriptor;
 157 public:
 158         typedef std::vector<EndpointDescriptor*> base_type;
 159 private:
 160         const std::auto_ptr<InterfaceDescriptorImpl> m_impl;
 161 public:
 162         InterfaceDescriptor(ConfigDescriptor& cfgdesc,
 163                             int interface, int altsetting);
 164         ~InterfaceDescriptor();
 165         uint8_t GetClass() const;
 166         uint8_t GetNumber() const;
 167         uint8_t GetAltSetting() const;
 168 };
 169
 170 // Private struct for holding library specific
 171 // information about config descriptors
 172
 173 struct ConfigDescriptorImpl;
 174
 175 // Encapsulates a configuration descriptor
 176 //
 177 // The inherited map methods look up interface descriptors
 178 class BXEXPORT ConfigDescriptor : public std::map<int, InterfaceDescriptor*>
 179 {
 180         friend class InterfaceDescriptor;
 181 public:
 182         typedef std::map<int, InterfaceDescriptor*> base_type;
 183 private:
 184         const std::auto_ptr<ConfigDescriptorImpl> m_impl;
 185 public:
 186         ConfigDescriptor(DeviceDescriptor& dev, int cfgnumber);
 187         ~ConfigDescriptor();
 188         uint8_t GetNumber() const;
 189 };
 190
 191 // Private struct for holding library specific
 192 // information about a device descriptor
 193 struct DeviceDescriptorImpl;
 194
 195 // Encapsulates a device descriptor
 196 //
 197 // The inherited map methods look up config descriptors
 198 class BXEXPORT DeviceDescriptor : public std::map<int, ConfigDescriptor*>
 199 {
 200         friend class ConfigDescriptor;
 201 public:
 202         typedef std::map<int, ConfigDescriptor*> base_type;
 203 private:
 204         const std::auto_ptr<DeviceDescriptorImpl> m_impl;
 205 public:
 206         DeviceDescriptor(DeviceID& devid);
 207         ~DeviceDescriptor();
 208 };
 209
 210 // Private struct for holding library specific
 211 // information for devices.
 212 struct DeviceListImpl;
 213
 214 class BXEXPORT DeviceList
 215 {
 216 private:
 217         // Private implementation structure
 218         const std::auto_ptr<DeviceListImpl> m_impl;
 219 public:
 220         DeviceList();
 221         ~DeviceList();
 222
 223         std::vector<DeviceID> MatchDevices(int vendor, int product,
 224                                            const char *busname, const char *devname);
 225
 226 };
 227
 228 struct PrivateDeviceData;
 229
 230 class BXEXPORT Device
 231 {
 232 private:
 233         Usb::DeviceID m_id;
 234         std::auto_ptr<Usb::DeviceHandle> m_handle;
 235
 236         int m_timeout;
 237         int m_lasterror;
 238
 239 public:
 240         Device(const Usb::DeviceID& id, int timeout = USBWRAP_DEFAULT_TIMEOUT);
 241         ~Device();
 242
 243         /////////////////////////////
 244         // Data access
 245
 246         const Usb::DeviceID& GetID() const { return m_id; }
 247         const Usb::DeviceHandle* GetHandle() const { return &*m_handle; }
 248         int GetLastError() const { return m_lasterror; } //< not thread safe...
 249                 //< use the error code stored in the exceptions to track
 250                 //< errors in threaded usage
 251         void SetLastError(int err) { m_lasterror = err; }
 252         int GetDefaultTimeout() const { return m_timeout; }
 253
 254         /////////////////////////////
 255         // Device information
 256
 257         int GetPowerLevel();
 258         int FindInterface(int ifaceClass);
 259
 260         /////////////////////////////
 261         // Device manipulation
 262
 263         bool SetConfiguration(unsigned char cfg);
 264         bool ClearHalt(int ep);
 265         bool Reset();
 266         bool DetachKernelDriver(int iface);
 267
 268         /////////////////////////////
 269         // IO functions
 270
 271         bool BulkRead(int ep, Barry::Data &data, int timeout = -1);
 272         bool BulkWrite(int ep, const Barry::Data &data, int timeout = -1);
 273         bool BulkWrite(int ep, const void *data, size_t size, int timeout = -1);
 274         bool InterruptRead(int ep, Barry::Data &data, int timeout = -1);
 275         bool InterruptWrite(int ep, const Barry::Data &data, int timeout = -1);
 276
 277         void BulkDrain(int ep, int timeout = 100);
 278
 279         bool ControlMsg(int requesttype, int request, int value,
 280                         int index, char *bytes, int size, int timeout);
 281
 282         /////////////////////////////
 283         // Combo functions
 284
 285         bool GetConfiguration(unsigned char &cfg);
 286 };
 287
 288 class BXEXPORT Interface
 289 {
 290         Device &m_dev;
 291         int m_iface;
 292 public:
 293         Interface(Device &dev, int iface);
 294         ~Interface();
 295         bool SetAltInterface(int altSetting);
 296 };
 297
 298 // Map of Endpoint numbers (not indexes) to endpoint descriptors
 299 struct BXEXPORT EndpointPair
 300 {
 301         unsigned char read;
 302         unsigned char write;
 303         EndpointDescriptor::EpType type;
 304
 305         EndpointPair();
 306         bool IsTypeSet() const;
 307         bool IsComplete() const;
 308         bool IsBulk() const;
 309 };
 310
 311 class BXEXPORT EndpointPairings : public std::vector<EndpointPair>
 312 {
 313 public:
 314         typedef std::vector<EndpointPair> base_type;
 315 private:
 316         bool m_valid;
 317 public:
 318         EndpointPairings(const std::vector<EndpointDescriptor*>& eps);
 319         ~EndpointPairings();
 320         bool IsValid() const;
 321 };
 322
 323 class BXEXPORT Match
 324 {
 325 private:
 326         std::vector<DeviceID> m_list;
 327         std::vector<DeviceID>::iterator m_iter;
 328 public:
 329         // Due to USB libraries having different ownership ideas
 330         // about device IDs, Match objects must be constructed
 331         // with a device list.
 332         Match(DeviceList& devices,
 333               int vendor, int product,
 334               const char *busname = 0, const char *devname = 0);
 335         ~Match();
 336
 337         // searches for next match, and if found, fills devid with
 338         // something you can pass on to DeviceDiscover, etc
 339         // returns true if next is found, false if no more
 340         bool next_device(Usb::DeviceID& devid);
 341 };
 342
 343 }
 344
 345 #endif