#include <device.h>

Inheritance diagram for Device:

Collaboration diagram for Device:

Public Types
enum	DeviceTypes { MiscellaneousType = 0, AnalogInputType = 1, AnalogOutputType = 2, DigitalIOType = 3, TriggerType = 4, AttenuatorType = 5, AttenuateType = 6, ManipulatorType = 7, TemperatureType = 8, CameraType = 9 }

Public Member Functions
	Device (int type=MiscellaneousType)

	Device (const string &deviceclass, int type=MiscellaneousType)

virtual	~Device (void)

virtual int	open (const string &device)

virtual int	open (Device &device)

virtual bool	isOpen (void) const =0

virtual void	close (void)=0

virtual int	reset (void)

virtual const Options &	info (void) const

virtual const Options &	settings (void) const

int	deviceType (void) const

string	deviceTypeStr (void) const

string	deviceClass (void) const

string	deviceFile (void) const

string	deviceName (void) const

string	deviceVendor (void) const

string	deviceIdent (void) const

virtual void	setDeviceIdent (const string &ident)

virtual void	clearError (void)

virtual string	errorStr (void) const

void	setErrorStr (const string &strg)

void	addErrorStr (const string &strg)

void	setErrorStr (int errnum)

void	addErrorStr (int errnum)

virtual bool	success (void) const

virtual bool	failed (void) const

Static Public Member Functions
static int	deviceTypes (void)

static string	deviceTypeStr (int type)

static string	getErrorStr (int ern)

Static Public Attributes
static const int	NotOpen = -1

static const int	InvalidDevice = -2

static const int	ReadError = -3

static const int	WriteError = -4

static const int	InvalidParam = -5

Protected Member Functions
void	setDeviceType (int type)

void	setDeviceClass (const string &deviceclass)

void	setDeviceFile (const string &devicefile)

void	setDeviceName (const string &devicename)

void	setDeviceVendor (const string &devicevendor)

void	addInfo (void)

void	lock (void) const

void	unlock (void) const

QMutex *	mutex (void) const

virtual void	initOptions (void)

Protected Attributes
Options	Info

Options	Settings

Friends
ostream &	operator<< (ostream &str, const Device &d)

Detailed Description

Basic interface for accessing a device.

Author: Jan Benda

Todo:: Options as part of the device

The Device class defines the interface for the basic operations open(), close(), and reset() of a device. You have to implement at least the isOpen(), close() and one of the two open() functions.

In case you want to use a device within RELACS, your Device implementation needs to provide a void default constructor (i.e. with no parameters) that does not open the device. Make sure your constructor calls initOptions() once which registers configuation options, do not forget to also call the base class implementation. Also, include the header file <relacs/relacsplugin.h> and make the Device known to RELACS with the addDevice( ClassNameOfYourDeviceImplementation, PluginSetName ) macro or one of the derived macros for any specialized DeviceType.

A subclass of Device can be identified by its deviceType(). For example, the Temperature class provides a uniqe interface for measuring temperatures. All classes derived from the Temperature class then share the same deviceType(). The type of a Device class should be set in the constructor of the interface class either directly using setDeviceType() or by passing the type to the constructor of the Device class.

A name for class of devices a particular implementation of the Device class is handling is returned by deviceClass(). Usually deviceClass() is the name of the class derived from Device. Set the class-name for the devices in the constructor with setDeviceClass() or by passing the name to the constructor of the Device class.

Each individual physical device may have an unique identifier string deviceIdent() that can be set by setDeviceIdent(). The identifier string should be unique for each instance of a device class. The name and the vendor of the physical device is returned by deviceName() and deviceVendor(). Both should be set from within the open() function using setDeviceName() and setDeviceVendor(). The device file on which the device was opened is returned by deviceFile().

The info() function returns Options that contain some usefull information about the capabilities of the specific device. The settings() functions returns Options containing information about the current settings of the specific device. You should fill in both info() and settings() in an implementation of the Device class.

There are four flags for indicating errors with handling the device: NotOpen, InvalidDevice, ReadError, and WriteError. In addition an arbitrary error string errorStr() can be set with setErrorStr() and addErrorStr() to indicate a failure in detail.

