Open Lighting Architecture: ola::plugin::usbdmx::LibUsbAdaptor Class Reference

| Open Lighting Architecture 0.10.9

Loading...
Searching...
No Matches
Classes | Public Member Functions | Static Public Member Functions | List of all members
ola::plugin::usbdmx::LibUsbAdaptor Class Referenceabstract

## Detailed Description

Wraps calls to libusb so we can test the code.

Inheritance diagram for ola::plugin::usbdmx::LibUsbAdaptor:

## Classes
struct | DeviceInformation

## Public Member Functions
virtual libusb_device * | RefDevice (libusb_device *dev)=0
| Wraps libusb_ref_device.
virtual void | UnrefDevice (libusb_device *dev)=0
| Wraps libusb_unref_device.
virtual bool | OpenDevice (libusb_device *usb_device, libusb_device_handle **usb_handle)=0
| Open a libusb device.
virtual bool | OpenDeviceAndClaimInterface (libusb_device *usb_device, int interface, libusb_device_handle **usb_handle)=0
| Open a libusb device and claim an interface.
virtual void | Close (libusb_device_handle *usb_handle)=0
| Close a libusb handle.
virtual int | SetConfiguration (libusb_device_handle *dev, int configuration)=0
| Wraps libusb_set_configuration.
virtual int | ClaimInterface (libusb_device_handle *dev, int interface_number)=0
| Wraps libusb_claim_interface.
virtual int | DetachKernelDriver (libusb_device_handle *dev, int interface_number)=0
| Detach a kernel driver.
virtual int | GetDeviceDescriptor (libusb_device *dev, struct libusb_device_descriptor *descriptor)=0
| Wraps libusb_get_device_descriptor.
virtual int | GetActiveConfigDescriptor (libusb_device *dev, struct libusb_config_descriptor **config)=0
| Wraps libusb_get_active_config_descriptor.
virtual int | GetConfigDescriptor (libusb_device *dev, uint8_t config_index, struct libusb_config_descriptor **config)=0
| Wraps libusb_get_config_descriptor.
virtual void | FreeConfigDescriptor (struct libusb_config_descriptor *config)=0
| Wraps busb_free_config_descriptor.
virtual bool | GetStringDescriptor (libusb_device_handle *usb_handle, uint8_t descriptor_index, std::string *data)=0
| Get the value of a string descriptor.
virtual struct libusb_transfer * | AllocTransfer (int iso_packets)=0
| Wraps libusb_alloc_transfer.
virtual void | FreeTransfer (struct libusb_transfer *transfer)=0
| Wraps libusb_free_transfer.
virtual int | SubmitTransfer (struct libusb_transfer *transfer)=0
| Wraps libusb_submit_transfer.
virtual int | CancelTransfer (struct libusb_transfer *transfer)=0
| Wraps libusb_cancel_transfer.
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.
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.
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.
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.
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().
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.
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.
virtual USBDeviceID | GetDeviceId (libusb_device *device) const=0
| Get the USBDeviceID for a device.

## Static Public Member Functions
static bool | Initialize (struct libusb_context **context)
| Initialize a new libusb context.
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.
static bool | CheckManufacturer (const std::string &expected, const DeviceInformation &device_info)
| Check if the manufacturer string matches the expected value.
static bool | CheckProduct (const std::string &expected, const DeviceInformation &device_info)
| Check if the product string matches the expected value.
static bool | HotplugSupported ()
| Check if this platform supports hotplug.
static std::string | ErrorCodeToString (const int error_code)
| Try and convert an error code to a string.

## Member Function Documentation

## ◆ AllocTransfer()

virtual struct libusb_transfer * ola::usb::LibUsbAdaptor::AllocTransfer | ( | int | iso_packets | ) |
| pure virtual

Wraps libusb_alloc_transfer.

Parameters

  iso_packets | number of isochronous packet descriptors to allocate

Returns
  a newly allocated transfer, or NULL on error

## ◆ BulkTransfer()

virtual int ola::usb::LibUsbAdaptor::BulkTransfer | ( | struct libusb_device_handle * | dev_handle,
|  | unsigned char | endpoint,
|  | unsigned char * | data,
|  | int | length,
|  | int * | transferred,
|  | unsigned int | timeout )
| pure virtual

Wraps libusb_bulk_transfer.

Returns
  0 on success and populates transferred
  LIBUSB_ERROR_TIMEOUT if the transfer timed out (and populates transferred)
  LIBUSB_ERROR_PIPE if the endpoint halted
  LIBUSB_ERROR_OVERFLOW if the device offered more data, see
  LIBUSB_ERROR_NO_DEVICE if the device has been disconnected
  another LIBUSB_ERROR code on other failures

## ◆ CancelTransfer()

