Base class for input/output classes. More...

Inheritance diagram for PIIODevice:

Protected Member Functions
virtual bool	init ()
	Function executed before first openDevice() or from constructor.

virtual bool	configureDevice (const void e_main, const void e_parent=0)
	Reimplement to configure device from entries "e_main" and "e_parent", cast arguments to PIConfig::Entry*.

virtual bool	openDevice ()=0
	Reimplement to open device, return value will be set to "opened_" variable.

virtual bool	closeDevice ()
	Reimplement to close device, inverse return value will be set to "opened_" variable.

virtual bool	threadedRead (uchar *readed, int size)
	Function executed when thread read some data, default implementation execute external slot "ret_func_".

virtual PIString	fullPathPrefix () const
	Reimplement to construct full unambiguous string prefix. Creating devices by unambiguous string.

virtual void	configureFromFullPath (const PIString &full_path)
	Reimplement to configure your device with parameters of full unambiguous string. Default implementation does nothing.

Protected Member Functions inherited from PIObject
PIObject *	emitter () const
	Returns PIObject* which has raised an event. This value is correct only in definition of some event handler.

virtual void	propertyChanged (const PIString &name)
	Virtual function executes after property with name "name" has been changed.

Related Functions
(Note that these are not member functions.)
template<typename T >
T	readDeviceSetting (const PIString &name, const T &def, const PIConfig::Entry em, const PIConfig::Entry ep)
	Service function. useful for configuring devices. More...

#define	REGISTER_DEVICE(class)
	Use this macro to enable automatic creation instances of your class with createFromFullPath() function.

#define	PIIODEVICE(class)
	Use this macro instead of PIOBJECT when describe your own PIIODevice.

Related Functions inherited from PIObject
#define	piCoutObj
	Macro used for conditional (piDebug and PIObject::debug()) output to PICout for subclasses of PIObject.

#define	PIOBJECT(name)
	you should use this macro after class declaration to use EVENT and EVENT_HANDLER and correct piCoutObj output

#define	PIOBJECT_PARENT(name)
	you should use this macro after class declaration to use EVENT and EVENT_HANDLER of parent class

#define	EVENT_HANDLER0(ret, name) ret name()
	declare event handler "event" with name "name" and return type "ret", ret name()

#define	EVENT_HANDLER1(ret, name, type0, var0) ret name(type0 var0)
	declare event handler "event" with name "name" and return type "ret", ret name(type0 var0)

#define	EVENT_HANDLER2(ret, name, type0, var0, type1, var1) ret name(type0 var0, type1 var1)
	declare event handler "event" with name "name" and return type "ret", ret name(type0 var0, type1 var1)

#define	EVENT_HANDLER3(ret, name, type0, var0, type1, var1, type2, var2) ret name(type0 var0, type1 var1, type2 var2)
	declare event handler "event" with name "name" and return type "ret", ret name(type0 var0, type1 var1, type2 var2)

#define	EVENT_HANDLER4(ret, name, type0, var0, type1, var1, type2, var2, type3, var3) ret name(type0 var0, type1 var1, type2 var2, type3 var3)
	declare event handler "event" with name "name" and return type "ret", ret name(type0 var0, type1 var1, type2 var2, type3 var3)

#define	EVENT_HANDLER EVENT_HANDLER0
	EVENT_HANDLER is synonym of EVENT_HANDLER0.

#define	EVENT_VHANDLER0(ret, name) virtual ret name()
	declare virtual event handler "event" with name "name" and return type "ret", virtual ret name()

#define	EVENT_VHANDLER1(ret, name, type0, var0) virtual ret name(type0 var0)
	declare virtual event handler "event" with name "name" and return type "ret", virtual ret name(type0 var0)

#define	EVENT_VHANDLER2(ret, name, type0, var0, type1, var1) virtual ret name(type0 var0, type1 var1)
	declare virtual event handler "event" with name "name" and return type "ret", virtual ret name(type0 var0, type1 var1)

#define	EVENT_VHANDLER3(ret, name, type0, var0, type1, var1, type2, var2) virtual ret name(type0 var0, type1 var1, type2 var2)
	declare virtual event handler "event" with name "name" and return type "ret", virtual ret name(type0 var0, type1 var1, type2 var2)

#define	EVENT_VHANDLER4(ret, name, type0, var0, type1, var1, type2, var2, type3, var3) virtual ret name(type0 var0, type1 var1, type2 var2, type3 var3)
	declare virtual event handler "event" with name "name" and return type "ret", virtual ret name(type0 var0, type1 var1, type2 var2, type3 var3)

