Home

Libraries

Author

Links

---

stm::UsbDevice Class Reference
[UsbDevice: Base Class for USB Devices]

Inheritance diagram for stm::UsbDevice:

[legend]

Collaboration diagram for stm::UsbDevice:

[legend]

List of all members.

---

Detailed Description

Class defining the C++ API for a libusb controlled USB device inheriting the generic stm::Device C++ API.

This class can be instantiated or be used as base class of a special libusb controlled USB device class which may reimplement the interface of stm::UsbDevice as well as that of the abstract base class stm::Device.

Definition at line 199 of file usbdevice.hpp.

Public Types
enum	DescribeFlags {   DeviceReleaseNumber = DriverVersion << 1,   DeviceBusNumber = DeviceReleaseNumber << 1,   DeviceManufacturer = DeviceBusNumber << 1,   DeviceProduct = DeviceManufacturer << 1,   DeviceSerialNumber = DeviceProduct << 1,   DeviceConfigurations = DeviceSerialNumber << 1,   DeviceInterfaces = DeviceConfigurations << 1,   DeviceAltSettings = DeviceInterfaces << 1,   DeviceEndpoints = DeviceAltSettings << 1,   DeviceChildren = DeviceEndpoints << 1 }
	Describe flags (bitwise orable). More...
Public Member Functions
	UsbDevice (int defaultTimeout=Forever, const Descriptor &descr=Descriptor())
	Constructor of a UsbDevice object representing a libusb controlled USB device described by descr.
virtual	~UsbDevice ()
	Destructor.
virtual bool	canRead () const
	Return the read capability of this UsbDevice.
virtual bool	canWrite () const
	Return the write capability of this UsbDevice.
virtual bool	canControl () const
	Return the control capability of this UsbDevice.
virtual void	setError (int error, const std::string &msg=std::string()) const
	Set the error state and error string of this UsbDevice according to error and msg.
virtual void	setDescr (const Descriptor &descr)
	Set the Device::Descriptor of this UsbDevice to descr.
UsbPipe	pipe () const
	Return a copy of the UsbPipe object configured for this UsbDevice.
UsbPipe::Type	pipeType () const
	Return the type of the UsbPipe object configured for this UsbDevice as an enumerator of the enumeration UsbPipe::Type.
UsbPipe::Type	setPipe (UsbPipe pipe)
	Set the UsbPipe object configured for this UsbDevice to a copy of pipe and return its type.
virtual bool	isOpen () const
	Determine, if this UsbDevice is open.
virtual bool	open (unsigned int openMode)
	Open this UsbDevice in openMode.
virtual bool	close ()
	Close this UsbDevice.
virtual int64_t	read (void *data, int64_t maxLen, int timeout=DefaultTimeout, unsigned int flags=NoFlags)
	Read maxLen bytes from the currently confiured USB pipe of this UsbDevice into the data buffer.
virtual int64_t	readPipe (UsbPipe pipe, void *data, int64_t maxLen, int timeout=DefaultTimeout, unsigned int flags=NoFlags)
	Atomically set the UsbPipe object configured for this UsbDevice to a copy of pipe and read maxLen bytes from that pipe into the data buffer.
virtual int64_t	write (const void *data, int64_t len, int timeout=DefaultTimeout, unsigned int flags=NoFlags)
	Write len bytes from the data buffer to the currently configured USB pipe of this UsbDevice.
virtual int64_t	writePipe (UsbPipe pipe, const void *data, int64_t len, int timeout=DefaultTimeout, unsigned int flags=NoFlags)
	Atomically set the UsbPipe object configured for this UsbDevice to a copy of pipe and write len bytes from the data buffer to that pipe.
virtual int64_t	control (unsigned int request, const void *ctrl, int64_t ctrlLen, void *data, int64_t dataLen, int timeout=DefaultTimeout, unsigned int flags=NoFlags) const
	Perform the control operation request over the default control pipe of this UsbDevice.
virtual std::ostream &	describe (std::ostream &os, unsigned int flags=DefaultProperties) const
	Insert a description of this UsbDevice into os.
bool	isA (const InterfaceClass &interfaceClass) const
	The method returns true, if this UsbDevice is a device supporting the libusb controlled USB device interface class described by interfaceClass.
