# PIP: PIIODevice Class Reference

PIIODevice Class Referenceabstract

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

Inheritance diagram for PIIODevice:
[legend]

## Public Types

enum | DeviceMode { ReadOnly = 0x01, WriteOnly = 0x02, ReadWrite = 0x03 }
| Open modes for PIIODevice. More...
Public Types inherited from PIThread
enum | Priority { piLowerst, piLow, piNormal, piHigh, piHighest }
| Priority of thread. More...

## Public Member Functions

| PIIODevice ()
| Constructs a empty PIIODevice.
| PIIODevice (const PIString &path, DeviceMode mode=ReadWrite)
| Constructs a PIIODevice with path and mode. More...
DeviceMode | mode () const
| Current open mode of device.
PIString | path () const
| Current path of device.
void | setPath (const PIString &path)
| Set path of device.
bool | isReadable () const
| Return true if mode is ReadOnly or ReadWrite.
bool | isWriteable () const
| Return true if mode is WriteOnly or ReadWrite.
bool | isOpened () const
| Return true if device is successfully opened.
bool | isClosed () const
| Return true if device is closed.
virtual bool | canRead () const
| Return true if device can read now.
virtual bool | canWrite () const
| Return true if device can write now.
void | setReopenEnabled (bool yes=true)
| Set execution of open enabled while threaded read on closed device.
void | setReopenTimeout (int msecs)
| Set timeout in milliseconds between open tryings if reopen is enabled.
bool | isReopenEnabled () const
| Return reopen enable.
int | reopenTimeout ()
| Return reopen timeout.
void | setThreadedReadSlot (ReadRetFunc func)
| Set "threaded read slot". More...
void | setThreadedReadData (void *d)
| Set custom data that will be passed to "threaded read slot".
void | setThreadedReadBufferSize (int new_size)
| Set size of threaded read buffer. More...
int | threadedReadBufferSize () const
| Return size of threaded read buffer.
const uchar * | threadedReadBuffer () const
| Return content of threaded read buffer.
void * | threadedReadData () const
| Return custom data that will be passed to "threaded read slot".
bool | isThreadedRead () const
| Return true if threaded read is started.
void | startThreadedRead ()
| Start threaded read.
void | startThreadedRead (ReadRetFunc func)
| Start threaded read and assign "threaded read slot" to "func".
void | stopThreadedRead ()
| Stop threaded read.
bool | isThreadedWrite () const
| Return true if threaded write is started.
void | startThreadedWrite ()
| Start threaded write.
void | stopThreadedWrite ()
| Stop threaded write.
void | clearThreadedWriteQueue ()
| Clear threaded write task queue.
void | start ()
| Start both threaded read and threaded write.
void | stop (bool wait=false)
| Stop both threaded read and threaded write and if "wait" block until both threads are stop.
virtual int | read (void *read_to, int max_size)
| Reimplement this function to read from your device.
virtual int | write (const void *data, int max_size)
| Reimplement this function to write to your device.
PIByteArray | read (int max_size)
| Read from device maximum "max_size" bytes and return them as PIByteArray.
PIByteArray | readForTime (double timeout_ms)
| Read from device for "timeout_ms" milliseconds and return readed data as PIByteArray. Timeout should to be greater than 0.
int | write (const PIByteArray &data)
| Write "data" to device.
ullong | writeThreaded (const void *data, int max_size)
| Add task to threaded write queue and return task ID.
ullong | writeThreaded (const PIByteArray &data)
| Add task to threaded write queue and return task ID.
bool | configure (const PIString &config_file, const PIString &section, bool parent_section=false)
| Configure device from section "section" of file "config_file", if "parent_section" parent section also will be read.
virtual PIString | fullPathPrefix () const
| Reimplement to construct full unambiguous string prefix. Creating devices by unambiguous string.
virtual PIString | constructFullPath () const
| Reimplement to construct full unambiguous string, describes this device, default returns fullPathPrefix() + "://" + path()
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

static PIIODevice * | createFromFullPath (const PIString &full_path)
| Try to determine suitable device, create new one, configure it with configureFromFullPath() and returns it. More...
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.

## 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 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.
void | deleted ()
| Raise before object delete. More...

## 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_SUBCLASS(name, parent)
| 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".

## Handlers

bool | open ()
| Open device.
bool | open (const PIString &_path)
| Open device with path "path".
bool | open (const DeviceMode &_mode)
| Open device with mode "mode".
bool | open (const PIString &_path, const DeviceMode &_mode)
| Open device with path "path" and mode "mode".
bool | close ()
| Close device.
bool | initialize ()
| Initialize device.

## Virtual handlers

virtual void | flush ()
| Immediate write all buffers.

## Events

void | opened ()
| Raise if succesfull open.
void | closed ()
| Raise if succesfull close.
void | threadedReadEvent (uchar *readed, int size)
| Raise if read thread succesfull read some data.
void | threadedWriteEvent (ullong id, int written_size)
| Raise if write thread succesfull write some data of task with ID "id".

## Configurable parameters

bool | reopenEnabled
| setReopenEnabled, default "true"
int | reopenTimeout
| setReopenTimeout in ms, default 1000
int | threadedReadBufferSize
| setThreadedReadBufferSize in bytes, default 4096

## 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: UDP "eth://UDP:<readIP>:<readPort>:<sendIP>:<sendPort>[:<multicast(mcast:<ip>)>]"
- PIEthernet: TCP "eth://TCP:<IP>:<Port>"
- 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:192.168.0.6:16667: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:127.0.0.1:4002");
  // 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)

## Member Enumeration Documentation

enum PIIODevice::DeviceMode

Open modes for PIIODevice.

Enumerator
ReadOnly | Device can only read
WriteOnly | Device can only write
ReadWrite | Device can both read and write

## Constructor & Destructor Documentation

PIIODevice::PIIODevice | ( | const PIString & | path,
|  | PIIODevice::DeviceMode | mode = `ReadWrite`
| ) |  |

Constructs a PIIODevice with path and mode.

Parameters

  path | path to device
  type | mode for open

## Member Function Documentation

void PIIODevice::setThreadedReadSlot | ( | ReadRetFunc | func | ) |

inline

Set "threaded read slot".

Set external static function of threaded read that will be executed at every successful threaded read. Function should have format "bool func(void * data, uchar * readed, int size)"

void PIIODevice::setThreadedReadBufferSize | ( | int | new_size | ) |

inline

Set size of threaded read buffer.

Default size is 4096 bytes. If your device can read at single read more than 4096 bytes you should use this function to adjust buffer size

PIIODevice * PIIODevice::createFromFullPath | ( | const PIString & | full_path | ) |

static

Try to determine suitable device, create new one, configure it with configureFromFullPath() and returns it.

To function configureFromFullPath() "full_path" passed without fullPathPrefix() + "://". See Creating devices by unambiguous string

## Friends And Related Function Documentation

template<typename T >

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

related

Service function. useful for configuring devices.

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