#define	EVENT_VHANDLER EVENT_VHANDLER0
	EVENT_VHANDLER is synonym of EVENT_VHANDLER0.

#define	EVENT0(name) void name();
	declare event "event" with name "name", void name();

#define	EVENT1(name, type0, var0) void name(type0 var0);
	declare event "event" with name "name", void name(type0 var0);

#define	EVENT2(name, type0, var0, type1, var1) void name(type0 var0, type1 var1);
	declare event "event" with name "name", void name(type0 var0, type1 var1);

#define	EVENT3(name, type0, var0, type1, var1, type2, var2) void name(type0 var0, type1 var1, type2 var2);
	declare event "event" with name "name", void name(type0 var0, type1 var1, type2 var2);

#define	EVENT4(name, type0, var0, type1, var1, type2, var2, type3, var3) void name(type0 var0, type1 var1, type2 var2, type3 var3);
	declare event "event" with name "name", void name(type0 var0, type1 var1, type2 var2, type3 var3);

#define	EVENT EVENT0
	EVENT is synonym of EVENT0.

#define	CONNECTU(src, event, dest, handler)
	connect event "event" from object "src" to event handler "handler". "Event" and "handler" must has equal argument lists.

#define	CONNECT0(ret, src, event, dest, handler)
	connect event "event" from object "src" to event handler "handler" with return type "ret" from object "dest" with check of event and handler exists

#define	CONNECT1(ret, type0, src, event, dest, handler)
	connect event "event" from object "src" to event handler "handler" with return type "ret" from object "dest" with check of event and handler exists

#define	CONNECT2(ret, type0, type1, src, event, dest, handler)
	connect event "event" from object "src" to event handler "handler" with return type "ret" from object "dest" with check of event and handler exists

#define	CONNECT3(ret, type0, type1, type2, src, event, dest, handler)
	connect event "event" from object "src" to event handler "handler" with return type "ret" from object "dest" with check of event and handler exists

#define	CONNECT4(ret, type0, type1, type2, type3, src, event, dest, handler)
	connect event "event" from object "src" to event handler "handler" with return type "ret" from object "dest" with check of event and handler exists

#define	CONNECT CONNECT0
	CONNECT is synonym of CONNECT0.

#define	WEAK_CONNECT0(ret, src, event, dest, handler)
	connect event "event" from object "src" to event handler "handler" with return type "ret" from object "dest" without check of event exists

#define	WEAK_CONNECT1(ret, type0, src, event, dest, handler)
	connect event "event" from object "src" to event handler "handler" with return type "ret" from object "dest" without check of event exists

#define	WEAK_CONNECT2(ret, type0, type1, src, event, dest, handler)
	connect event "event" from object "src" to event handler "handler" with return type "ret" from object "dest" without check of event exists

#define	WEAK_CONNECT3(ret, type0, type1, type2, src, event, dest, handler)
	connect event "event" from object "src" to event handler "handler" with return type "ret" from object "dest" without check of event exists

#define	WEAK_CONNECT4(ret, type0, type1, type2, type3, src, event, dest, handler)
	connect event "event" from object "src" to event handler "handler" with return type "ret" from object "dest" without check of event exists

#define	WEAK_CONNECT WEAK_CONNECT0
	WEAK_CONNECT is synonym of WEAK_CONNECT0.

#define	DISCONNECT0(ret, src, event, dest, handler)
	piDisconnect event "event" from object "src" from event handler "handler" with return type "ret" from object "dest"

#define	DISCONNECT1(ret, type0, src, event, dest, handler)
	piDisconnect event "event" from object "src" from event handler "handler" with return type "ret" from object "dest"

#define	DISCONNECT2(ret, type0, type1, src, event, dest, handler)
	piDisconnect event "event" from object "src" from event handler "handler" with return type "ret" from object "dest"

#define	DISCONNECT3(ret, type0, type1, type2, src, event, dest, handler)
	piDisconnect event "event" from object "src" from event handler "handler" with return type "ret" from object "dest"

#define	DISCONNECT4(ret, type0, type1, type2, type3, src, event, dest, handler)
	piDisconnect event "event" from object "src" from event handler "handler" with return type "ret" from object "dest"

#define	DISCONNECT DISCONNECT0
	DISCONNECT is synonym of DISCONNECT0.

#define	HANDLER(handler)
	Returns pointer to events handler "handler".

