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