stm::Device

stm::Device Class Reference
[Device: Abstract Base Class for Generic Devices]

Inheritance diagram for stm::Device:

Detailed Description

Abstract base class defining the C++ API for a generic device.

This class is intended to serve as base class of a special device class which shall implement the interface of stm::Device.

Definition at line 398 of file device.hpp.


Public Types
enum	OpenMode { NoAccess = 0x00000000, ReadAccess = 0x00000001, WriteAccess = 0x00000002, ReadWriteAccess = ReadAccess \| WriteAccess }
	Open mode flags (bitwise orable). More...
enum	ErrorState { NoError = 0, ReadError = 1, WriteError = 2, ControlError = 3, ResourceError = 4, OpenError = 5, CloseError = 6, SeekError = 7, ArgumentError = 8, UnknownError = 9 }
	Error state values. More...
enum	ErrorFlags { ErrorFlagMask = 0x7fff0000, SystemError = 0x00010000 }
	Error flags. More...
enum	{ NoFlags = 0x00000000, AcceptTimeout = 0x00000001 }
	Bitwise orable operation flag bits for read(), write() and control(). More...
enum	DescribeFlags { IndentMask = 0x0000000f, IndentFirst = IndentMask + 1, NoPropertyNames = IndentFirst << 1, DefaultProperties = NoPropertyNames << 1, VerboseProperties = DefaultProperties << 1 \| DefaultProperties, AllProperties = ~ ((DefaultProperties << 2) - 1), DeviceType = DefaultProperties << 2, DeviceUuid = DeviceType << 1, DriverVersion = DeviceUuid << 1 }
	Describe flags (bitwise orable). More...
enum	Timeout { DefaultTimeout = -1, Forever = INT_MAX }
	Special timeout values. More...
Public Member Functions
	Device (const Uuid &uuid=Uuid(), const std::string type=std::string(), int defaultTimeout=Forever, const Descriptor &descr=Descriptor())
	Constructor optionally setting the Uuid of the Device to uuid, the type string of the Device to type, the default operation timeout of the Device to defaultTimeout milliseconds and the Descriptor of the Device to descr.
	Device (int defaultTimeout, const Descriptor &descr=Descriptor())
	Constructor setting the default operation timeout of the Device to defaultTimeout milliseconds and the Descriptor to descr.
	Device (const Uuid &uuid, const std::string type, const Version &version, int defaultTimeout=Forever, const Descriptor &descr=Descriptor())
	Constructor setting the Uuid of the Device to uuid, the type string and version of the Device to type and version, respectively, and the default operation timeout of the Device to defaultTimeout milliseconds which defaults to infinite.
	Device (const Device &other)
	Copy constructor.
Device &	operator= (const Device &other)
	Copy assignment operator.
virtual	~Device ()
	Destructor.
virtual const Uuid &	uuid () const
	The virtual method shall return the Uuid of this Device.
virtual void	setUuid (const Uuid &uuid)
	The virtual method shall set the Uuid of this Device to uuid.
const std::string &	property (const std::string &name) const
	The method returns the string value of property name of this Device.
void	setProperty (const std::string &name, const std::string &value)
	The method sets the property name of this Device to value.
bool	unsetProperty (const std::string &name)
	The method unsets the property name of this Device to value and returns true, if it were set, else false.
bool	hasProperty (const std::string &name)
	The method returns true, if the property name is set for this Device, else false.
virtual const std::string &	type () const
	The virtual method shall return the type string of this Device.
virtual void	setType (const std::string &type)
	The virtual method shall set the type string of this Device to type.
virtual Version	version () const
	The virtual method shall return the Version of this Device.
virtual void	setVersion (const Version &version)
	The virtual method shall set the Version of this Device to version.
virtual int	defaultTimeout () const
	The virtual method shall return the default timeout of this Device.
virtual void	setDefaultTimeout (int defaultTimeout=Forever)
	The virtual method shall set the default operation timeout in milliseconds of this Device to defaultTimeout.
virtual const Descriptor &	descr () const
	Return the Device::Descriptor of this Device.
virtual void	setDescr (const Descriptor &descr)=0
	Set the Device::Descriptor of this Device to descr.
virtual bool	canRead () const
	Return the read capability of this Device.
virtual bool	canWrite () const
	Return the write capability of this Device.
virtual bool	canControl () const
	Return the control capability of this Device.
virtual bool	canSeek () const
	Return the seek capability of this Device.