template<class ForwardIterator>
bool	isA (ForwardIterator beginInterfaceClass, ForwardIterator endInterfaceClass) const
	The method template returns true, if this UsbDevice is a device supporting one of the the libusb controlled USB device interface classes whose description is contained in the half open interval [*beginInterfaceClass, *endInterfaceClass).
Static Public Member Functions
static size_t	enumerate (std::vector< Descriptor > &descriptors, const InterfaceClass &interfaceClass, bool append=false, bool quick=false)
	Enumerate all Device::Descriptor objects describing libusb controlled USB devices supporting the libusb controlled USB device interface class described by interfaceClass.
template<class ForwardIterator>
static size_t	enumerate (std::vector< Descriptor > &descriptors, ForwardIterator beginInterfaceClass, ForwardIterator endInterfaceClass, bool append=false)
	Enumerate all Device::Descriptor objects describing libusb controlled USB devices supporting one of the the libusb controlled USB device interface classes whose description is contained in the half open interval [*beginInterfaceClass, *endInterfaceClass).
static size_t	enumerateAll (std::vector< Descriptor > &descriptors)
	Enumerate all Device::Descriptor objects describing libusb controlled USB devices.
Classes
struct	InterfaceClass
	Type describing a libusb controlled USB device interface class. More...

---

Member Enumeration Documentation

enum stm::UsbDevice::DescribeFlags

Describe flags (bitwise orable).

The enumerators of UsbDevice::DescribeFlags augment the Device::DescribeFlags further specifying the extent produced by describe().

Enumerator:

DeviceReleaseNumber	If set, the device release number property is included, else not.
DeviceBusNumber	If set, the device bus number property is included, else not.
DeviceManufacturer	If set, the device manufacturer property is included, else not.
DeviceProduct	If set, the device product property is included, else not.
DeviceSerialNumber	If set, the device serial number property is included, else not.
DeviceConfigurations	If set, the device configurations property is included, else not.
DeviceInterfaces	If set and property names are configured, the device interfaces property is included, else not.
DeviceAltSettings	If set and property names are configured, the device alternate settings property is included, else not.
DeviceEndpoints	If set and property names are configured, the device endpoints property is included, else not.
DeviceChildren	If set, the device children property is included, else not.

Reimplemented from stm::Device.

Definition at line 208 of file usbdevice.hpp.

---

Constructor & Destructor Documentation

stm::UsbDevice::UsbDevice	(	int	defaultTimeout = Forever,
		const Descriptor &	descr = Descriptor()
	)

Constructor of a UsbDevice object representing a libusb controlled USB device described by descr.

Parameters:

[in]	defaultTimeout	Timeout in milliseconds used by default for all operations of this UsbDevice.
[in]	descr	A valid Device::Descriptor for the libusb controlled USB device to be represented by the UsbDevice object to be constructed or an invalid Device::Descriptor. A valid Device::Descriptor is typically yielded by one of the static methods enumerate() or enumerateAll().

Effects:

Constructs a UsbDevice object with the Device::Descriptor descr defined for it. If descr is valid, the constructed UsbDevice is ready to be opened.

See also:

descr(), open(), enumerate(), enumerateAll().

virtual stm::UsbDevice::~UsbDevice

(

)

[virtual]

Destructor.

Effects:

If this UsbDevice is open, it is closed first.

See also:

isOpen(), close().

---

Member Function Documentation

virtual bool stm::UsbDevice::canRead

(

)

const [virtual]

Return the read capability of this UsbDevice.

Returns:

true.

Note:

If this virtual method is not reimplemented by a derived class, this means that the device can be successfully opended in open mode Device::ReadAccess.

It is not necessary that this UsbDevice is open.

See also:

canWrite(), canControl(), canSeek(), open().

Reimplemented from stm::Device.

virtual bool stm::UsbDevice::canWrite

(

)

const [virtual]

Return the write capability of this UsbDevice.

Returns:

true.

Note:

If this virtual method is not reimplemented by a derived class, this means that the device can be successfully opended in open mode Device::WriteAccess.

It is not necessary that this UsbDevice is open.

See also:

canRead(), canControl(), canSeek(), open().

Reimplemented from stm::Device.

virtual bool stm::UsbDevice::canControl

(

)

const [virtual]

