# PIP: PIConnection Class Reference

PIConnection Class Reference

Complex Input/Output point. More...

Inheritance diagram for PIConnection:
[legend]

## Public Member Functions

| PIConnection ()
| Constructs an empty connection.
| PIConnection (const PIString &name)
| Constructs connection with name "name".
| PIConnection (const PIString &config, const PIString &name)
| Constructs connection and configure it from config file "config" from section "name".
| PIConnection (PIString *string, const PIString &name)
| Constructs connection and configure it from config content "string" from section "name".
bool | configureFromConfig (const PIString &config, const PIString &name)
| Configure connection from config file "config" from section "name". Returns if configuration was successful. More...
bool | configureFromString (PIString *string, const PIString &name)
| Configure connection from config content "string" from section "name". Returns if configuration was successful. More...
PIString | makeConfig () const
| Returns config file section of current connection configuration.
PIIODevice * | addDevice (const PIString &full_path, PIIODevice::DeviceMode mode=PIIODevice::ReadWrite, bool start=false)
| Add device with full path "full_path", open mode "mode" to Device pool and connection. More...
bool | removeDevice (const PIString &full_path)
| Remove device with full path "full_path" from connection. More...
void | removeAllDevices ()
| Remove all device from connection. More...
PIIODevice * | deviceByFullPath (const PIString &full_path) const
| Returns device with full path "full_path" or null if there is no such device.
PIIODevice * | deviceByName (const PIString &name) const
| Returns device with name "name" or null if there is no such device.
PIVector< PIIODevice * > | boundedDevices () const
| Returns all devices bounded to this connection.
PIPacketExtractor * | addFilter (const PIString &name, const PIString &full_path_name, PIPacketExtractor::SplitMode mode=PIPacketExtractor::None)
| Add filter with name "name" to device with full path "full_path_name" or filter "full_path_name". More...
PIPacketExtractor * | addFilter (const PIString &name, const PIIODevice *dev, PIPacketExtractor::SplitMode mode=PIPacketExtractor::None)
| Add filter with name "name" to device "dev".
bool | removeFilter (const PIString &name, const PIString &full_path_name)
| Remove from filter with name "name" device with full path "full_path_name" or filter "full_path_name". More...
bool | removeFilter (const PIString &name, const PIIODevice *dev)
| Remove from filter with name "name" device or filter "dev".
bool | removeFilter (const PIString &name)
| Remove filter with name "name". Returns if filter was removed.
void | removeAllFilters ()
| Remove all filters from connection.
PIVector< PIPacketExtractor * > | filters () const
| Returns all filters of connection.
PIStringList | filterNames () const
| Returns all filter names of connection.
PIPacketExtractor * | filter (const PIString &name) const
| Returns PIPacketExtractor * assosiated with filter "name" or null if there is no such filter.
PIVector< PIIODevice * > | filterBoundedDevices (const PIString &name) const
| Returns all devices bounded to filter "name".
bool | addChannel (const PIString &name_from, const PIString &name_to)
| Add to connection channel from "name_from" to "name_to". More...
bool | addChannel (const PIString &name_from, const PIIODevice *dev_to)
| Add to connection channel from "name_from" to "dev_to".
bool | addChannel (const PIIODevice *dev_from, const PIString &name_to)
| Add to connection channel from "dev_from" to "name_to".
bool | addChannel (const PIIODevice *dev_from, const PIIODevice *dev_to)
| Add to connection channel from "dev_from" to "dev_to".
bool | removeChannel (const PIString &name_from, const PIString &name_to)
| Remove from connection channel from "name_from" to "name_to". More...
bool | removeChannel (const PIString &name_from, const PIIODevice *dev_to)
| Remove from connection channel from "name_from" to "dev_to".
bool | removeChannel (const PIIODevice *dev_from, const PIString &name_to)
| Remove from connection channel from "dev_from" to "name_to".
bool | removeChannel (const PIIODevice *dev_from, const PIIODevice *dev_to)
| Remove from connection channel from "dev_from" to "dev_to".
bool | removeChannel (const PIString &name_from)
| Remove from connection all channels from "name_from". More...
bool | removeChannel (const PIIODevice *dev_from)
| Remove from connection all channels from "dev_from".
void | removeAllChannels ()
| Remove from connection all channels.
PIVector< PIPair< PIString, PIString > > | channels () const
| Returns all channels of this connection as full pathes or filter names pair array (from, to)
void | addSender (const PIString &name, const PIString &full_path, float frequency, bool start=false)
| Add to connection sender with name "name" device with full path "full_path". More...
void | addSender (const PIString &name, const PIIODevice *dev, float frequency, bool start=false)
| Add to connection sender with name "name" device "dev".
bool | removeSender (const PIString &name, const PIString &full_path)
| Remove from sender with name "name" device with full path "full_path_name". More...
bool | removeSender (const PIString &name, const PIIODevice *dev)
| Remove from sender with name "name" device "dev".
bool | removeSender (const PIString &name)
| Remove sender with name "name", returns if sender was removed.
bool | setSenderFixedData (const PIString &name, const PIByteArray &data)
| Set sender "name" fixed send data "data", returns if sender exists.
bool | clearSenderFixedData (const PIString &name)
| Remove sender "name" fixed send data, returns if sender exists.
PIByteArray | senderFixedData (const PIString &name) const
| Returns sender "name" fixed send data.
float | senderFrequency (const PIString &name) const
| Returns sender "name" timer frequency, -1 if there is no such sender, or 0 if sender is not started yet.
void | removeAllSenders ()
| Remove from connection all senders.
void | startThreadedRead (const PIString &full_path)
| Start read thread of device with full path "full_path".
void | startThreadedRead (const PIIODevice *dev)
| Start read thread of device "dev".
void | startAllThreadedReads ()
| Start read threads of all Device pool device.
void | startSender (const PIString &name)
| Start sender "name" timer.
void | startAllSenders ()
| Start all senders timers.
void | start ()
| Start all read threads and senders.
void | stopThreadedRead (const PIString &full_path)
| Stop read thread of device with full path "full_path".
void | stopThreadedRead (const PIIODevice *dev)
| Stop read thread of device "dev".
void | stopAllThreadedReads ()
| Stop read threads of all Device pool device.
void | stopSender (const PIString &name)
| Stop sender "name" timer.
void | stopAllSenders ()
| Stop all senders timers.
void | stop ()
| Stop all read threads and senders.
bool | isEmpty () const
| Returns if there are no devices in this connection.
PIDiagnostics * | diagnostic (const PIString &full_path_name) const
| Returns PIDiagnostics * assosiated with device with full path "full_path_name", name "full_path_name" or filter "full_path_name".
PIDiagnostics * | diagnostic (const PIIODevice *dev) const
| Returns PIDiagnostics * assosiated with device or filter "dev".
int | writeByFullPath (const PIString &full_path, const PIByteArray &data)
| Write data "data" to device with full path "full_path" and returns result of write() function of device.
int | writeByName (const PIString &name, const PIByteArray &data)
| Write data "data" to device with name "name" and returns result of write() function of device.
int | write (PIIODevice *dev, const PIByteArray &data)
| Write data "data" to device "dev" and returns result of write() function of device.
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 PIVector< PIConnection * > | allConnections ()
| Returns all connections in application.
static PIVector< PIIODevice * > | allDevices ()
| Returns all devices in Device pool.
static bool | setFakeMode (bool yes)
| Set Device pool fake mode to "yes" and returns previous mode.
static bool | isFakeMode ()
| Returns if Device pool works in fake mode.
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 void | dataReceived (const PIString &from, const PIByteArray &data)
| Executes on data received from device with full path "from".
virtual void | packetReceived (const PIString &from, const PIByteArray &data)
| Executes on packet received from filter with name "from".
virtual bool | filterValidateHeader (const PIString &filter_name, uchar *src, uchar *rec, int size)
| Validate header "rec" with source header "src" and size "size", executes from filter "filter_name".
virtual bool | filterValidateFooter (const PIString &filter_name, uchar *src, uchar *rec, int size)
| Validate footer "rec" with source footer "src" and size "size", executes from filter "filter_name".
virtual bool | filterValidatePayload (const PIString &filter_name, uchar *rec, int size)
| Validate payload "rec" with size "size", executes from filter "filter_name".
virtual PIByteArray | senderData (const PIString &sender_name)
| You should returns data for sender "sender_name".
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...