virtual int	error () const
	Return the error state of this Device.
virtual void	setError (int error, const std::string &msg=std::string()) const
	Set the error state and error string of this Device according to error and msg.
virtual void	clearError () const
	Clear the error state and error string of this Device.
virtual std::string	errorString (bool msgOnly=false) const
	Return the error string of this Device.
virtual void	augmentErrorString (const std::string &prefix, const std::string &suffix=std::string()) const
	Augment the error string of this device.
virtual bool	isOpen () const
	The virtual method shall return true, if this Device is open, else false.
virtual unsigned int	openMode () const
	The virtual method shall return the open mode of this Device.
virtual bool	open (unsigned int openMode=ReadWriteAccess)
	The virtual method shall open this Device in openMode, if possible and return true on success, else false.
virtual bool	close ()
	The virtual method shall close this Device, if possible and return true on success, else false.
virtual int64_t	read (void *data, int64_t maxLen, int timeout=DefaultTimeout, unsigned int flags=NoFlags)
	The virtual method shall read maximal maxLen bytes from this Device and store them in the buffer pointed to by data.
virtual int64_t	write (const void *data, int64_t len, int timeout=DefaultTimeout, unsigned int flags=NoFlags)
	The virtual method shall write len bytes from the buffer pointed to by data to this Device.
virtual int64_t	control (unsigned int request, const void inData, int64_t inLen, void outData, int64_t maxOutLen, int timeout=DefaultTimeout, unsigned int flags=NoFlags) const
	The virtual method shall perform the control operation specified by request for this Device with input data of length inLen pointed to by inData producing output data of maximal length maxOutLen in the buffer pointed to by outData.
virtual int64_t	size () const
	The virtual method shall return the size of this Device, if it is an opened random access device, else -1.
virtual int64_t	pos () const
	The virtual method shall return the access position of this Device, if it is an opened random access device, else -1.
virtual bool	seek (int64_t pos)
	The virtual method shall set the access position of this Device to pos and return true on success, if it is an opened random access device, else it shall return false.
virtual bool	reset ()
	The virtual method shall set the access position of this Device to 0 and return true on success, if it is an opened random access device, else it shall return false.
virtual std::ostream &	describe (std::ostream &os, unsigned int flags=DefaultProperties) const
	Insert a description of this Device into os.
Classes
struct	Descriptor
	Objects of type Device::Descriptor describe system dependent aspects of a Device as a pair of a void pointer and a void function pointer. More...
struct	Version
	Device driver version. More...

Member Enumeration Documentation

enum stm::Device::OpenMode

Open mode flags (bitwise orable).

The enumerators of Device::OpenMode specify the possible access modes of a Device.

Enumerator:

NoAccess	No acces, Device not open.
ReadAccess	Read access, Device readable.
WriteAccess	Write access, Device writeable.
ReadWriteAccess	Read and write access.

Definition at line 405 of file device.hpp.

enum stm::Device::ErrorState

Error state values.

The enumerators of Device::ErrorState indicate the reason of the last Device error occurred.

Enumerator:

NoError	No error.
ReadError	Error during read().
WriteError	Error during write().
ControlError	Error during control().
ResourceError	Resource error.
OpenError	Error during open().
CloseError	Error during close().
SeekError	Error during seek(), reset(), pos() or size().
ArgumentError	Invalid argument.
UnknownError	Unknown error.

Definition at line 416 of file device.hpp.

enum stm::Device::ErrorFlags

Error flags.

Enumerator:

ErrorFlagMask	All error flags shall be covered by that mask.
SystemError	Indicates that the error string shall be augmented by a system error description, if available.

Definition at line 432 of file device.hpp.

anonymous enum

Bitwise orable operation flag bits for read(), write() and control().

Enumerator:

NoFlags	No flag bits set.
AcceptTimeout	Timeout is no error.

Definition at line 442 of file device.hpp.

enum stm::Device::DescribeFlags

Describe flags (bitwise orable).

The enumerators of Device::DescribeFlags specify output format and extent produced by describe().

Enumerator:

IndentMask	Mask for indentation field. If the value masked is not 0, each property is output on a new line indented by this value. If it is 0, all properties are enumerated on one line separated by commas.
IndentFirst	If set, also the first property is indented, else not and also its name is omitted. This flag has no effect, if no indentation is performed.
NoPropertyNames	If set and no indentation is performed, all property names are omitted.
DefaultProperties	If set, the device specific default properties are included.
VerboseProperties	If set, the device specific verbose properties are included which include the device specific default properties.
AllProperties	If set, all device specific properties are included.
DeviceType	If set, the device type property is included, else not.
DeviceUuid	If set, the device UUID property is included, else not.
DriverVersion	If set, the driver version property is included, else not.