Return the control capability of this UsbDevice.

Returns:

true.

Note:

If this virtual method is not reimplemented by a derived class, this means that the device does support the method control().

It is not necessary that this UsbDevice is open.

See also:

canRead(), canWrite(), canSeek(), control().

Reimplemented from stm::Device.

virtual void stm::UsbDevice::setError	(	int	error,
		const std::string &	msg = std::string()
	)			const [virtual]

Set the error state and error string of this UsbDevice according to error and msg.

Parameters:

[in]	error	Error state as one of the enumerators of Device::ErrorState optionally ored with one ore more of the enumerators of Device::ErrorFlags.
[in]	msg	Error string.

Effects:

If the error state part of error is one of the enumerators of Device::ErrorState, the error state of this UsbDevice is set to that state and its error string to msg, else to Device::UnknownError. If the error flag Device::SystemError is set in error, the error string is augmented by a system error description, if available.

Note:

Despite of being const, the method can change the error state and error string.

It is not necessary that this UsbDevice is open.

See also:

error(), clearError(), errorString(), augmentErrorString().

Reimplemented from stm::Device.

virtual void stm::UsbDevice::setDescr

(

const Descriptor &

descr

)

[virtual]

Set the Device::Descriptor of this UsbDevice to descr.

Parameters:

[in]

descr

A valid Device::Descriptor of the libusb controlled USB device to be represented by this UsbDevice or an invalid Device::Descriptor. A valid descriptor is typically yielded by one of the static methods enumerate() or enumerateAll().

Effects:

If this UsbDevice is open, it is closed. Then descr is defined for it. If descr is valid, this UsbDevice is ready to be opened, else it does not represent a libusb controlled USB device.

See also:

descr(), isOpen(), close(), open(), enumerate(), enumerateAll().

Implements stm::Device.

UsbPipe stm::UsbDevice::pipe

(

)

const

Return a copy of the UsbPipe object configured for this UsbDevice.

Returns:

an invalid UsbPipe object, if this UsbDevice does not represent a libusb controlled USB device.

a copy of the UsbPipe object configured for the libusb controlled USB device represented by this UsbDevice.

Note:

It is not necessary that this UsbDevice is open.

See also:

pipeType(), setPipe(), isOpen().

UsbPipe::Type stm::UsbDevice::pipeType

(

)

const

Return the type of the UsbPipe object configured for this UsbDevice as an enumerator of the enumeration UsbPipe::Type.

Returns:

UsbPipe::Invalid, if this UsbDevice does not represent a libusb controlled USB device, or if its configured pipe is invalid.

UsbPipe::Bulk or UsbPipe::Interrupt, if this UsbDevice represents a libusb controlled USB device with a pipe configured for bulk or interrupt data transfer.

Note:

It is not necessary that this UsbDevice is open.

See also:

pipe(), setPipe(), isOpen().

UsbPipe::Type stm::UsbDevice::setPipe

(

UsbPipe

pipe

)

Set the UsbPipe object configured for this UsbDevice to a copy of pipe and return its type.

Parameters:

[in]

pipe

A UsbPipe object a copy of which is to be configured for the libusb controlled USB device represented by this UsbDevice.

Returns:

The type UsbPipe::Bulk or UsbPipe::Interrupt, if a copy of pipe can be configured for this UsbDevice, else UsbPipe::Invalid, in which case the UsbPipe object configured for this UsbDevice stays unchanged.

Note:

It is not necessary that this UsbDevice is open.

See also:

pipe(), pipeType(), isOpen().

virtual bool stm::UsbDevice::isOpen

(

)

const [virtual]

Determine, if this UsbDevice is open.

Returns:

true, if this UsbDevice is open, that is if its open mode is not the Device::OpenMode enumerator Device::NoAccess.

false, if this UsbDevice is not open, that is if its open mode is the Device::OpenMode enumerator Device::NoAccess.

See also:

open(), close().

Reimplemented from stm::Device.

virtual bool stm::UsbDevice::open

(

unsigned int

openMode

)

[virtual]

Open this UsbDevice in openMode.

Parameters:

[in]

openMode

Open mode to be set.

Effects:

