Home

Libraries

Author

Links

---

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

Inheritance diagram for stm::W32Device:

[legend]

Collaboration diagram for stm::W32Device:

[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).