Home Libraries Author Links

stm::W32Device Class Reference
[W32Device: Base Class for Win32 Devices]

Inheritance diagram for stm::W32Device:

Inheritance graph
[legend]
Collaboration diagram for stm::W32Device:

Collaboration graph
[legend]

List of all members.


Detailed Description

Class defining the C++ API for a Windows device inheriting the generic stm::Device C++ API.

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

Definition at line 128 of file w32device.hpp.


Public Types

enum  DescribeFlags {
  DevicePath = DriverVersion << 1,
  DeviceInstance = DevicePath << 1,
  DeviceIfClass = DeviceInstance << 1
}
 Describe flags (bitwise orable). More...

Public Member Functions

 W32Device (int defaultTimeout=Forever, const Descriptor &descr=Descriptor())
 Constructor of a W32Device object representing a Windows device described by descr.
virtual ~W32Device ()
 Destructor.
virtual bool canRead () const
 Return the read capability of this W32Device.
virtual bool canWrite () const
 Return the write capability of this W32Device.
virtual bool canControl () const
 Return the control capability of this W32Device.
virtual int error () const
 Return the error state of this W32Device.
virtual void setError (int error, const std::string &msg=std::string()) const
 Set the error state and error string of this W32Device according to error and msg.
virtual void clearError () const
 Clear the error state and error string of this W32Device.
virtual bool isOpen () const
 Determine, if this W32Device is open.
virtual bool open (unsigned int openMode)
 Open this W32Device in openMode.
virtual bool close ()
 Close this W32Device.
virtual int64_t read (void *data, int64_t maxLen, int timeout=DefaultTimeout, unsigned int flags=NoFlags)
 Read maxLen bytes from this W32Device 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 this W32Device.
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
 Perform the control operation request on this W32Device.
virtual std::ostream & describe (std::ostream &os, unsigned int flags=DefaultProperties) const
 Insert a description of this W32Device into os.
bool isA (const InterfaceClass &interfaceClass) const
 The method returns true, if this W32Device is a device supporting the Windows device interface class described by interfaceClass.
template<class ForwardIterator>
bool isA (ForwardIterator beginInterfaceClass, ForwardIterator endInterfaceClass) const
 The method template returns true, if this W32Device is a device supporting one of the the Windows 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)
 Enumerate all Device::Descriptor objects describing Windows devices supporting the Windows 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 Windows devices supporting one of the the Windows device interface classes whose description is contained in the half open interval [*beginInterfaceClass, *endInterfaceClass).

Classes

struct  InterfaceClass
 Type describing a Windows device interface class. More...

Member Enumeration Documentation

enum stm::W32Device::DescribeFlags

Describe flags (bitwise orable).

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

Enumerator:
DevicePath  If set, the device path property is included, else not.
DeviceInstance  If set, the device instance property is included, else not.
DeviceIfClass  If set, the device interface class property is included, else not.

Reimplemented from stm::Device.

Definition at line 137 of file w32device.hpp.


Constructor & Destructor Documentation

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

Constructor of a W32Device object representing a Windows device described by descr.

Parameters:
[in] defaultTimeout Timeout in milliseconds used by default for all operations of this W32Device.
[in] descr A valid Device::Descriptor of the Windows device to be represented by the W32Device 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 W32Device object with the Device::Descriptor descr defined for it. If descr is valid, the constructed W32Device is ready to be opened.
See also:
descr(), open(), enumerate(), enumerateAll().

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

Destructor.

Effects:
If this W32Device is open, it is closed first.
See also:
isOpen(), close().


Member Function Documentation

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

Return the read capability of this W32Device.

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 W32Device is open.

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

Reimplemented from stm::Device.

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

Return the write capability of this W32Device.

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 W32Device is open.

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

Reimplemented from stm::Device.

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

Return the control capability of this W32Device.

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 W32Device is open.

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

Reimplemented from stm::Device.

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

Return the error state of this W32Device.