The method sets the error state of this UsbDevice to the Device::ErrorState enumerator Device::OpenError, if openMode is the Device::OpenMode enumerator Device::NoAccess, if isOpen() does not return false or if the libusb controlled USB device represented by this UsbDevice cannot be opened conforming to openMode. Else the method sets the open mode of this UsbDevice to openMode.

Returns:

true, if this UsbDevice could be opened in openMode.

false, if this UsbDevice could not be opened in openMode. Then the error state of this UsbDevice is set to Device::OpenError.

See also:

isOpen(), close(), error ().

Reimplemented from stm::Device.

virtual bool stm::UsbDevice::close

(

)

[virtual]

Close this UsbDevice.

Effects:

The method sets the error state of this UsbDevice to the Device::ErrorState enumerator Device::CloseError, if isOpen() returns false or if the libusb controlled USB device represented by this UsbDevice cannot be closed successfully. Else the method sets the open mode of this UsbDevice to the Device::OpenMode enumerator Device::NoAccess.

Returns:

true, if this UsbDevice could be closed successfully.

false, if this UsbDevice could not be closed successfully. Then the error state of this UsbDevice is set to Device::CloseError.

See also:

isOpen(), open(), error ().

Reimplemented from stm::Device.

virtual int64_t stm::UsbDevice::read	(	void *	data,
		int64_t	maxLen,
		int	timeout = DefaultTimeout,
		unsigned int	flags = NoFlags
	)			[virtual]

Read maxLen bytes from the currently confiured USB pipe of this UsbDevice into the data buffer.

Parameters:

[out]	data	Buffer for the data to be read.
[in]	maxLen	Maximal number of bytes to be read.
[in]	timeout	Operation timeout in milliseconds. If the value is Device::Forever, no timeout occurs. The default value Device::DefaultTimeout means, that the default timeout of this UsbDevice is used.
[in]	flags	If the flag bit Device::AcceptTimeout is set, a timeout is no error.

Effects:

The method sets the error state of this UsbDevice to the Device::ErrorState enumerator Device::ReadError, if the result of openMode() does not contain the Device::OpenMode enumerator Device::ReadAccess, or if maxLen is negative or data is the NULL pointer unless maxLen is also, 0 or if the read operation described below fails. During the read operation maximal maxLen bytes from the libusb controlled USB device represented by this UsbDevice are read through the USB pipe currently configured and are stored in the buffer pointed to by data.

Returns:

The number of bytes actually read, if the read operation was successful.

-1, if the read operation was not successful. Then the error state of this UsbDevice is set to Device::ReadError.

Note:

Be aware that in multithreaded applications configuring the USB pipe to be used and the reading from the pipe must occur atomically. To ensure this, better use readPipe() in those situations.

See also:

write(), control(), openMode(), error (), defaultTimeout(), pipe(), setPipe(), readPipe().

Reimplemented from stm::Device.

virtual int64_t stm::UsbDevice::readPipe	(	UsbPipe	pipe,
		void *	data,
		int64_t	maxLen,
		int	timeout = DefaultTimeout,
		unsigned int	flags = NoFlags
	)			[virtual]

Atomically set the UsbPipe object configured for this UsbDevice to a copy of pipe and read maxLen bytes from that pipe into the data buffer.

Parameters:

[in]	pipe	A UsbPipe object a copy of which is to be configured for the libusb controlled USB device represented by this UsbDevice.
[out]	data	Buffer for the data to be read.
[in]	maxLen	Maximal number of bytes to be read.
[in]	timeout	Operation timeout in milliseconds. If the value is Device::Forever, no timeout occurs. The default value Device::DefaultTimeout means, that the default timeout of this UsbDevice is used.
[in]	flags	If the flag bit Device::AcceptTimeout is set, a timeout is no error.

Effects:

The method sets the error state of this UsbDevice to the Device::ErrorState enumerator Device::ReadError, if it cannot set the pipe successfully, if the result of openMode() does not contain the Device::OpenMode enumerator Device::ReadAccess, or if maxLen is negative or data is the NULL pointer unless maxLen is also, 0 or if the read operation described below fails. During the read operation maximal maxLen bytes from the libusb controlled USB device represented by this UsbDevice are read through pipe and are stored in the buffer pointed to by data.

Returns:

The number of bytes actually read, if the read operation was successful.

