src/usbwrap.h

   1 ///
   2 /// \file       usbwrap.h
   3 ///             USB API wrapper
   4 ///
   5
   6 /*
   7     Copyright (C) 2005-2012, 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 public:
 154         EndpointDescriptor(InterfaceDescriptor& dev, int endpoint);
 155         ~EndpointDescriptor();
 156         bool IsRead() const;
 157         uint8_t GetAddress() const;
 158         EpType GetType() const;
 159 };
 160
 161 // Private struct for holding library specific
 162 // information about interface descriptors
 163 struct InterfaceDescriptorImpl;
 164
 165 // Encapsulates an interface descriptor
 166 //
 167 // The inherited vector methods look up endpoints
 168 class BXEXPORT InterfaceDescriptor : public std::vector<EndpointDescriptor*>
 169 {
 170         friend class EndpointDescriptor;
 171 public:
 172         typedef std::vector<EndpointDescriptor*> base_type;
 173 private:
 174         const std::auto_ptr<InterfaceDescriptorImpl> m_impl;
 175 public:
 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;
 182 };
 183
 184 // Private struct for holding library specific
 185 // information about config descriptors
 186
 187 struct ConfigDescriptorImpl;
 188
 189 // Encapsulates a configuration descriptor
 190 //
 191 // The inherited map methods look up interface descriptors
 192 class BXEXPORT ConfigDescriptor : public std::map<int, InterfaceDescriptor*>
 193 {
 194         friend class InterfaceDescriptor;
 195 public:
 196         typedef std::map<int, InterfaceDescriptor*> base_type;
 197 private:
 198         const std::auto_ptr<ConfigDescriptorImpl> m_impl;
 199 public:
 200         ConfigDescriptor(DeviceDescriptor& dev, int cfgnumber);
 201         ~ConfigDescriptor();
 202         uint8_t GetNumber() const;
 203 };
 204
 205 // Private struct for holding library specific
 206 // information about a device descriptor
 207 struct DeviceDescriptorImpl;
 208
 209 // Encapsulates a device descriptor
 210 //
 211 // The inherited map methods look up config descriptors
 212 class BXEXPORT DeviceDescriptor : public std::map<int, ConfigDescriptor*>
 213 {
 214         friend class ConfigDescriptor;
 215 public:
 216         typedef std::map<int, ConfigDescriptor*> base_type;
 217 private:
 218         const std::auto_ptr<DeviceDescriptorImpl> m_impl;
 219 public:
 220         DeviceDescriptor(DeviceID& devid);
 221         ~DeviceDescriptor();
 222 };
 223
 224 // Private struct for holding library specific
 225 // information for devices.
 226 struct DeviceListImpl;
 227
 228 class BXEXPORT DeviceList
 229 {
 230 private:
 231         // Private implementation structure
 232         const std::auto_ptr<DeviceListImpl> m_impl;
 233 public:
 234         DeviceList();
 235         ~DeviceList();
 236
 237         std::vector<DeviceID> MatchDevices(int vendor, int product,
 238                                            const char *busname, const char *devname);
 239
 240 };
 241
 242 struct PrivateDeviceData;
 243
 244 class BXEXPORT Device
 245 {
 246 private:
 247         Usb::DeviceID m_id;
 248         std::auto_ptr<Usb::DeviceHandle> m_handle;
 249
 250         int m_timeout;
 251         int m_lasterror;
 252
 253 public:
 254         Device(const Usb::DeviceID& id, int timeout = USBWRAP_DEFAULT_TIMEOUT);
 255         ~Device();
 256
 257         /////////////////////////////
 258         // Data access
 259
 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; }
 267
 268         /////////////////////////////
 269         // Device information
 270
 271         int GetPowerLevel();
 272         int FindInterface(int ifaceClass);
 273
 274         /////////////////////////////
 275         // Device manipulation
 276
 277         bool SetConfiguration(unsigned char cfg);
 278         bool ClearHalt(int ep);
 279         bool Reset();
 280         bool IsAttachKernelDriver(int iface);
 281         bool DetachKernelDriver(int iface);
 282
 283         /////////////////////////////
 284         // IO functions
 285
 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);
 291
 292         void BulkDrain(int ep, int timeout = 100);
 293
 294         bool ControlMsg(int requesttype, int request, int value,
 295                         int index, char *bytes, int size, int timeout);
 296
 297         /////////////////////////////
 298         // Combo functions
 299
 300         bool GetConfiguration(unsigned char &cfg);
 301 };
 302
 303 class BXEXPORT Interface
 304 {
 305         Device &m_dev;
 306         int m_iface;
 307 public:
 308         Interface(Device &dev, int iface);
 309         ~Interface();
 310         bool SetAltInterface(int altSetting);
 311 };
 312
 313 // Map of Endpoint numbers (not indexes) to endpoint descriptors
 314 struct BXEXPORT EndpointPair
 315 {
 316         unsigned char read;
 317         unsigned char write;
 318         EndpointDescriptor::EpType type;
 319
 320         EndpointPair();
 321         bool IsTypeSet() const;
 322         bool IsComplete() const;
 323         bool IsBulk() const;
 324 };
 325
 326 class BXEXPORT EndpointPairings : public std::vector<EndpointPair>
 327 {
 328 public:
 329         typedef std::vector<EndpointPair> base_type;
 330 private:
 331         bool m_valid;
 332 public:
 333         EndpointPairings(const std::vector<EndpointDescriptor*>& eps);
 334         ~EndpointPairings();
 335         bool IsValid() const;
 336 };
 337
 338 class BXEXPORT Match
 339 {
 340 private:
 341         std::vector<DeviceID> m_list;
 342         std::vector<DeviceID>::iterator m_iter;
 343 public:
 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);
 350         ~Match();
 351
 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);
 356 };
 357
 358 }
 359
 360 #endif