Home Libraries Author Links

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

Inheritance diagram for stm::Device:

Inheritance graph
[legend]

List of all members.


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.
Deviceoperator= (const Device &other)
 Copy assignment operator.
virtual ~Device ()
 Destructor.
virtual const Uuiduuid () 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 Descriptordescr () 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.


© Copyright Tom Michaelis 2002-2007

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