Detailed Description

Wraps calls to libusb so we can test the code.

Inheritance diagram for ola::usb::LibUsbAdaptor:

Classes
struct	DeviceInformation

Public Member Functions
virtual libusb_device *	RefDevice (libusb_device *dev)=0
	Wraps libusb_ref_device. More...

virtual void	UnrefDevice (libusb_device *dev)=0
	Wraps libusb_unref_device. More...

virtual bool	OpenDevice (libusb_device usb_device, libusb_device_handle *usb_handle)=0
	Open a libusb device. More...

virtual bool	OpenDeviceAndClaimInterface (libusb_device usb_device, int interface, libusb_device_handle *usb_handle)=0
	Open a libusb device and claim an interface. More...

virtual void	Close (libusb_device_handle *usb_handle)=0
	Close a libusb handle. More...

virtual int	SetConfiguration (libusb_device_handle *dev, int configuration)=0
	Wraps libusb_set_configuration. More...

virtual int	ClaimInterface (libusb_device_handle *dev, int interface_number)=0
	Wraps libusb_claim_interface. More...

virtual int	DetachKernelDriver (libusb_device_handle *dev, int interface_number)=0
	Detach a kernel driver. More...

virtual int	GetDeviceDescriptor (libusb_device dev, struct libusb_device_descriptor descriptor)=0
	Wraps libusb_get_device_descriptor. More...

virtual int	GetActiveConfigDescriptor (libusb_device dev, struct libusb_config_descriptor *config)=0
	Wraps libusb_get_active_config_descriptor. More...

virtual int	GetConfigDescriptor (libusb_device dev, uint8_t config_index, struct libusb_config_descriptor *config)=0
	Wraps libusb_get_config_descriptor. More...

virtual void	FreeConfigDescriptor (struct libusb_config_descriptor *config)=0
	Wraps busb_free_config_descriptor. More...

virtual bool	GetStringDescriptor (libusb_device_handle usb_handle, uint8_t descriptor_index, std::string data)=0
	Get the value of a string descriptor. More...

virtual struct libusb_transfer *	AllocTransfer (int iso_packets)=0
	Wraps libusb_alloc_transfer. More...

virtual void	FreeTransfer (struct libusb_transfer *transfer)=0
	Wraps libusb_free_transfer. More...

virtual int	SubmitTransfer (struct libusb_transfer *transfer)=0
	Wraps libusb_submit_transfer. More...

virtual int	CancelTransfer (struct libusb_transfer *transfer)=0
	Wraps libusb_cancel_transfer. More...

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. More...

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. More...

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. More...

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. More...

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(). More...

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. More...

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. More...

virtual USBDeviceID	GetDeviceId (libusb_device *device) const =0
	Get the USBDeviceID for a device. More...

Static Public Member Functions
static bool	Initialize (struct libusb_context **context)
	Initialize a new libusb context. More...

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. More...

static bool	CheckManufacturer (const std::string &expected, const DeviceInformation &device_info)
	Check if the manufacturer string matches the expected value. More...

static bool	CheckProduct (const std::string &expected, const DeviceInformation &device_info)
	Check if the product string matches the expected value. More...

static bool	HotplugSupported ()
	Check if this platform supports hotplug. More...

static std::string	ErrorCodeToString (const int error_code)
	Try and convert an error code to a string. More...

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

Implemented in ola::usb::BaseLibUsbAdaptor.

◆ 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

Implemented in ola::usb::AsynchronousLibUsbAdaptor, and ola::usb::BaseLibUsbAdaptor.

◆ 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

Implemented in ola::usb::BaseLibUsbAdaptor.

◆ 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

Implemented in ola::usb::BaseLibUsbAdaptor.

◆ 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.

Implemented in ola::usb::AsynchronousLibUsbAdaptor, and ola::usb::SynchronousLibUsbAdaptor.

◆ 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

Implemented in ola::usb::AsynchronousLibUsbAdaptor, and ola::usb::BaseLibUsbAdaptor.

◆ 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

Implemented in ola::usb::BaseLibUsbAdaptor.

◆ 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

Implemented in ola::usb::BaseLibUsbAdaptor.

◆ 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.

Implemented in ola::usb::BaseLibUsbAdaptor.

◆ 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

Implemented in ola::usb::BaseLibUsbAdaptor.

◆ 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

Implemented in ola::usb::BaseLibUsbAdaptor.

◆ 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

Implemented in ola::usb::BaseLibUsbAdaptor.

◆ FreeTransfer()

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

pure virtual

Wraps libusb_free_transfer.

Parameters

transfer the transfer to free

Implemented in ola::usb::BaseLibUsbAdaptor.

◆ 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

Implemented in ola::usb::BaseLibUsbAdaptor.

◆ 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

Implemented in ola::usb::BaseLibUsbAdaptor.

◆ 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

Implemented in ola::usb::BaseLibUsbAdaptor.

◆ 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.

Implemented in ola::usb::BaseLibUsbAdaptor.

◆ 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.

Implemented in ola::usb::BaseLibUsbAdaptor.

◆ 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

Implemented in ola::usb::AsynchronousLibUsbAdaptor, and ola::usb::BaseLibUsbAdaptor.

◆ 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.

Implemented in ola::usb::AsynchronousLibUsbAdaptor, and ola::usb::SynchronousLibUsbAdaptor.

◆ 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.

Implemented in ola::usb::AsynchronousLibUsbAdaptor, and ola::usb::SynchronousLibUsbAdaptor.

◆ 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

Implemented in ola::usb::BaseLibUsbAdaptor.

◆ 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

Implemented in ola::usb::BaseLibUsbAdaptor.

◆ 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

Implemented in ola::usb::BaseLibUsbAdaptor.

◆ UnrefDevice()

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

pure virtual

Wraps libusb_unref_device.

Parameters

dev	the device to unreference.

Implemented in ola::usb::BaseLibUsbAdaptor.

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

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

Detailed Description

Classes

Public Member Functions

Static Public Member Functions

Member Function Documentation

◆ AllocTransfer()

◆ BulkTransfer()

◆ CancelTransfer()

◆ CheckManufacturer()

◆ CheckProduct()

◆ ClaimInterface()

◆ Close()

◆ ControlTransfer()

◆ DetachKernelDriver()

◆ ErrorCodeToString()

◆ FillBulkTransfer()

◆ FillControlSetup()

◆ FillControlTransfer()

◆ FillInterruptTransfer()

◆ FreeConfigDescriptor()

◆ FreeTransfer()

◆ GetActiveConfigDescriptor()

◆ GetConfigDescriptor()

◆ GetDeviceDescriptor()

◆ GetDeviceId()

◆ GetDeviceInfo()

◆ GetStringDescriptor()

◆ HotplugSupported()

◆ Initialize()

◆ InterruptTransfer()

◆ OpenDevice()

◆ OpenDeviceAndClaimInterface()

◆ RefDevice()

◆ SetConfiguration()

◆ SubmitTransfer()

◆ UnrefDevice()