## Events

void | dataReceivedEvent (const PIString &from, const PIByteArray &data)
| Raise on data received from device with full path "from".
void | packetReceivedEvent (const PIString &from, const PIByteArray &data)
| Raise on packet received from filter with name "from".
void | qualityChanged (const PIIODevice *dev, PIDiagnostics::Quality new_quality, PIDiagnostics::Quality old_quality)
| Raise on diagnostic quality of device "device" changed from "old_quality" to "new_quality".

## Additional Inherited Members

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".

## Detailed Description

Complex Input/Output point.

# Synopsis

PIConnection provides abstract layer over physical devices, filtering and connecting data streams. Each PIConnection works through Device Pool, so several PIConnections can read from single physical device. General scheme:

# Device pool concept

Device pool is static object, single for each application, which contains unique devices. Each PIConnection works with real devices through Device pool. Each device has assosiated thread for read and it can be started or stopped with PIConnection functions startThreadedRead() and stopThreadedRead().

# Filters

PIConnection filter is a PIPacketExtractor and assosiated array of devices or other filters. When read thread is successfully read from device this data can be passed to one or more filters. Each filter has name and filter names should be unique. You can use this name for access to PIPacketExtractor* with function filter(), or get array of assosiated devices and filters with function filterBoundedDevices(). One filter can receive data from several sources, and can be bounded to several filters.