-1, if the read operation was not successful. Then the error state of this UsbDevice is set to Device::ReadError.

Note:

The timeout only applies to the read operation not to the setting of the pipe.

See also:

write(), control(), openMode(), error (), defaultTimeout(), pipe(), setPipe(), read().

virtual int64_t stm::UsbDevice::write	(	const void *	data,
		int64_t	len,
		int	timeout = DefaultTimeout,
		unsigned int	flags = NoFlags
	)			[virtual]

Write len bytes from the data buffer to the currently configured USB pipe of this UsbDevice.

Parameters:

[in]	data	Buffer containing the data to be written.
[in]	len	Number of bytes to be written.
[in]	timeout	Operation timeout in milliseconds. If the value is Device::Forever, no timeout occurs. The default value Device::DefaultTimeout means, that the default timeout of this UsbDevice is used.
[in]	flags	If the flag bit Device::AcceptTimeout is set, a timeout is no error.

Effects:

The method sets the error state of this UsbDevice to the Device::ErrorState enumerator Device::WriteError, if the result of openMode() does not contain the Device::OpenMode enumerator Device::WriteAccess, or if len is negative or data is the NULL pointer unless len is also 0, or if the write operation described below fails. During the write operation len bytes from the buffer pointed to by data are written through the USB pipe currently configured to the libusb controlled USB device represented by this UsbDevice.

Returns:

len, if the write operation was successful.

-1, if the write operation was not successful. Then the error state of this UsbDevice is set to Device::WriteError.

Note:

Be aware that in multithreaded applications configuring the USB pipe to be used and the writing to the pipe must occur atomically. To ensure this, better use writePipe() in those situations.

See also:

read(), control(), openMode(), error (), defaultTimeout(), pipe(), setPipe(), writePipe().

Reimplemented from stm::Device.

virtual int64_t stm::UsbDevice::writePipe	(	UsbPipe	pipe,
		const void *	data,
		int64_t	len,
		int	timeout = DefaultTimeout,
		unsigned int	flags = NoFlags
	)			[virtual]

Atomically set the UsbPipe object configured for this UsbDevice to a copy of pipe and write len bytes from the data buffer to that pipe.

Parameters:

[in]	pipe	A UsbPipe object a copy of which is to be configured for the libusb controlled USB device represented by this UsbDevice.
[in]	data	Buffer containing the data to be written.
[in]	len	Number of bytes to be written.
[in]	timeout	Operation timeout in milliseconds. If the value is Device::Forever, no timeout occurs. The default value Device::DefaultTimeout means, that the default timeout of this UsbDevice is used.
[in]	flags	If the flag bit Device::AcceptTimeout is set, a timeout is no error.

Effects:

The method sets the error state of this UsbDevice to the Device::ErrorState enumerator Device::WriteError, if it cannot set the pipe successfully, if the result of openMode() does not contain the Device::OpenMode enumerator Device::WriteAccess, or if len is negative or data is the NULL pointer unless len is also 0, or if the write operation described below fails. During the write operation len bytes from the buffer pointed to by data are written through pipe to the libusb controlled USB device represented by this UsbDevice.

Returns:

len, if the write operation was successful.

-1, if the write operation was not successful. Then the error state of this UsbDevice is set to Device::WriteError.

Note:

The timeout only applies to the write operation not to the setting of the pipe.

See also:

read(), control(), openMode(), error (), defaultTimeout(), pipe(), setPipe(), write().

virtual int64_t stm::UsbDevice::control	(	unsigned int	request,
		const void *	ctrl,
		int64_t	ctrlLen,
		void *	data,
		int64_t	dataLen,
		int	timeout = DefaultTimeout,
		unsigned int	flags = NoFlags
	)			const [virtual]

Perform the control operation request over the default control pipe of this UsbDevice.

Parameters:

[in]	request	Specifies the particular control operation to be performed.
[in]	ctrl	Pointer to a UsbCtrl object specifying the request type (in which the transfer direction is encoded), the value and the index of the request.
[in]	ctrlLen	sizeof(UsbCtrl).
[in,out]	data	Buffer for the input or output data.
[in]	dataLen	Byte length of the data buffer.
[in]	timeout	Operation timeout in milliseconds. If the value is Device::Forever, no timeout occurs. The default value Device::DefaultTimeout means, that the default timeout of this UsbDevice is used.
[in]	flags	If the flag bit Device::AcceptTimeout is set, a timeout is no error.