virtual int ola::usb::LibUsbAdaptor::CancelTransfer | ( | struct libusb_transfer * | transfer | ) |
| pure virtual

Wraps libusb_cancel_transfer.

Parameters

  transfer | the transfer to cancel

Returns
  0 on success
  LIBUSB_ERROR_NOT_FOUND if the transfer is already complete or cancelled.
  a LIBUSB_ERROR code on failure

## ◆ CheckManufacturer()

bool ola::usb::LibUsbAdaptor::CheckManufacturer | ( | const std::string & | expected,
|  | const DeviceInformation & | device_info )
| static

Check if the manufacturer string matches the expected value.

Parameters

  expected | The expected manufacturer string.
  device_info | The DeviceInformation struct to check against.

Returns
  true if the strings matched, false otherwise.

## ◆ CheckProduct()

bool ola::usb::LibUsbAdaptor::CheckProduct | ( | const std::string & | expected,
|  | const DeviceInformation & | device_info )
| static

Check if the product string matches the expected value.

Parameters

  expected | The expected product string.
  device_info | The DeviceInformation struct to check against.

Returns
  true if the strings matched, false otherwise.

## ◆ ClaimInterface()

virtual int ola::usb::LibUsbAdaptor::ClaimInterface | ( | libusb_device_handle * | dev,
|  | int | interface_number )
| pure virtual

Wraps libusb_claim_interface.

Parameters

  dev | a device handle
  interface_number | the bInterfaceNumber of the interface you wish to claim

Returns
  0 on success
  LIBUSB_ERROR_NOT_FOUND if the requested interface does not exist
  LIBUSB_ERROR_BUSY if another program or driver has claimed the interface
  LIBUSB_ERROR_NO_DEVICE if the device has been disconnected
  a LIBUSB_ERROR code on other failure

## ◆ Close()

virtual void ola::usb::LibUsbAdaptor::Close | ( | libusb_device_handle * | usb_handle | ) |
| pure virtual

Close a libusb handle.

Parameters

  usb_handle | the handle to close.

## ◆ ControlTransfer()

virtual int ola::usb::LibUsbAdaptor::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 )
| pure virtual

Wraps libusb_control_transfer().

Parameters

  | dev_handle | a handle for the device to communicate with
  | bmRequestType | the request type field for the setup packet
  | bRequest | the request field for the setup packet
  | wValue | the value field for the setup packet
  | wIndex | the index field for the setup packet
  [in,out] | data | a suitably-sized data buffer for either input or output (depending on direction bits within bmRequestType)
  | wLength | the length field for the setup packet. The data buffer should be at least this size.
  | timeout | timeout (in milliseconds) that this function should wait before giving up due to no response being received. For an unlimited timeout, use value 0.

Returns
  on success, the number of bytes actually transferred

## ◆ DetachKernelDriver()

virtual int ola::usb::LibUsbAdaptor::DetachKernelDriver | ( | libusb_device_handle * | dev,
|  | int | interface_number )
| pure virtual

Detach a kernel driver.

Parameters

  dev | a device handle
  interface_number | the interface to detach the driver from

Returns
  0 on success
  LIBUSB_ERROR_NOT_FOUND if no kernel driver was active
  LIBUSB_ERROR_INVALID_PARAM if the interface does not exist
  LIBUSB_ERROR_NO_DEVICE if the device has been disconnected
  LIBUSB_ERROR_NOT_SUPPORTED on platforms where the functionality is not available
  another LIBUSB_ERROR code on other failure

## ◆ ErrorCodeToString()

string ola::usb::LibUsbAdaptor::ErrorCodeToString | ( | const int | error_code | ) |
| static

Try and convert an error code to a string.

Parameters

  error_code | The error code.

Returns
  A string representing the error code.

## ◆ FillBulkTransfer()

virtual void ola::usb::LibUsbAdaptor::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 )
| pure virtual

Wraps libusb_fill_bulk_transfer.

Parameters

  [out] | transfer | the transfer to populate
  | dev_handle | handle of the device that will handle the transfer
  | endpoint | address of the endpoint where this transfer will be sent
  | buffer | data buffer. If provided, this function will interpret the first 8 bytes as a setup packet and infer the transfer length from that. This pointer must be aligned to at least 2 bytes boundary.
  | length | length of data buffer
  | callback | callback function to be invoked on transfer completion
  | user_data | user data to pass to callback function
  | timeout | timeout for the transfer in milliseconds

## ◆ FillControlSetup()

virtual void ola::usb::LibUsbAdaptor::FillControlSetup | ( | unsigned char * | buffer,
|  | uint8_t | bmRequestType,
|  | uint8_t | bRequest,
|  | uint16_t | wValue,
|  | uint16_t | wIndex,
|  | uint16_t | wLength )
| pure virtual

Wraps libusb_fill_control_setup.