Reimplemented in stm::UsbDevice, and stm::W32Device.

Definition at line 451 of file device.hpp.

enum stm::Device::Timeout

Special timeout values.

Enumerator:

DefaultTimeout	Use default timeout of this Device.
Forever	Wait forever.

Definition at line 489 of file device.hpp.

Constructor & Destructor Documentation

stm::Device::Device	(	const Uuid &	uuid = `Uuid()`,
		const std::string	type = `std::string()`,
		int	defaultTimeout = `Forever`,
		const Descriptor &	descr = `Descriptor()`
	)

Constructor optionally setting the Uuid of the Device to uuid, the type string of the Device to type, the default operation timeout of the Device to defaultTimeout milliseconds and the Descriptor of the Device to descr.

The default Uuid is null as is the default type string, whereas the default defaultTimeout is infinite and the default descr is invalid.

stm::Device::Device	(	int	defaultTimeout,
		const Descriptor &	descr = `Descriptor()`
	)

Constructor setting the default operation timeout of the Device to defaultTimeout milliseconds and the Descriptor to descr.

stm::Device::Device	(	const Uuid &	uuid,
		const std::string	type,
		const Version &	version,
		int	defaultTimeout = `Forever`,
		const Descriptor &	descr = `Descriptor()`
	)

Constructor setting the Uuid of the Device to uuid, the type string and version of the Device to type and version, respectively, and the default operation timeout of the Device to defaultTimeout milliseconds which defaults to infinite.

Moreover, the Descripor is set to descr defaulting to invalid.

stm::Device::Device ( const Device & other )

Copy constructor.

Only copyable, if the Device::Descriptor of other is invalid. Then the constructed Device object is a copy of other with the exception that its Uuid is null.

virtual stm::Device::~Device ( ) [virtual]

Destructor.

If this Device is open, it is closed first.

Member Function Documentation

Device& stm::Device::operator= ( const Device & other )

Copy assignment operator.

Only copyable, if the Device::Descriptor of this Device and of other are invalid. Then this Device is replaced with a copy of other with the exception that its Uuid is null.

virtual const Uuid& stm::Device::uuid ( ) const [virtual]

The virtual method shall return the Uuid of this Device.

The default implementation returns the Uuid of this Device set by the constructor or by setUuid().

virtual void stm::Device::setUuid ( const Uuid & uuid ) [virtual]

The virtual method shall set the Uuid of this Device to uuid.

The default implementation sets the Uuid of this device to uuid.

const std::string& stm::Device::property ( const std::string & name ) const

The method returns the string value of property name of this Device.

If property name was not set, an empty string is returned.

void stm::Device::setProperty	(	const std::string &	name,
		const std::string &	value
	)

The method sets the property name of this Device to value.

bool stm::Device::unsetProperty ( const std::string & name )

The method unsets the property name of this Device to value and returns true, if it were set, else false.

bool stm::Device::hasProperty ( const std::string & name )

The method returns true, if the property name is set for this Device, else false.

virtual const std::string& stm::Device::type ( ) const [virtual]

The virtual method shall return the type string of this Device.

The default implementation returns the type string of this Device set by the constructor or by setType() and is implemented as property.

virtual void stm::Device::setType ( const std::string & type ) [virtual]

The virtual method shall set the type string of this Device to type.

The default implementation sets the type string of this device to type and is implemented as property.

virtual Version stm::Device::version ( ) const [virtual]

The virtual method shall return the Version of this Device.

The default implementation returns the Version of this Device set by the constructor or by setVersion().

virtual void stm::Device::setVersion ( const Version & version ) [virtual]

The virtual method shall set the Version of this Device to version.

The default implementation sets the Version of this device to version.

virtual int stm::Device::defaultTimeout ( ) const [virtual]

The virtual method shall return the default timeout of this Device.

The default implementation returns the default operation timout of this Device in milliseconds set by the constructor or by setDefaultTimeout().

virtual void stm::Device::setDefaultTimeout ( int defaultTimeout = Forever ) [virtual]

The virtual method shall set the default operation timeout in milliseconds of this Device to defaultTimeout.