Each device has its own mutex() for locking critical sections. Use lock() and unlock() for locking the device.

Member Enumeration Documentation

enum DeviceTypes

Predefined device types.

See Also: deviceType(), setDeviceType()

Enumerator
MiscellaneousType
AnalogInputType
AnalogOutputType
DigitalIOType
TriggerType
AttenuatorType
AttenuateType
ManipulatorType
TemperatureType
CameraType

Constructor & Destructor Documentation

Device ( int type = MiscellaneousType )

Construct a Device of type type. This constructor is used by the more specific but still abstract device classes like AnalogInput, AnalogOutput, etc.

See Also: setDeviceType()

Device	(	const string &	deviceclass,
		int	type = `MiscellaneousType`
	)

Construct a Device with class-name deviceclass and type type. Use this constructor if your device does not fit in the predefined DeviceTypes.

See Also: setDeviceClass(), setDeviceType()

~Device ( void )

virtual

Destroy a Device. In case the associated device is open, close it.

Member Function Documentation

int open ( const string & device )

virtual

Open the device specified by device with options opts. On success, in your implementation device should be passed to setDeviceFile() and the name and the vendor of the device should be set with setDeviceName() and setDeviceVendor(). The info() should be set in the implementation of open() by the info().addNumber(), info().addText(), etc. functions. For adding some default information to info() you may use addInfo(). Returns zero on success, or InvalidDevice (or any other negative number indicating the error).

See Also: isOpen(), close(), reset()

Reimplemented in Attenuate, AnalogOutput, DigitalIO, and AnalogInput.

References Device::InvalidDevice, Device::setDeviceFile(), and Device::setErrorStr().

int open ( Device & device )

virtual

Open the device specified by device with options opts. On success, in your implementation device should be passed to setDeviceFile() and the name and the vendor of the device should be set with setDeviceName() and setDeviceVendor(). The info() should be set in the implementation of open() by the info().addNumber(), info().addText(), etc. functions. For adding some default information to info() you may use addInfo(). Returns zero on success, or InvalidDevice (or any other negative number indicating the error).

See Also: isOpen(), close(), reset()

Reimplemented in Attenuate, AnalogOutput, DigitalIO, and AnalogInput.

References Device::deviceClass(), Device::deviceIdent(), Device::InvalidDevice, Device::setDeviceFile(), and Device::setErrorStr().

virtual bool isOpen ( void ) const

pure virtual

Returns true if the device is open.

See Also: open(), close(), reset()

Implemented in Attenuate, AnalogOutput, DigitalIO, and AnalogInput.

Referenced by Device::addInfo(), Attenuate::attenuate(), Attenuate::close(), Attenuate::isOpen(), Attenuate::mute(), Attenuate::open(), Attenuate::testAttenuate(), Attenuate::testMute(), Attenuate::testWrite(), and Attenuate::write().

virtual void close ( void )

pure virtual

Close the device. info() should be cleared in an implementation of close() by caling Info.clear().

See Also: open(), isOpen(), reset()

Implemented in Attenuate, AnalogOutput, DigitalIO, and AnalogInput.

Referenced by Attenuate::close().

int reset ( void )

virtual

Reset the device. Returns zero on success, otherwise one of the flags NotOpen, InvalidDevice, WriteError. An implementation should not clear the error string and should onlyadd error strings using addErrorStr().

See Also: close(), open(), isOpen()

Reimplemented in Trigger, AnalogOutput, and AnalogInput.

const Options & info ( void ) const

virtual

Returns some information about the capabilities of the device (for example, maximum possible sampling rate). This function can be reimplemented to set the the infos right before returning them.

See Also: settings()

References Device::Info.

const Options & settings ( void ) const

virtual

Returns some information about the current settings of the device (for example, the currently used sampling rate). This function can be reimplemented to set the the settings right before returning them.

See Also: info()

Reimplemented in DigitalIO.

References Device::Settings.

int deviceType ( void ) const

The id of the device type.