Parameters

  [out] | buffer | buffer to output the setup packet into This pointer must be aligned to at least 2 bytes boundary.
  | bmRequestType | the request type field for the setup packet
  | bRequest | the request field for the setup packet
  | wValue | the value field for the setup packet
  | wIndex | the index field for the setup packet
  | wLength | the length field for the setup packet. The data buffer should be at least this size.

## ◆ FillControlTransfer()

virtual void ola::usb::LibUsbAdaptor::FillControlTransfer | ( | struct libusb_transfer * | transfer,
|  | libusb_device_handle * | dev_handle,
|  | unsigned char * | buffer,
|  | libusb_transfer_cb_fn | callback,
|  | void * | user_data,
|  | unsigned int | timeout )
| pure virtual

Wraps libusb_fill_control_transfer.

Parameters

  [out] | transfer | the transfer to populate
  | dev_handle | handle of the device that will handle the transfer
  | buffer | data buffer. If provided, this function will interpret the first 8 bytes as a setup packet and infer the transfer length from that. This pointer must be aligned to at least 2 bytes boundary.
  | callback | callback function to be invoked on transfer completion
  | user_data | user data to pass to callback function
  | timeout | timeout for the transfer in milliseconds

## ◆ FillInterruptTransfer()

virtual void ola::usb::LibUsbAdaptor::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 )
| pure virtual

Wraps libusb_fill_interrupt_transfer.

Parameters

  [out] | transfer | the transfer to populate
  | dev_handle | handle of the device that will handle the transfer
  | endpoint | address of the endpoint where this transfer will be sent
  | buffer | data buffer
  | length | length of data buffer
  | callback | callback function to be invoked on transfer completion
  | user_data | user data to pass to callback function
  | timeout | timeout for the transfer in milliseconds

## ◆ FreeConfigDescriptor()

virtual void ola::usb::LibUsbAdaptor::FreeConfigDescriptor | ( | struct libusb_config_descriptor * | config | ) |
| pure virtual

Wraps busb_free_config_descriptor.

Parameters

  config | the configuration descriptor to free

## ◆ FreeTransfer()

virtual void ola::usb::LibUsbAdaptor::FreeTransfer | ( | struct libusb_transfer * | transfer | ) |
| pure virtual

Wraps libusb_free_transfer.

Parameters

  transfer | the transfer to free

## ◆ GetActiveConfigDescriptor()

virtual int ola::usb::LibUsbAdaptor::GetActiveConfigDescriptor | ( | libusb_device * | dev,
|  | struct libusb_config_descriptor ** | config )
| pure virtual

Wraps libusb_get_active_config_descriptor.

Parameters

  | dev | a device
  [out] | config | output location for the USB configuration descriptor. Only valid if 0 was returned. Must be freed with libusb_free_config_descriptor() after use.

Returns
  0 on success
  LIBUSB_ERROR_NOT_FOUND if the device is in unconfigured state
  another LIBUSB_ERROR code on error

## ◆ GetConfigDescriptor()

virtual int ola::usb::LibUsbAdaptor::GetConfigDescriptor | ( | libusb_device * | dev,
|  | uint8_t | config_index,
|  | struct libusb_config_descriptor ** | config )
| pure virtual

Wraps libusb_get_config_descriptor.

Parameters

  | dev | a device
  | config_index | the index of the configuration you wish to retrieve
  [out] | config | output location for the USB configuration descriptor. Only valid if 0 was returned. Must be freed with libusb_free_config_descriptor() after use.

Returns
  0 on success
  LIBUSB_ERROR_NOT_FOUND if the configuration does not exist
  another LIBUSB_ERROR code on error

## ◆ GetDeviceDescriptor()

virtual int ola::usb::LibUsbAdaptor::GetDeviceDescriptor | ( | libusb_device * | dev,
|  | struct libusb_device_descriptor * | descriptor )
| pure virtual

Wraps libusb_get_device_descriptor.

Parameters

  | dev | a device
  [out] | descriptor | The device descriptor.

Returns
  0 on success
  another LIBUSB_ERROR code on error

## ◆ GetDeviceId()

virtual USBDeviceID ola::usb::LibUsbAdaptor::GetDeviceId | ( | libusb_device * | device | ) | const
| pure virtual

Get the USBDeviceID for a device.

Parameters

  device | The libusb device to get the ID of.

Returns
  The USBDeviceID for this device.

## ◆ GetDeviceInfo()

bool ola::usb::LibUsbAdaptor::GetDeviceInfo | ( | struct libusb_device * | usb_device,
|  | const struct libusb_device_descriptor & | device_descriptor,
|  | DeviceInformation * | device_info )
| static

Fetch the manufacturer, product and serial strings from a device.

Parameters

  | usb_device | The USB device to get information for.
  | device_descriptor | The descriptor to use
  [out] | device_info | The DeviceInformation struct to populate.

