Open Lighting Architecture  Latest Git
LibUsbAdaptor.h
1 /*
2  * This program is free software; you can redistribute it and/or modify
3  * it under the terms of the GNU General Public License as published by
4  * the Free Software Foundation; either version 2 of the License, or
5  * (at your option) any later version.
6  *
7  * This program is distributed in the hope that it will be useful,
8  * but WITHOUT ANY WARRANTY; without even the implied warranty of
9  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
10  * GNU Library General Public License for more details.
11  *
12  * You should have received a copy of the GNU General Public License
13  * along with this program; if not, write to the Free Software
14  * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
15  *
16  * LibUsbAdaptor.h
17  * The wrapper around libusb calls.
18  * Copyright (C) 2014 Simon Newton
19  */
20 
21 #ifndef LIBS_USB_LIBUSBADAPTOR_H_
22 #define LIBS_USB_LIBUSBADAPTOR_H_
23 
24 #include <libusb.h>
25 #include <string>
26 
27 #include "ola/base/Macro.h"
28 #include "libs/usb/Types.h"
29 
30 namespace ola {
31 namespace usb {
32 
36 class LibUsbAdaptor {
37  public:
38  struct DeviceInformation {
39  std::string manufacturer;
40  std::string product;
41  std::string serial;
42  };
43 
44  virtual ~LibUsbAdaptor() {}
45 
46  // Device handling and enumeration
47 
53  virtual libusb_device* RefDevice(libusb_device *dev) = 0;
54 
59  virtual void UnrefDevice(libusb_device *dev) = 0;
60 
67  virtual bool OpenDevice(libusb_device *usb_device,
68  libusb_device_handle **usb_handle) = 0;
69 
78  virtual bool OpenDeviceAndClaimInterface(
79  libusb_device *usb_device,
80  int interface,
81  libusb_device_handle **usb_handle) = 0;
82 
87  virtual void Close(libusb_device_handle *usb_handle) = 0;
88 
102  virtual int SetConfiguration(libusb_device_handle *dev,
103  int configuration) = 0;
104 
117  virtual int ClaimInterface(libusb_device_handle *dev,
118  int interface_number) = 0;
119 
133  virtual int DetachKernelDriver(libusb_device_handle *dev,
134  int interface_number) = 0;
135 
136  // USB descriptors
144  virtual int GetDeviceDescriptor(
145  libusb_device *dev,
146  struct libusb_device_descriptor *descriptor) = 0;
147 
158  virtual int GetActiveConfigDescriptor(
159  libusb_device *dev,
160  struct libusb_config_descriptor **config) = 0;
161 
173  virtual int GetConfigDescriptor(libusb_device *dev,
174  uint8_t config_index,
175  struct libusb_config_descriptor **config) = 0;
176 
181  virtual void FreeConfigDescriptor(
182  struct libusb_config_descriptor *config) = 0;
183 
191  virtual bool GetStringDescriptor(libusb_device_handle *usb_handle,
192  uint8_t descriptor_index,
193  std::string *data) = 0;
194 
195  // Asynchronous device I/O
196 
202  virtual struct libusb_transfer* AllocTransfer(int iso_packets) = 0;
203 
208  virtual void FreeTransfer(struct libusb_transfer *transfer) = 0;
209 
220  virtual int SubmitTransfer(struct libusb_transfer *transfer) = 0;
221 
230  virtual int CancelTransfer(struct libusb_transfer *transfer) = 0;
231 
243  virtual void FillControlSetup(unsigned char *buffer,
244  uint8_t bmRequestType,
245  uint8_t bRequest,
246  uint16_t wValue,
247  uint16_t wIndex,
248  uint16_t wLength) = 0;
249 
261  virtual void FillControlTransfer(struct libusb_transfer *transfer,
262  libusb_device_handle *dev_handle,
263  unsigned char *buffer,
264  libusb_transfer_cb_fn callback,
265  void *user_data,
266  unsigned int timeout) = 0;
267 
281  virtual void FillBulkTransfer(struct libusb_transfer *transfer,
282  libusb_device_handle *dev_handle,
283  unsigned char endpoint,
284  unsigned char *buffer,
285  int length,
286  libusb_transfer_cb_fn callback,
287  void *user_data,
288  unsigned int timeout) = 0;
289 
301  virtual void FillInterruptTransfer(struct libusb_transfer *transfer,
302  libusb_device_handle *dev_handle,
303  unsigned char endpoint,
304  unsigned char *buffer,
305  int length,
306  libusb_transfer_cb_fn callback,
307  void *user_data,
308  unsigned int timeout) = 0;
309 
310  // Synchronous device I/O
311 
329  virtual int ControlTransfer(libusb_device_handle *dev_handle,
330  uint8_t bmRequestType,
331  uint8_t bRequest,
332  uint16_t wValue,
333  uint16_t wIndex,
334  unsigned char *data,
335  uint16_t wLength,
336  unsigned int timeout) = 0;
337 
348  virtual int BulkTransfer(struct libusb_device_handle *dev_handle,
349  unsigned char endpoint,
350  unsigned char *data,
351  int length,
352  int *transferred,
353  unsigned int timeout) = 0;
354 
364  virtual int InterruptTransfer(libusb_device_handle *dev_handle,
365  unsigned char endpoint,
366  unsigned char *data,
367  int length,
368  int *actual_length,
369  unsigned int timeout) = 0;
370 
376  virtual USBDeviceID GetDeviceId(libusb_device *device) const = 0;
377 
378  // Static helper methods.
379 
385  static bool Initialize(struct libusb_context **context);
386 
394  static bool GetDeviceInfo(
395  struct libusb_device *usb_device,
396  const struct libusb_device_descriptor &device_descriptor,
397  DeviceInformation *device_info);
398 
405  static bool CheckManufacturer(const std::string &expected,
406  const DeviceInformation &device_info);
407 
414  static bool CheckProduct(const std::string &expected,
415  const DeviceInformation &device_info);
416 
422  static bool HotplugSupported();
423 
429  static std::string ErrorCodeToString(const int error_code);
430 };
431 
435 class BaseLibUsbAdaptor : public LibUsbAdaptor {
436  public:
437  // Device handling and enumeration
438  libusb_device* RefDevice(libusb_device *dev);
439 
440  void UnrefDevice(libusb_device *dev);
441 
442  int SetConfiguration(libusb_device_handle *dev, int configuration);
443 
444  int ClaimInterface(libusb_device_handle *dev, int interface_number);
445 
446  int DetachKernelDriver(libusb_device_handle *dev, int interface_number);
447 
448  // USB descriptors
449  int GetDeviceDescriptor(libusb_device *dev,
450  struct libusb_device_descriptor *descriptor);
451 
452  int GetActiveConfigDescriptor(
453  libusb_device *dev,
454  struct libusb_config_descriptor **config);
455 
456  int GetConfigDescriptor(libusb_device *dev,
457  uint8_t config_index,
458  struct libusb_config_descriptor **config);
459 
460  void FreeConfigDescriptor(struct libusb_config_descriptor *config);
461 
462  bool GetStringDescriptor(libusb_device_handle *usb_handle,
463  uint8_t descriptor_index,
464  std::string *data);
465 
466  // Asynchronous device I/O
467  struct libusb_transfer* AllocTransfer(int iso_packets);
468 
469  void FreeTransfer(struct libusb_transfer *transfer);
470 
471  int SubmitTransfer(struct libusb_transfer *transfer);
472 
473  int CancelTransfer(struct libusb_transfer *transfer);
474 
475  void FillControlSetup(unsigned char *buffer,
476  uint8_t bmRequestType,
477  uint8_t bRequest,
478  uint16_t wValue,
479  uint16_t wIndex,
480  uint16_t wLength);
481 
482  void FillControlTransfer(struct libusb_transfer *transfer,
483  libusb_device_handle *dev_handle,
484  unsigned char *buffer,
485  libusb_transfer_cb_fn callback,
486  void *user_data,
487  unsigned int timeout);
488 
489  void FillBulkTransfer(struct libusb_transfer *transfer,
490  libusb_device_handle *dev_handle,
491  unsigned char endpoint,
492  unsigned char *buffer,
493  int length,
494  libusb_transfer_cb_fn callback,
495  void *user_data,
496  unsigned int timeout);
497 
498  void FillInterruptTransfer(struct libusb_transfer *transfer,
499  libusb_device_handle *dev_handle,
500  unsigned char endpoint,
501  unsigned char *buffer,
502  int length,
503  libusb_transfer_cb_fn callback,
504  void *user_data,
505  unsigned int timeout);
506 
507  // Synchronous device I/O
508  int ControlTransfer(libusb_device_handle *dev_handle,
509  uint8_t bmRequestType,
510  uint8_t bRequest,
511  uint16_t wValue,
512  uint16_t wIndex,
513  unsigned char *data,
514  uint16_t wLength,
515  unsigned int timeout);
516 
517  int BulkTransfer(struct libusb_device_handle *dev_handle,
518  unsigned char endpoint,
519  unsigned char *data,
520  int length,
521  int *transferred,
522  unsigned int timeout);
523 
524  int InterruptTransfer(libusb_device_handle *dev_handle,
525  unsigned char endpoint,
526  unsigned char *data,
527  int length,
528  int *actual_length,
529  unsigned int timeout);
530 
531  USBDeviceID GetDeviceId(libusb_device *device) const;
532 };
533 
540 class SynchronousLibUsbAdaptor : public BaseLibUsbAdaptor {
541  public:
542  SynchronousLibUsbAdaptor() {}
543 
544  bool OpenDevice(libusb_device *usb_device,
545  libusb_device_handle **usb_handle);
546 
547  bool OpenDeviceAndClaimInterface(libusb_device *usb_device,
548  int interface,
549  libusb_device_handle **usb_handle);
550 
551  void Close(libusb_device_handle *usb_handle);
552 
553  private:
554  DISALLOW_COPY_AND_ASSIGN(SynchronousLibUsbAdaptor);
555 };
556 
563 class AsynchronousLibUsbAdaptor : public BaseLibUsbAdaptor {
564  public:
565  explicit AsynchronousLibUsbAdaptor(class LibUsbThread *thread)
566  : m_thread(thread) {
567  }
568 
569  bool OpenDevice(libusb_device *usb_device,
570  libusb_device_handle **usb_handle);
571 
572  bool OpenDeviceAndClaimInterface(libusb_device *usb_device,
573  int interface,
574  libusb_device_handle **usb_handle);
575 
576  void Close(libusb_device_handle *usb_handle);
577 
578  int ControlTransfer(libusb_device_handle *dev_handle,
579  uint8_t bmRequestType,
580  uint8_t bRequest,
581  uint16_t wValue,
582  uint16_t wIndex,
583  unsigned char *data,
584  uint16_t wLength,
585  unsigned int timeout);
586 
587  int BulkTransfer(struct libusb_device_handle *dev_handle,
588  unsigned char endpoint,
589  unsigned char *data,
590  int length,
591  int *transferred,
592  unsigned int timeout);
593 
594  int InterruptTransfer(libusb_device_handle *dev_handle,
595  unsigned char endpoint,
596  unsigned char *data,
597  int length,
598  int *actual_length,
599  unsigned int timeout);
600 
601  private:
602  class LibUsbThread *m_thread;
603 
604  DISALLOW_COPY_AND_ASSIGN(AsynchronousLibUsbAdaptor);
605 };
606 } // namespace usb
607 } // namespace ola
608 #endif // LIBS_USB_LIBUSBADAPTOR_H_
ola::usb::LibUsbAdaptor::FillInterruptTransfer
virtual void FillInterruptTransfer(struct libusb_transfer *transfer, libusb_device_handle *dev_handle, unsigned char endpoint, unsigned char *buffer, int length, libusb_transfer_cb_fn callback, void *user_data, unsigned int timeout)=0
Wraps libusb_fill_interrupt_transfer.
ola::usb::LibUsbAdaptor::Close
virtual void Close(libusb_device_handle *usb_handle)=0
Close a libusb handle.
ola::usb::LibUsbAdaptor::SetConfiguration
virtual int SetConfiguration(libusb_device_handle *dev, int configuration)=0
Wraps libusb_set_configuration.
ola::usb::LibUsbAdaptor::InterruptTransfer
virtual int InterruptTransfer(libusb_device_handle *dev_handle, unsigned char endpoint, unsigned char *data, int length, int *actual_length, unsigned int timeout)=0
Wraps libusb_interrupt_transfer.
ola::usb::LibUsbAdaptor::DetachKernelDriver
virtual int DetachKernelDriver(libusb_device_handle *dev, int interface_number)=0
Detach a kernel driver.
ola::usb::LibUsbAdaptor::CheckManufacturer
static bool CheckManufacturer(const std::string &expected, const DeviceInformation &device_info)
Check if the manufacturer string matches the expected value.
Definition: LibUsbAdaptor.cpp:147
DISALLOW_COPY_AND_ASSIGN
#define DISALLOW_COPY_AND_ASSIGN(TypeName)
Creates dummy copy constructor and assignment operator declarations.
Definition: Macro.h:44
ola::usb::BaseLibUsbAdaptor
The base LibUsbAdaptor that passes most calls through to libusb.
Definition: LibUsbAdaptor.h:435
ola::usb::LibUsbAdaptor::ClaimInterface
virtual int ClaimInterface(libusb_device_handle *dev, int interface_number)=0
Wraps libusb_claim_interface.
ola::usb::LibUsbAdaptor::UnrefDevice
virtual void UnrefDevice(libusb_device *dev)=0
Wraps libusb_unref_device.
ola::usb::USBDeviceID
Definition: Types.h:30
ola::usb::LibUsbAdaptor::BulkTransfer
virtual int BulkTransfer(struct libusb_device_handle *dev_handle, unsigned char endpoint, unsigned char *data, int length, int *transferred, unsigned int timeout)=0
Wraps libusb_bulk_transfer.
ola::usb::LibUsbAdaptor::FreeConfigDescriptor
virtual void FreeConfigDescriptor(struct libusb_config_descriptor *config)=0
Wraps busb_free_config_descriptor.
ola::usb::LibUsbAdaptor::CancelTransfer
virtual int CancelTransfer(struct libusb_transfer *transfer)=0
Wraps libusb_cancel_transfer.
ola::usb::LibUsbAdaptor::GetDeviceId
virtual USBDeviceID GetDeviceId(libusb_device *device) const =0
Get the USBDeviceID for a device.
ola::usb::LibUsbAdaptor::ControlTransfer
virtual int ControlTransfer(libusb_device_handle *dev_handle, uint8_t bmRequestType, uint8_t bRequest, uint16_t wValue, uint16_t wIndex, unsigned char *data, uint16_t wLength, unsigned int timeout)=0
Wraps libusb_control_transfer().
ola::usb::LibUsbAdaptor::GetActiveConfigDescriptor
virtual int GetActiveConfigDescriptor(libusb_device *dev, struct libusb_config_descriptor **config)=0
Wraps libusb_get_active_config_descriptor.
ola::usb::LibUsbAdaptor::RefDevice
virtual libusb_device * RefDevice(libusb_device *dev)=0
Wraps libusb_ref_device.
ola::usb::LibUsbAdaptor::GetDeviceInfo
static bool GetDeviceInfo(struct libusb_device *usb_device, const struct libusb_device_descriptor &device_descriptor, DeviceInformation *device_info)
Fetch the manufacturer, product and serial strings from a device.
Definition: LibUsbAdaptor.cpp:116
ola::usb::LibUsbAdaptor::DeviceInformation
Definition: LibUsbAdaptor.h:38
ola::usb::LibUsbAdaptor::FillControlTransfer
virtual void FillControlTransfer(struct libusb_transfer *transfer, libusb_device_handle *dev_handle, unsigned char *buffer, libusb_transfer_cb_fn callback, void *user_data, unsigned int timeout)=0
Wraps libusb_fill_control_transfer.
ola::usb::LibUsbAdaptor::SubmitTransfer
virtual int SubmitTransfer(struct libusb_transfer *transfer)=0
Wraps libusb_submit_transfer.
ola::usb::LibUsbThread
The base class for the dedicated libusb thread.
Definition: LibUsbThread.h:55
ola::usb::LibUsbAdaptor::ErrorCodeToString
static std::string ErrorCodeToString(const int error_code)
Try and convert an error code to a string.
Definition: LibUsbAdaptor.cpp:175
ola::usb::LibUsbAdaptor::GetConfigDescriptor
virtual int GetConfigDescriptor(libusb_device *dev, uint8_t config_index, struct libusb_config_descriptor **config)=0
Wraps libusb_get_config_descriptor.
ola::usb::LibUsbAdaptor::OpenDevice
virtual bool OpenDevice(libusb_device *usb_device, libusb_device_handle **usb_handle)=0
Open a libusb device.
ola::usb::LibUsbAdaptor::Initialize
static bool Initialize(struct libusb_context **context)
Initialize a new libusb context.
Definition: LibUsbAdaptor.cpp:107
ola::usb::LibUsbAdaptor::GetStringDescriptor
virtual bool GetStringDescriptor(libusb_device_handle *usb_handle, uint8_t descriptor_index, std::string *data)=0
Get the value of a string descriptor.
ola::usb::LibUsbAdaptor::HotplugSupported
static bool HotplugSupported()
Check if this platform supports hotplug.
Definition: LibUsbAdaptor.cpp:167
Macro.h
Helper macros.
ola::usb::LibUsbAdaptor::FreeTransfer
virtual void FreeTransfer(struct libusb_transfer *transfer)=0
Wraps libusb_free_transfer.
ola::usb::LibUsbAdaptor::CheckProduct
static bool CheckProduct(const std::string &expected, const DeviceInformation &device_info)
Check if the product string matches the expected value.
Definition: LibUsbAdaptor.cpp:157
ola::usb::LibUsbAdaptor::FillBulkTransfer
virtual void FillBulkTransfer(struct libusb_transfer *transfer, libusb_device_handle *dev_handle, unsigned char endpoint, unsigned char *buffer, int length, libusb_transfer_cb_fn callback, void *user_data, unsigned int timeout)=0
Wraps libusb_fill_bulk_transfer.
ola::usb::LibUsbAdaptor::OpenDeviceAndClaimInterface
virtual bool OpenDeviceAndClaimInterface(libusb_device *usb_device, int interface, libusb_device_handle **usb_handle)=0
Open a libusb device and claim an interface.
ola
The namespace containing all OLA symbols.
Definition: Credentials.cpp:44
ola::usb::SynchronousLibUsbAdaptor
A LibUsbAdaptor for use with Synchronous widgets.
Definition: LibUsbAdaptor.h:540
ola::usb::AsynchronousLibUsbAdaptor
A LibUsbAdaptor for use with Asynchronous widgets.
Definition: LibUsbAdaptor.h:563
ola::usb::LibUsbAdaptor::GetDeviceDescriptor
virtual int GetDeviceDescriptor(libusb_device *dev, struct libusb_device_descriptor *descriptor)=0
Wraps libusb_get_device_descriptor.
ola::usb::LibUsbAdaptor::FillControlSetup
virtual void FillControlSetup(unsigned char *buffer, uint8_t bmRequestType, uint8_t bRequest, uint16_t wValue, uint16_t wIndex, uint16_t wLength)=0
Wraps libusb_fill_control_setup.
ola::usb::LibUsbAdaptor::AllocTransfer
virtual struct libusb_transfer * AllocTransfer(int iso_packets)=0
Wraps libusb_alloc_transfer.
ola::usb::LibUsbAdaptor
Wraps calls to libusb so we can test the code.
Definition: LibUsbAdaptor.h:36
Generated on Mon Jan 2 2023 23:40:35 for Open Lighting Architecture by   doxygen 1.8.13