Effects:

The method performs the control operation characterized by request for the libusb controlled USB device represented by this UsbDevice using its default control pipe. The parameter ctrl shall be the address of a UsbCtrl object specifying the request type encoding the transfer direction, the value and the index of the request. The parameter ctrlLen shall be sizeof(UsbCtrl). If any data transfer is required, data shall not be NULL and point to a buffer of size dataLen.

Returns:

The number of bytes transferred to or from data, if the operation was successful. This is 0 in the case of an accepted timeout.

-1, if the operation was not successful. Then the error state of this UsbDevice is set to the Device::ErrorState enumerator Device::ControlError.

See also:

write(), read(), openMode(), error (), defaultTimeout().

Reimplemented from stm::Device.

virtual std::ostream& stm::UsbDevice::describe	(	std::ostream &	os,
		unsigned int	flags = DefaultProperties
	)			const [virtual]

Insert a description of this UsbDevice into os.

Parameters:

[in]	os	The output stream to insert the description.
[in]	flags	Description flags.

Effects:

The method inserts a verbal description of this UsbDevice into the output stream os. Format and extent of the description is controlled by the flags parameter according to the bitwise ored enumerators of Device::DescribeFlags and UsbDevice::DescribeFlags.

Returns:

The output stream os.

Note:

This UsbDevice need not be open.

Reimplemented from stm::Device.

bool stm::UsbDevice::isA

(

const InterfaceClass &

interfaceClass

)

const

The method returns true, if this UsbDevice is a device supporting the libusb controlled USB device interface class described by interfaceClass.

That means it returns true, if the Device::Descriptor of this UsbDevice describes a libusb controlled USB device supporting the libusb controlled USB device interface class described by interfaceClass, else false.

template<class ForwardIterator>

bool stm::UsbDevice::isA	(	ForwardIterator	beginInterfaceClass,
		ForwardIterator	endInterfaceClass
	)			const

The method template returns true, if this UsbDevice is a device supporting one of the the libusb controlled USB device interface classes whose description is contained in the half open interval [*beginInterfaceClass, *endInterfaceClass).

That means it returns true, if the Device::Descriptor of this UsbDevice describes a libusb controlled USB device supporting one of the libusb controlled USB device interface classes described by that interval, else false.

static size_t stm::UsbDevice::enumerate	(	std::vector< Descriptor > &	descriptors,
		const InterfaceClass &	interfaceClass,
		bool	append = false,
		bool	quick = false
	)			[static]

Enumerate all Device::Descriptor objects describing libusb controlled USB devices supporting the libusb controlled USB device interface class described by interfaceClass.

The static method clears the vector descriptors, scans the system for all libusb controlled USB devices supporting the libusb controlled USB device interface class described by interfaceClass, stores the Device::Descriptor objects describing those devices in the vector descriptors and returns the size of that vector. If quick is true, the system is not scanned for new hardware.

template<class ForwardIterator>

static size_t stm::UsbDevice::enumerate	(	std::vector< Descriptor > &	descriptors,
		ForwardIterator	beginInterfaceClass,
		ForwardIterator	endInterfaceClass,
		bool	append = false
	)			[static]

Enumerate all Device::Descriptor objects describing libusb controlled USB devices supporting one of the the libusb controlled USB device interface classes whose description is contained in the half open interval [*beginInterfaceClass, *endInterfaceClass).

The static method template clears the vector descriptors, scans the system for all libusb controlled USB devices supporting one of the libusb controlled USB device interface classes described by that interval, stores the Device::Descriptor objects describing those devices in the vector descriptors and returns the size of that vector.

static size_t stm::UsbDevice::enumerateAll

(

std::vector< Descriptor > &

descriptors

)

[static]

Enumerate all Device::Descriptor objects describing libusb controlled USB devices.

The static method template clears the vector descriptors, scans the system for all libusb controlled USB devices, stores the Device::Descriptor objects describing those devices in the vector descriptors and returns the size of that vector.

---

© Copyright Tom Michaelis 2002-2007

Distributed under the SysToMath Software License (See the accompanying file license.txt or a copy at www.SysToMath.com).