The default implementation sets the default timeout of this Device to defaultTimeout which defaults to infinite.

virtual const Descriptor& stm::Device::descr ( ) const [virtual]

Return the Device::Descriptor of this Device.

Returns:: An invalid Device::Descriptor, if this Device does not represent a device.
A valid Device::Descriptor of this Device represents a device.

Note:: It is not necessary that this UsbDevice is open.

See also:: setDescr().

virtual void stm::Device::setDescr ( const Descriptor & descr ) [pure virtual]

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

Parameters:

[in] descr A valid Device::Descriptor of the device to be represented by this Device object or an invalid Device::Descriptor.

Effects:: If this Device is open, it is closed. Then descr is defined for it. If descr is valid, this Device is ready to be opened, else it does not represent a device.

See also:: descr(), isOpen(), close(), open().

Implemented in stm::UsbDevice.

virtual bool stm::Device::canRead ( ) const [virtual]

Return the read capability of this Device.

Returns:: false.

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

See also:: canWrite(), canControl(), canSeek(), open().

Reimplemented in stm::UsbDevice, and stm::W32Device.

virtual bool stm::Device::canWrite ( ) const [virtual]

Return the write capability of this Device.

Returns:: false.

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

See also:: canRead(), canControl(), canSeek(), open().

Reimplemented in stm::UsbDevice, and stm::W32Device.

virtual bool stm::Device::canControl ( ) const [virtual]

Return the control capability of this Device.

Returns:: false.

Note:: If this virtual method is not reimplemented by a derived class, this means that the device does not support the method control().
It is not necessary that this Device is open.

See also:: canRead(), canWrite(), canSeek(), control().

Reimplemented in stm::UsbDevice, and stm::W32Device.

virtual bool stm::Device::canSeek ( ) const [virtual]

Return the seek capability of this Device.

Returns:: false.

Note:: If this virtual method is not reimplemented by a derived class, this means that the device does not support the methods size(), pos(), seek () and reset().
It is not necessary that this Device is open.

See also:: canRead(), canWrite(), canControl(), size(), pos(), seek(), reset ().

virtual int stm::Device::error ( ) const [virtual]

Return the error state of this Device.

Returns:: The error state of this Device as one of the enumerators of Device::ErrorState.

Note:: It is not necessary that this Device is open.

See also:: setError(), clearError(), errorString(), augmentErrorString().

Reimplemented in stm::W32Device.

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

Set the error state and error string of this Device 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 Device 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 Device is open.

See also:: error(), clearError(), errorString(), augmentErrorString().

Reimplemented in stm::UsbDevice, and stm::W32Device.

virtual void stm::Device::clearError ( ) const [virtual]

Clear the error state and error string of this Device.

Effects:: The error state and error string of this Device are cleared, that means set to Device::NoError and the empty string.

Note:: Despite of being const, the method can change the error state and error string.
It is not necessary that this Device is open.

See also:: error(), setError(), errorString(), augmentErrorString().

Reimplemented in stm::W32Device.

virtual std::string stm::Device::errorString ( bool msgOnly = false ) const [virtual]

Return the error string of this Device.

Parameters:

[in] msgOnly If true, return only error message, else precede it by a verbal description of the error state.

Returns:: A non empty string describing the error state of this Device, if that error state is not Device::NoError.
The empty string, if the error state of this Device is Device::NoError.

Note:: It is not necessary that this Device is open.

See also:: error(), setError(), clearError(), augmentErrorString().

virtual void stm::Device::augmentErrorString	(	const std::string &	prefix,
		const std::string &	suffix = `std::string()`
	)			const `[virtual]`

Augment the error string of this device.

Parameters:

`[in]`	prefix	Error string prefix.
`[in]`	suffix	Error string suffix.

Effects:: If the error state of this Device is not Device::NoError and at least one of prefix or suffix is not empty, the current error string is augmented accordingly.

Note:: Despite of being const, the method can change the error string.
It is not necessary that this Device is open.

See also:: error(), setError(), clearError(), errorString().

virtual bool stm::Device::isOpen ( ) const [virtual]

The virtual method shall return true, if this Device is open, else false.

The default implementation returns true, if this Device is open, that is if its open mode is not the Device::OpenMode enumerator Device::NoAccess, else false.

Reimplemented in stm::UsbDevice, and stm::W32Device.

virtual unsigned int stm::Device::openMode ( ) const [virtual]

The virtual method shall return the open mode of this Device.