See Also: deviceTypeStr() setDeviceType(), deviceClass(), deviceFile(), deviceIdent(), deviceName(), deviceVendor()

Referenced by Device::addInfo().

string deviceTypeStr ( void ) const

Returns: a string naming the device type.

See Also: deviceType() setDeviceType(), deviceClass(), deviceFile(), deviceIdent(), deviceName(), deviceVendor()

int deviceTypes ( void )

static

Returns: the number of known device types.

See Also: deviceTypeStr(), deviceType()

string deviceTypeStr ( int type )

static

Returns: a string naming the device type type.

See Also: deviceType(), deviecTypes()

string deviceClass ( void ) const

The name for the device(s) a particular implementation of the Device class is handling.

See Also: setDeviceClass(), deviceIdent(), deviceType(), deviceFile(), deviceName(), deviceVendor()

Referenced by Device::addInfo(), and Device::open().

string deviceFile ( void ) const

The name of the device file on which the device was opened.

See Also: setDeviceFile(), deviceIdent(), deviceClass(), deviceType(), deviceName(), deviceVendor()

Referenced by Device::addInfo().

string deviceName ( void ) const

The name of the particular physical device that is handled by this instance of the Device class.

See Also: setDeviceName(), deviceIdent(), deviceClass(), deviceType(), deviceFile(), deviceVendor()

Referenced by Device::addInfo().

string deviceVendor ( void ) const

The vendor of the particular physical device that is handled by this instance of the Device class.

See Also: setDeviceVendor(), deviceIdent(), deviceClass(), deviceType(), deviceFile(), deviceName()

Referenced by Device::addInfo().

string deviceIdent ( void ) const

The uniqe identifier string of an individual physical device.

See Also: setDeviceIdent(), deviceType(), deviceClass(), deviceFile(), deviceName(), deviceVendor()

Referenced by Device::addInfo(), Attenuate::init(), AnalogInput::open(), DigitalIO::open(), AnalogOutput::open(), Device::open(), and Attenuate::open().

void setDeviceIdent ( const string & ident )

virtual

Set the identifier string of an individual physical device to ident.

See Also: deviceIdent(), setDeviceClass(), setDeviceType(), setDeviceFile(), setDeviceName(), setDeviceVendor()

References Device::Info.

void clearError ( void )

virtual

Clear the error string.

See Also: setErrorStr(), addErrorStr()

Referenced by AnalogOutput::setErrorStr().

string errorStr ( void ) const

virtual

Return error string of the last operation.

See Also: setErrorStr(), addErrorStr()

void setErrorStr ( const string & strg )

Set error string to strg.

See Also: addErrorStr(), errorStr()

Referenced by Device::open(), and AnalogOutput::setErrorStr().

void addErrorStr ( const string & strg )

Add strg to the error string.

See Also: setErrorStr(), errorStr()

Referenced by AnalogOutput::addErrorStr(), and AnalogInput::run().

void setErrorStr ( int errnum )

Set error string to the string describing the standard C error code errnum (from errno).

See Also: addErrorStr(), errorStr()

void addErrorStr ( int errnum )

Add the string describing the standard C error code errnum (from errno) to the error string.

See Also: setErrorStr(), errorStr()

string getErrorStr ( int ern )

static

Translates the error code ern returned by open(), reset(), etc. into a string.

References Device::InvalidDevice, Device::NotOpen, Device::ReadError, and Device::WriteError.

Referenced by AnalogInput::run(), and AnalogOutput::run().

bool success ( void ) const

virtual

Return true if the last operation was successfull and did not set an error string, i.e. errorStr().empty().

bool failed ( void ) const

virtual

Return true if the last operation failed and did set an error string, i.e. not errorStr().empty().

void setDeviceType ( int type )

protected

Set id of the device class to type. This function should be called in the constructor of an device interface class.

See Also: deviceType(), setDeviceClass(), setDeviceFile(), setDeviceIdent(), setDeviceName(), setDeviceVendor()

void setDeviceClass ( const string & deviceclass )

protected

Set the name for the class of devices a particular implementation of the Devive class is handling to deviceclass. This function should be called in the constructor and/or the open function of the Device class implementation.