Additional Inherited Members
Public Types inherited from PIThread
enum	Priority { piLowerst, piLow, piNormal, piHigh, piHighest }
	Priority of thread. More...

Public Member Functions inherited from PIThread
	PIThread (void *data, ThreadFunc func, bool startNow=false, int loop_delay=-1)
	Contructs thread with custom data "data", external function "func" and main loop delay "loop_delay".

	PIThread (bool startNow=false, int loop_delay=-1)
	Contructs thread with main loop delay "loop_delay".

void	setData (void *d)
	Set common data passed to external function.

void	setSlot (ThreadFunc func)
	Set external function that will be executed after every run()

void	setPriority (PIThread::Priority prior)
	Set priority of thread.

void *	data () const
	Returns common data passed to external function.

PIThread::Priority	priority () const
	Return priority of thread.

bool	isRunning () const
	Return `true` if thread is running.

void	needLockRun (bool need)
	Set necessity of lock every run with internal mutex.

PIMutex &	mutex ()
	Return internal mutex.

bool	start (int timer_delay)
	Start thread. More...

bool	start (ThreadFunc func, int timer_delay)
	Start thread. More...

bool	startOnce ()
	Start thread without internal loop. More...

bool	startOnce (ThreadFunc func)
	Start thread without internal loop. More...

void	stop (bool wait)
	Stop thread. More...

void	terminate ()
	Strongly stop thread. More...

bool	waitForStart (int timeout_msecs)
	Wait for thread start. More...

bool	waitForFinish (int timeout_msecs)
	Wait for thread finish. More...

void	lock ()
	Lock internal mutex.

void	unlock ()
	Unlock internal mutex.

void	started ()
	Raise on thread start.

void	stopped ()
	Raise on thread stop.

Public Member Functions inherited from PIObject
	PIObject (const PIString &name=PIString())
	Contructs PIObject with name "name".

PIString	name () const
	Returns object name.

virtual const char *	className () const
	Returns object class name.

virtual const char *	superClassName () const
	Returns object superclass name.

bool	debug () const
	Return if debug of this object is active.

void	setName (const PIString &name)
	Set object name.

void	setDebug (bool debug)
	Set object debug active.

const PIMap< PIString, PIVariant > &	properties () const
	Returns properties of the object.

int	propertiesCount () const
	Returns properties count of the object.

PIVariant	property (const PIString &name) const
	Returns property with name "name".

void	setProperty (const PIString &name, const PIVariant &value)
	Set property with name "name" to "value". If there is no such property in object it will be added.

bool	isPropertyExists (const PIString &name) const
	Returns if property with name "name" exists.

Static Public Member Functions inherited from PIObject
static void	piDisconnect (PIObject *src, const PIString &sig)
	Disconnect object "src" from all connections with event name "sig".

static void	piDisconnect (PIObject *src)
	Disconnect object "src" from all connections, i.e. all connections where object "src" is emitter.

static PIObject *	findByName (const PIString &name)
	Returns PIObject* with name "name" or 0, if there is no object found.

Detailed Description

Base class for input/output classes.

Synopsis

This class provide open/close logic, threaded read/write and virtual input/output functions read() and write(). You should implement pure virtual function openDevice() in your subclass.

Open and close

PIIODevice have boolean variable indicated open status. Returns of functions openDevice() and closeDevice() change this variable.

Threaded read