Effects:
If the error state of this W32Device is Device::NoError, the Windows last-error code is cleared.
Returns:
The error state of this W32Device as one of the enumerators of Device::ErrorState.
Note:
It is not necessary that this W32Device is open.
See also:
setError(), clearError(), errorString().

Reimplemented from stm::Device.

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

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

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

Reimplemented from stm::Device.

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

Clear the error state and error string of this W32Device.

Effects:
The error state and error string of this W32Device are cleared, that means set to Device::NoError and the empty string. Moreover, the Windows last-error code is cleared.
Note:
Despite of being const, the method can change the error state and error string.

It is not necessary that this W32Device is open.

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

Reimplemented from stm::Device.

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

Determine, if this W32Device is open.

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

false, if this W32Device 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::W32Device::open ( unsigned int  openMode  )  [virtual]

Open this W32Device in openMode.

Parameters:
[in] openMode Open mode to be set.
Effects:
The method sets the error state of this W32Device 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 Windows device represented by this W32Device cannot be opened conforming to openMode. Else the method sets the open mode of this W32Device to openMode.
Returns:
true, if this W32Device could be opened in openMode.

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

See also:
isOpen(), close(), error ().

Reimplemented from stm::Device.

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

Close this W32Device.

Effects:
The method sets the error state of this W32Device to the Device::ErrorState enumerator Device::CloseError, if isOpen() returns false or if the Windows device represented by this W32Device cannot be closed successfully. Else the method sets the open mode of this W32Device to the Device::OpenMode enumerator Device::NoAccess.
Returns:
true, if this W32Device could be closed successfully.

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

See also:
isOpen(), open(), error ().

Reimplemented from stm::Device.

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

Read maxLen bytes from this W32Device 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 W32Device 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 W32Device 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 Windows device represented by this W32Device are read and 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 W32Device is set to Device::ReadError.

See also:
write(), control(), openMode(), error (), defaultTimeout().

Reimplemented from stm::Device.

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

Write len bytes from the data buffer to this W32Device.

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 W32Device 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 W32Device 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 to the Windows device represented by this W32Device.
Returns:
len, if the write operation was successful.

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

See also:
read(), control(), openMode(), error (), defaultTimeout().

Reimplemented from stm::Device.

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

Perform the control operation request on this W32Device.

Parameters:
[in] request Specifies the particular control operation to be performed.
[in] inData Buffer containing the input data for the control operation.
[in] inLen Number of bytes of the input data.
[out] outData Buffer for the output data generated by the control operation.
[in] maxOutLen Maximal number of the output data.
[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 W32Device 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 Windows device represented by this W32Device. If any input data are required, the parameter inData shall point to a buffer of length inLen containing them, else inData shall be NULL and inLen 0. If any data result is expected, outData shall not be NULL and point to a buffer of size maxOutLen.
Returns:
The number of bytes available in outData, 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 W32Device is set to the Device::ErrorState enumerator Device::ControlError.

See also:
write(), read(), openMode(), error (), defaultTimeout().

Reimplemented from stm::Device.

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

Insert a description of this W32Device 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 W32Device 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 W32Device::DescribeFlags.
Returns:
The output stream os.
Note:
This W32Device need not be open.

Reimplemented from stm::Device.

bool stm::W32Device::isA ( const InterfaceClass interfaceClass  )  const

The method returns true, if this W32Device is a device supporting the Windows device interface class described by interfaceClass.

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

template<class ForwardIterator>
bool stm::W32Device::isA ( ForwardIterator  beginInterfaceClass,
ForwardIterator  endInterfaceClass 
) const

The method template returns true, if this W32Device is a device supporting one of the the Windows 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 W32Device describes a Windows device supporting one of the Windows device interface classes described by that interval, else false.

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

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

The static method clears the vector descriptors, scans the system for all Windows devices supporting the Windows 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.

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

Enumerate all Device::Descriptor objects describing Windows devices supporting one of the the Windows 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 Windows devices supporting one of the Windows 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.


© Copyright Tom Michaelis 2002-2007

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