Returns
  true if we fetched the information, false otherwise.

## ◆ GetStringDescriptor()

virtual bool ola::usb::LibUsbAdaptor::GetStringDescriptor | ( | libusb_device_handle * | usb_handle,
|  | uint8_t | descriptor_index,
|  | std::string * | data )
| pure virtual

Get the value of a string descriptor.

Parameters

  | usb_handle | The USB device handle
  | descriptor_index | The index of the string descriptor to fetch.
  [out] | data | The value of the string descriptor.

Returns
  true if the string descriptor was retrieved, false otherwise.

## ◆ HotplugSupported()

bool ola::usb::LibUsbAdaptor::HotplugSupported | ( |  | ) |
| static

Check if this platform supports hotplug.

Returns
  true if hotplug is supported and enabled on this platform, false otherwise.

## ◆ Initialize()

bool ola::usb::LibUsbAdaptor::Initialize | ( | struct libusb_context ** | context | ) |
| static

Initialize a new libusb context.

Parameters

  context | A pointer to a libusb context.

Returns
  true if the context is initialized, false otherwise.

## ◆ InterruptTransfer()

virtual int ola::usb::LibUsbAdaptor::InterruptTransfer | ( | libusb_device_handle * | dev_handle,
|  | unsigned char | endpoint,
|  | unsigned char * | data,
|  | int | length,
|  | int * | actual_length,
|  | unsigned int | timeout )
| pure virtual

Wraps libusb_interrupt_transfer.

Returns
  0 on success and populates transferred
  LIBUSB_ERROR_TIMEOUT if the transfer timed out
  LIBUSB_ERROR_PIPE if the endpoint halted
  LIBUSB_ERROR_OVERFLOW if the device offered more data, see
  LIBUSB_ERROR_NO_DEVICE if the device has been disconnected
  another LIBUSB_ERROR code on other error

## ◆ OpenDevice()

virtual bool ola::usb::LibUsbAdaptor::OpenDevice | ( | libusb_device * | usb_device,
|  | libusb_device_handle ** | usb_handle )
| pure virtual

Open a libusb device.

Parameters

  | usb_device | The usb device to open.
  [out] | usb_handle | the new device handle.

Returns
  true if the device was opened, false otherwise.

## ◆ OpenDeviceAndClaimInterface()

virtual bool ola::usb::LibUsbAdaptor::OpenDeviceAndClaimInterface | ( | libusb_device * | usb_device,
|  | int | interface,
|  | libusb_device_handle ** | usb_handle )
| pure virtual

Open a libusb device and claim an interface.

Parameters

  | usb_device | The usb device to open.
  | interface | the interface index to claim.
  [out] | usb_handle | the new device handle.

Returns
  true if the device was opened and the interface claimed, false otherwise.

## ◆ RefDevice()

virtual libusb_device * ola::usb::LibUsbAdaptor::RefDevice | ( | libusb_device * | dev | ) |
| pure virtual

Wraps libusb_ref_device.

Parameters

  dev | the device to reference

Returns
  the same device

## ◆ SetConfiguration()

virtual int ola::usb::LibUsbAdaptor::SetConfiguration | ( | libusb_device_handle * | dev,
|  | int | configuration )
| pure virtual

Wraps libusb_set_configuration.

Parameters

  dev | a device handle
  configuration | the bConfigurationValue of the configuration you wish to activate, or -1 if you wish to put the device in an unconfigured state.

Returns
  0 on success
  LIBUSB_ERROR_NOT_FOUND if the requested configuration does not exist.
  LIBUSB_ERROR_BUSY if interfaces are currently claimed
  LIBUSB_ERROR_NO_DEVICE if the device has been disconnected
  another LIBUSB_ERROR code on other failure

## ◆ SubmitTransfer()

virtual int ola::usb::LibUsbAdaptor::SubmitTransfer | ( | struct libusb_transfer * | transfer | ) |
| pure virtual

Wraps libusb_submit_transfer.

Parameters

  transfer | the transfer to submit

Returns
  0 on success
  LIBUSB_ERROR_NO_DEVICE if the device has been disconnected
  LIBUSB_ERROR_BUSY if the transfer has already been submitted.
  LIBUSB_ERROR_NOT_SUPPORTED if the transfer flags are not supported by the operating system.
  another LIBUSB_ERROR code on other failure

## ◆ UnrefDevice()

virtual void ola::usb::LibUsbAdaptor::UnrefDevice | ( | libusb_device * | dev | ) |
| pure virtual

Wraps libusb_unref_device.

Parameters

  dev | the device to unreference.

The documentation for this class was generated from the following files:

- libs/usb/LibUsbAdaptor.h
- libs/usb/LibUsbAdaptor.cpp