PIIODevice based on PIThread, so it`s overload run() to exec read() in background thread. If read is successful virtual function threadedRead() is executed. Default implementation of this function execute external static function set by setThreadedReadSlot() with data set by setThreadedReadData(). Extrenal static function should have format
bool func_name(void * Threaded_read_data, uchar * readed_data, int readed_size)
Threaded read starts with function startThreadedRead().

Threaded write

PIIODevice aggregate another PIThread to perform a threaded write by function writeThreaded(). This function add task to internal queue and return queue entry ID. You should start write thread by function startThreadedWrite. On successful write event threadedWriteEvent is raised with two arguments - task ID and written bytes count.

Internal buffer

PIIODevice have internal buffer for threaded read, and threadedRead() function receive pointer to this buffer in first argument. You can adjust size of this buffer by function setThreadedReadBufferSize()
Default size of this buffer is 4096 bytes.

Reopen

When threaded read is begin its call open() if device is closed. While threaded read running PIIODevice check if device opened every read and if not call open() every reopen timeout if reopen enabled. Reopen timeout is set by setReopenTimeout(), reopen enable is set by setReopenEnabled().

Configuration

This is virtual function configureDevice() which executes when configure() executes. This function takes two arguments: "e_main" and "e_parent" as void*. There are pointers to PIConfig::Entry entries of section "section" and their parent. If there is no parent "e_parent" = 0. Function configure() set three parameters of device: "reopenEnabled", "reopenTimeout" and "threadedReadBufferSize", then execute function configureDevice().
Each ancestor of PIIODevice reimlements configureDevice() function to be able to be confured from configuration file. This parameters described at section "Configurable parameters" in the class reference.
Usage example:

// file example.conf
dev.reopenEnabled = false
dev.device = /dev/ttyS0
dev.speed = 9600
// end example.conf
// code
PISerial ser;
ser.configure("example.conf", "dev");

Implementation example:

class SomeIO: public PIIODevice {
    ...
    bool configureDevice(const void * e_main, const void * e_parent) {
        PIConfig::Entry * em = (PIConfig::Entry * )e_main;
        PIConfig::Entry * ep = (PIConfig::Entry * )e_parent;
        setStringParam(readDeviceSetting<PIString>("stringParam", stringParam(), em, ep));
        setIntParam(readDeviceSetting<int>("intParam", intParam(), em, ep));
        return true;
    }
    ...
};

Creating devices by unambiguous string

There are some virtual functions to describe child class without its declaration.
fullPathPrefix() should returns unique prefix of device
constructFullPath() should returns full unambiguous string, contains prefix and all device parameters
configureFromFullPath() provide configuring device from full unambiguous string without prefix and "://"
Macro PIIODEVICE should be used instead of PIOBJECT
Macro REGISTER_DEVICE should be used after definition of class, i.e. at the last line of *.cpp file

If custom I/O device corresponds there rules, it can be returned by function createFromFullPath().
Each PIP I/O device has custom unambiguous string description:

PIFile: "file://<path>"
PIBinaryLog: "binlog://<logDir>[:<filePrefix>][:<defaultID>]"
PISerial: "ser://<device>:<speed(50|...|115200)>[:<dataBitsCount(6|7|8)>][:<parity(N|E|O)>][:<stopBits(1|2)>]"
PIEthernet: "eth://<type(UDP|TCP)>:<readIP>:<readPort>[:<multicast(mcast:<ip>)>]"
PIUSB: "usb://<vid>:<pid>[:<deviceNumber>][:<readEndpointNumber>][:<writeEndpointNumber>]"

Examples:
PIFile: "file://../text.txt"
PIBinaryLog: "binlog://../logs/:mylog_:1"
PISerial: "ser:///dev/ttyUSB0:9600:8:N:1", equivalent "ser:///dev/ttyUSB0:9600"
PIEthernet: "eth://TCP:127.0.0.1:16666", "eth://UDP:192.168.0.5:16666:mcast:234.0.2.1:mcast:234.0.2.2"
PIUSB: "usb://0bb4:0c86:1:1:2"

So, custom I/O device can be created with next call:
// creatring devices

PISerial * ser = (PISerial * )PIIODevice::createFromFullPath("ser://COM1:115200");

PIEthernet * eth = (PIEthernet * )PIIODevice::createFromFullPath("eth://UDP:127.0.0.1:4001");

// examine devices

piCout << ser << ser->properties();

piCout << eth << eth->properties();

Example

class SomeIO: public PIIODevice {
    PIIODEVICE(SomeIO)
public:
    SomeIO(): PIIODevice() {}
protected:
    bool openDevice() {
        // open your device here
        return if_success;
    }
    int read(void * read_to, int max_size) {
        // read from your device here
        return readed_bytes;
    }
    int write(const void * data, int max_size) {
        // write to your device here
        return written_bytes;
    }
    PIString fullPathPrefix() const {return "myio";}
    void configureFromFullPath(const PIString & full_path) {
        // parse full_path and configure device there
    }
};
REGISTER_DEVICE(SomeIO)

Friends And Related Function Documentation

template<typename T >

T readDeviceSetting	(	const PIString &	name,
		const T &	def,
		const PIConfig::Entry *	em,
		const PIConfig::Entry *	ep
	)

Function takes entry name "name", default value "def" and two PIConfig::Entry sections: "em" and their parent "ep". If there is no parent ep = 0. If "ep" is not null and entry "name" exists in "ep" function returns this value. Else returns value of entry "name" in section "em" or "def" if entry doesn`t exists.
This function useful to read settings from configuration file in implementation PIIODevice::configureDevice() function

Protected Member Functions

Related Functions

Additional Inherited Members