# Diagnostics

PIConnection create PIDiagnostics for each device or filter. You can access to these objects with functions diagnostic().

# Senders

PIConnection can send data to devices with named timers ("senders"). You can create sender or add device to sender with function addSender(). Each sender has internal timer and every tick execute virtual function senderData(). Returns value of this function sended to bounded devices. You can assign fixed send data to sender with function setSenderFixedData(). In this case sender will NOT execute senderData(), but send assigned data.

# Configuration

You can create PIConnection from config file section or configure it later with function configureFromConfig(). Devices describes with its full pathes, for details see Creating devices by unambiguous string. Example:

Also PIConnection can create PIString with its configuration with function makeConfig(). This string can be directly inserted into the config file.

## Member Function Documentation

bool PIConnection::configureFromConfig | ( | const PIString & | config,
|  | const PIString & | name
| ) |  |

Configure connection from config file "config" from section "name". Returns if configuration was successful.

Warning: all devices, filters and channels removed before configure!

bool PIConnection::configureFromString | ( | PIString * | string,
|  | const PIString & | name
| ) |  |

Configure connection from config content "string" from section "name". Returns if configuration was successful.

Warning: all devices, filters and channels removed before configure!

PIIODevice * PIConnection::addDevice | ( | const PIString & | full_path,
|  | PIIODevice::DeviceMode | mode = `PIIODevice::ReadWrite`,
|  | bool | start = `false`
| ) |  |

Add device with full path "full_path", open mode "mode" to Device pool and connection.

Returns pointer to device or null if device can not be created. If "start" is true, read thread is started immediately. Else, you can start read thread with functions startThreadedRead() or startAllThreadedReads(). By default, read thread doesn`t start

bool PIConnection::removeDevice | ( | const PIString & | full_path | ) |

Remove device with full path "full_path" from connection.

Returns if device was removed. If there is no connection bounded to this device, it will be removed from Device pool

void PIConnection::removeAllDevices | ( |  | ) |

Remove all device from connection.

If there is no connection bounded to there devices, they removed from Device pool

PIPacketExtractor * PIConnection::addFilter | ( | const PIString & | name,
|  | const PIString & | full_path_name,
|  | PIPacketExtractor::SplitMode | mode = `PIPacketExtractor::None`
| ) |  |

Add filter with name "name" to device with full path "full_path_name" or filter "full_path_name".

If there is no filter with name "name", connection create new with split mode "mode" and bound to it device "full_path_name" or filter "full_path_name". If filter with name "name" already exists, device "full_path_name" or filter "full_path_name" add to this filter. This function returns PIPacketExtractor * assosiated with this filter
Attention! "mode" is altual olny if new filter was created!

bool PIConnection::removeFilter | ( | const PIString & | name,
|  | const PIString & | full_path_name
| ) |  |

Remove from filter with name "name" device with full path "full_path_name" or filter "full_path_name".

If there is no devices bounded to this filter, it will be removed. Returns if device was removed

bool PIConnection::addChannel | ( | const PIString & | name_from,
|  | const PIString & | name_to
| ) |  |

Add to connection channel from "name_from" to "name_to".

"name_from" and "name_to" can be full pathes of devices or filter names. Returns false if there if no such device or filter, else create channel and returns true

bool PIConnection::removeChannel | ( | const PIString & | name_from,
|  | const PIString & | name_to
| ) |  |

Remove from connection channel from "name_from" to "name_to".

"name_from" and "name_to" can be full pathes of devices or filter names. Returns false if there if no such device or filter, else remove channel and returns true

bool PIConnection::removeChannel | ( | const PIString & | name_from | ) |

Remove from connection all channels from "name_from".

"name_from" can be full path of device or filter name. Returns false if there if no such device or filter, else remove channels and returns true

void PIConnection::addSender | ( | const PIString & | name,
|  | const PIString & | full_path,
|  | float | frequency,
|  | bool | start = `false`
| ) |  |

Add to connection sender with name "name" device with full path "full_path".

If there is no sender with name "name", connection create new, bound to it device "full_path_name" and start sender timer with frequency "frequency". If sender with name "name" already exists, device "full_path_name" add to this sender If "start" is true, sender is started immediately. Else, you can start sender with functions startSender()
Attention! "frequency" is actual olny if new sender was created!

bool PIConnection::removeSender | ( | const PIString & | name,
|  | const PIString & | full_path
| ) |  |

Remove from sender with name "name" device with full path "full_path_name".

If there is no devices bounded to this sender, it will be removed. Returns if sender was removed