The default implementation returns the open mode of this Device as one of the enumerators of Device::OpenMode.

virtual bool stm::Device::open ( unsigned int openMode = ReadWriteAccess ) [virtual]

The virtual method shall open this Device in openMode, if possible and return true on success, else false.

The default implementation sets the error state of this Device to the Device::ErrorState enumerator Device::OpenError and returns false, if isOpen() does not return false or if openMode is not compatible with the results of canRead() and/or canWrite(). Else the method sets the open mode of this Device to openMode and returns true.

Reimplemented in stm::UsbDevice, and stm::W32Device.

virtual bool stm::Device::close ( ) [virtual]

The virtual method shall close this Device, if possible and return true on success, else false.

The default implementation sets the error state of this Device to the Device::ErrorState enumerator Device::CloseError and returns false, if isOpen() returns false. Else the method sets the open mode of this Device to the Device::OpenMode enumerator Device::NoAccess and returns true.

Reimplemented in stm::UsbDevice, and stm::W32Device.

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

The virtual method shall read maximal maxLen bytes from this Device and store them in the buffer pointed to by data.

On error the method shall return -1, else the number of bytes actually read. The default implementation sets the error state of this Device to Device::ErrorState enumerator Device::ReadError and returns -1, 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. Else the method returns maxLen.

Reimplemented in stm::UsbDevice, and stm::W32Device.

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

The virtual method shall write len bytes from the buffer pointed to by data to this Device.

On error the method shall return -1, else the number of bytes actually written. The default implementation sets the error state of this Device to the Device::ErrorState enumerator Device::WriteError and returns -1, 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. Else the method returns len.

Reimplemented in stm::UsbDevice, and stm::W32Device.

virtual int64_t stm::Device::control	(	unsigned int	request,
		const void *	inData,
		int64_t	inLen,
		void *	outData,
		int64_t	maxOutLen,
		int	timeout = `DefaultTimeout`,
		unsigned int	flags = `NoFlags`
	)			const `[virtual]`

The virtual method shall perform the control operation specified by request for this Device with input data of length inLen pointed to by inData producing output data of maximal length maxOutLen in the buffer pointed to by outData.

On error the method shall return -1, else the number of bytes produced in outData. The default implementation sets the error state of this Device to the Device::ErrorState enumerator Device::ControlError and returns -1, if canControl() returns false, or if inLen is negative or inData is NULL unless inLen is also 0, or if outLen is negative or outData is NULL unless maxOutLen is also 0. Else the method returns maxOutLen.

Reimplemented in stm::UsbDevice, and stm::W32Device.

virtual int64_t stm::Device::size ( ) const [virtual]

The virtual method shall return the size of this Device, if it is an opened random access device, else -1.

The default implementation sets the error state of this Device to the Device::ErrorState enumerator Device::SeekError and returns -1, if canSeek() or isOpen() return false. Else the method returns 0.

virtual int64_t stm::Device::pos ( ) const [virtual]

The virtual method shall return the access position of this Device, if it is an opened random access device, else -1.

The default implementation sets the error state of this Device to the Device::ErrorState enumerator Device::SeekError and returns -1, if canSeek() or isOpen() return false. Else the method returns 0.

virtual bool stm::Device::seek ( int64_t pos ) [virtual]

The virtual method shall set the access position of this Device to pos and return true on success, if it is an opened random access device, else it shall return false.

The default implementation sets the error state of this Device to the Device::ErrorState enumerator Device::SeekError and returns false, if canSeek() or isOpen() return false, or if pos is negative. Else the method returns true.

virtual bool stm::Device::reset ( ) [virtual]

The virtual method shall set the access position of this Device to 0 and return true on success, if it is an opened random access device, else it shall return false.

The default implementation returns seek(0).

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

Insert a description of this Device into os.

The method shall insert a verbal description of this Device into the output stream os and return os. Format and extent of the description shall be controlled by the flags parameter according to the bitwise ored enumerators of Device::DescribeFlags. The default implementation handles the device properties device type and device Uuid for DefaultProperties and additionally the driver version property for VerboseProperties or AllProperties.

Reimplemented in stm::UsbDevice, and stm::W32Device.

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

stm::Device Class Reference [Device: Abstract Base Class for Generic Devices]

Detailed Description

Public Types

Public Member Functions

Classes

Member Enumeration Documentation

Constructor & Destructor Documentation

Member Function Documentation

stm::Device Class Reference
[Device: Abstract Base Class for Generic Devices]