PIConnection Class Reference

Routes data between shared devices, packet extractors, channels and periodic senders. More...

#include <piconnection.h>

Inheritance diagram for PIConnection:

Public Member Functions
	PIConnection (const PIString &name=PIString::fromAscii("connection"))
	Constructs an empty connection with name "name".
	PIConnection (const PIString &config, const PIString &name)
	Constructs a connection and immediately configures it from section "name" of file "config".
	PIConnection (PIString *string, const PIString &name)
	Constructs a connection and immediately configures it from section "name" stored in "string".
	~PIConnection ()
	Releases all bindings owned by this connection.
bool	configureFromConfig (const PIString &config, const PIString &name=PIString::fromAscii("connection"))
	Reconfigures the connection from section "name" of file "config". More...
bool	configureFromString (PIString *string, const PIString &name=PIString::fromAscii("connection"))
	Reconfigures the connection from section "name" stored in "string". More...
PIString	makeConfig () const
	Serializes current connection state into one configuration section.
PIIODevice *	addDevice (const PIString &full_path, PIIODevice::DeviceMode mode=PIIODevice::ReadWrite, bool start=false)
	Adds device "full_path" to the shared device pool and binds it to this connection. More...
void	setDeviceName (PIIODevice *dev, const PIString &name)
	Assigns alias "name" to device "dev" inside this connection.
PIStringList	deviceNames (const PIIODevice *dev) const
	Returns all aliases assigned to device "dev" in this connection.
bool	removeDevice (const PIString &full_path)
	Unbinds device "full_path" from this connection. More...
void	removeAllDevices ()
	Removes all devices currently bound to this connection. More...
PIIODevice *	deviceByFullPath (const PIString &full_path) const
	Returns bound device by normalized full path.
PIIODevice *	deviceByName (const PIString &name) const
	Returns bound device by alias.
PIVector< PIIODevice * >	boundedDevices () const
	Returns all devices currently bound to this connection.
PIPacketExtractor *	addFilter (const PIString &name, const PIString &full_path_name, PIPacketExtractor::SplitMode mode=PIPacketExtractor::None)
	Creates or reuses filter "name" and binds source "full_path_name" to it. More...
PIPacketExtractor *	addFilter (const PIString &name, const PIIODevice *dev, PIPacketExtractor::SplitMode mode=PIPacketExtractor::None)
	Creates or reuses filter "name" and binds device "dev" to it.
PIPacketExtractor *	addFilter (PIPacketExtractor *filter, const PIString &full_path_name)
	Binds existing extractor object "filter" to source "full_path_name".
PIPacketExtractor *	addFilter (PIPacketExtractor *filter, const PIIODevice *dev)
	Binds existing extractor object "filter" to device "dev".
bool	removeFilter (const PIString &name, const PIString &full_path_name)
	Unbinds source "full_path_name" from filter "name". More...
bool	removeFilter (const PIString &name, const PIIODevice *dev)
	Unbinds device or upstream filter "dev" from filter "name".
bool	removeFilter (const PIString &name)
	Removes filter "name" together with all its bindings.
void	removeAllFilters ()
	Removes all filters from this connection.
PIVector< PIPacketExtractor * >	filters () const
	Returns all filters owned by this connection.
PIStringList	filterNames () const
	Returns names of all filters owned by this connection.
PIPacketExtractor *	filter (const PIString &name) const
	Returns filter "name" or nullptr when it does not exist.
PIVector< PIIODevice * >	filterBoundedDevices (const PIString &name) const
	Returns all sources currently bound to filter "name".
bool	addChannel (const PIString &name_from, const PIString &name_to)
	Adds a routing channel from "name_from" to "name_to". More...
bool	addChannel (const PIString &name_from, const PIIODevice *dev_to)
	Adds a routing channel from "name_from" to device "dev_to".
bool	addChannel (const PIIODevice *dev_from, const PIString &name_to)
	Adds a routing channel from device "dev_from" to "name_to".
bool	addChannel (const PIIODevice *dev_from, const PIIODevice *dev_to)
	Adds a routing channel from device "dev_from" to device "dev_to".
bool	removeChannel (const PIString &name_from, const PIString &name_to)
	Removes routing channel from "name_from" to "name_to".
bool	removeChannel (const PIString &name_from, const PIIODevice *dev_to)
	Removes routing channel from "name_from" to device "dev_to".
bool	removeChannel (const PIIODevice *dev_from, const PIString &name_to)
	Removes routing channel from device "dev_from" to "name_to".
bool	removeChannel (const PIIODevice *dev_from, const PIIODevice *dev_to)
	Removes routing channel from device "dev_from" to device "dev_to".
bool	removeChannel (const PIString &name_from)
	Removes all outgoing channels starting from "name_from".
bool	removeChannel (const PIIODevice *dev_from)
	Removes all outgoing channels starting from device "dev_from".
void	removeAllChannels ()
	Removes all routing channels from this connection.
PIVector< PIPair< PIString, PIString > >	channels () const
	Returns all routing channels as source and destination pairs.
void	addSender (const PIString &name, const PIString &full_path_name, float frequency, bool start=false)
	Creates or reuses sender "name" and binds device "full_path_name" to it. More...
void	addSender (const PIString &name, const PIIODevice *dev, float frequency, bool start=false)
	Creates or reuses sender "name" and binds device "dev" to it.
bool	removeSender (const PIString &name, const PIString &full_path_name)
	Unbinds device "full_path_name" from sender "name". More...
bool	removeSender (const PIString &name, const PIIODevice *dev)
	Unbinds device "dev" from sender "name".
bool	removeSender (const PIString &name)
	Removes sender "name" together with its timer state.
bool	setSenderFixedData (const PIString &name, const PIByteArray &data)
	Assigns fixed payload "data" to sender "name".
bool	clearSenderFixedData (const PIString &name)
	Clears fixed payload for sender "name".
PIByteArray	senderFixedData (const PIString &name) const
	Returns fixed payload configured for sender "name".
float	senderFrequency (const PIString &name) const
	Returns sender timer frequency. More...
void	removeAllSenders ()
	Removes all senders from this connection.
void	startThreadedRead (const PIString &full_path_name)
	Starts threaded read for source "full_path_name".
void	startThreadedRead (const PIIODevice *dev)
	Starts threaded read for device "dev".
void	startAllThreadedReads ()
	Starts threaded read for all devices bound to the shared pool.
void	startSender (const PIString &name)
	Starts sender timer "name".
void	startAllSenders ()
	Starts all sender timers.
void	start ()
	Starts all threaded reads and all senders.
void	stopThreadedRead (const PIString &full_path_name)
	Stops threaded read for source "full_path_name".
void	stopThreadedRead (const PIIODevice *dev)
	Stops threaded read for device "dev".
void	stopAllThreadedReads ()
	Stops threaded read for all bound devices.
void	stopSender (const PIString &name)
	Stops sender timer "name".
void	stopAllSenders ()
	Stops all sender timers.
void	stop ()
	Stops all threaded reads and all senders.
void	destroy ()
	Stops the connection and removes all bound devices.
bool	isEmpty () const
	Returns whether the connection currently has no bound devices.
PIDiagnostics *	diagnostic (const PIString &full_path_name) const
	Returns diagnostics object for device or filter "full_path_name".
PIDiagnostics *	diagnostic (const PIIODevice *dev) const
	Returns diagnostics object associated with device or filter "dev".
int	writeByFullPath (const PIString &full_path, const PIByteArray &data)
	Writes "data" to device resolved by full path "full_path".
int	writeByName (const PIString &name, const PIByteArray &data)
	Writes "data" to device resolved by alias "name".
int	write (PIIODevice *dev, const PIByteArray &data)
	Writes "data" directly to device "dev".
Public Member Functions inherited from PIObject
	PIObject (const PIString &name=PIString())
	Constructs an object and initializes its name property.
virtual	~PIObject ()
	Destroys the object, raises deleted() and disconnects it from the event graph.
PIString	name () const
	Returns the name property of this object.
virtual const char *	className () const
	Returns the registered class name of this object.
virtual uint	classNameID () const
	Returns the hash of className().
virtual const char *	parentClassName () const
	Returns the registered parent class name, or an empty string for the root.
bool	debug () const
	Returns whether piCoutObj output is enabled for this object.
void	setName (const PIString &name)
	Sets the name property of this object.
void	setDebug (bool debug)
	Enables or disables piCoutObj output for this object.
PIVariant	property (const char *name) const
	Returns the property with name "name".
void	setProperty (const char *name, const PIVariant &value)
	Sets the property "name" to "value" and creates it if needed. More...
bool	isPropertyExists (const char *name) const
	Returns whether the property "name" exists.
void	setThreadSafe (bool yes)
	Enables or disables the internal object mutex during handler execution. More...
bool	isThreadSafe () const
	Returns whether the internal object mutex is enabled for handler execution.
bool	execute (const PIString &method, const PIVector< PIVariantSimple > &vl)
	Executes a registered method or handler method by name with the supplied arguments. More...
bool	execute (const PIString &method)
	Overload of execute() for a method without arguments.
bool	execute (const PIString &method, const PIVariantSimple &v0)
	Overload of execute() for one argument.
bool	execute (const PIString &method, const PIVariantSimple &v0, const PIVariantSimple &v1)
	Overload of execute() for two arguments.
bool	execute (const PIString &method, const PIVariantSimple &v0, const PIVariantSimple &v1, const PIVariantSimple &v2)
	Overload of execute() for three arguments.
bool	execute (const PIString &method, const PIVariantSimple &v0, const PIVariantSimple &v1, const PIVariantSimple &v2, const PIVariantSimple &v3)
	Overload of execute() for four arguments.
bool	executeQueued (PIObject *performer, const PIString &method, const PIVector< PIVariantSimple > &vl)
	Queues execution of a registered method on the performer object. More...
bool	executeQueued (PIObject *performer, const PIString &method)
	Overload of executeQueued() for a method without arguments.
bool	executeQueued (PIObject *performer, const PIString &method, const PIVariantSimple &v0)
	Overload of executeQueued() for one argument.
bool	executeQueued (PIObject *performer, const PIString &method, const PIVariantSimple &v0, const PIVariantSimple &v1)
	Overload of executeQueued() for two arguments.
bool	executeQueued (PIObject *performer, const PIString &method, const PIVariantSimple &v0, const PIVariantSimple &v1, const PIVariantSimple &v2)
	Overload of executeQueued() for three arguments.
bool	executeQueued (PIObject *performer, const PIString &method, const PIVariantSimple &v0, const PIVariantSimple &v1, const PIVariantSimple &v2, const PIVariantSimple &v3)
	Overload of executeQueued() for four arguments.
void	dump (const PIString &line_prefix=PIString()) const
	Dumps object diagnostics to the project output stream.
PIStringList	scopeList () const
	Returns the registered inheritance scope of this object, including its own class.
PIStringList	methodsEH () const
	Returns full signatures of all registered event and handler methods for this class scope.
bool	isMethodEHContains (const PIString &name) const
	Returns whether a registered event or handler method with this name exists.
PIString	methodEHArguments (const PIString &name) const
	Returns the comma-separated argument type list of a registered method.
PIString	methodEHFullFormat (const PIString &name) const
	Returns the full registered signature of a method.
PIString	methodEHFromAddr (const void *addr) const
	Returns the registered method name for the specified entry-point address.
void	piDisconnect (const PIString &sig, PIObject *dest, void *ev_h)
	Disconnects this source object from a specific destination handler for event "sig".
void	piDisconnect (const PIString &sig, PIObject *dest)
	Disconnects this source object from all connections of event "sig" to destination object "dest".
void	piDisconnect (const PIString &sig)
	Disconnects this source object from all connections of event "sig".
bool	isPIObject () const
	Returns whether this pointer still refers to a live PIObject instance.
template<typename T >
bool	isTypeOf () const
	Returns whether this object belongs to class "T" or one of its registered descendants.
template<typename T >
T *	cast () const
	Returns this object cast to "T" when isTypeOf<T>() succeeds, otherwise nullptr.
void	callQueuedEvents ()
	Executes all queued deliveries posted to this performer object.
bool	maybeCallQueuedEvents ()
	Executes queued deliveries only when this object was used as a performer. More...
void	deleteLater ()
	Schedules the object for deferred deletion. More...
void	deleted (PIObject *o)
	Raised immediately before object destruction. More...

Static Public Member Functions
static PIVector< PIConnection * >	allConnections ()
	Returns all currently alive PIConnection objects.
static PIVector< PIIODevice * >	allDevices ()
	Returns all devices currently stored in the shared device pool.
static bool	setFakeMode (bool yes)
	Enables or disables shared device-pool fake mode and returns previous state.
static bool	isFakeMode ()
	Returns whether the shared device pool works in fake mode.
Static Public Member Functions inherited from PIObject
static bool	execute (PIObject *o, const PIString &method, const PIVector< PIVariantSimple > &vl)
	Static convenience wrapper for execute().
static bool	execute (PIObject *o, const PIString &method)
	Static overload of execute() without arguments.
static bool	execute (PIObject *o, const PIString &method, const PIVariantSimple &v0)
	Static overload of execute() for one argument.
static bool	execute (PIObject *o, const PIString &method, const PIVariantSimple &v0, const PIVariantSimple &v1)
	Static overload of execute() for two arguments.
static bool	execute (PIObject *o, const PIString &method, const PIVariantSimple &v0, const PIVariantSimple &v1, const PIVariantSimple &v2)
	Static overload of execute() for three arguments.
static bool	execute (PIObject *o, const PIString &method, const PIVariantSimple &v0, const PIVariantSimple &v1, const PIVariantSimple &v2, const PIVariantSimple &v3)
	Static overload of execute() for four arguments.
static bool	executeQueued (PIObject *o, PIObject *performer, const PIString &method, const PIVector< PIVariantSimple > &vl)
	Static convenience wrapper for executeQueued().
static bool	executeQueued (PIObject *o, PIObject *performer, const PIString &method)
	Static overload of executeQueued() without arguments.
static bool	executeQueued (PIObject *o, PIObject *performer, const PIString &method, const PIVariantSimple &v0)
	Static overload of executeQueued() for one argument.
static bool	executeQueued (PIObject *o, PIObject *performer, const PIString &method, const PIVariantSimple &v0, const PIVariantSimple &v1)
	Static overload of executeQueued() for two arguments.
static bool	executeQueued (PIObject *o, PIObject *performer, const PIString &method, const PIVariantSimple &v0, const PIVariantSimple &v1, const PIVariantSimple &v2)
	Static overload of executeQueued() for three arguments.
static bool	executeQueued (PIObject *o, PIObject *performer, const PIString &method, const PIVariantSimple &v0, const PIVariantSimple &v1, const PIVariantSimple &v2, const PIVariantSimple &v3)
	Static overload of executeQueued() for four arguments.
static PIObject::Connection	piConnect (PIObject *src, const PIString &sig, PIObject *dest_o, void *dest, void *ev_h, void *e_h, int args, const char *loc)
	Low-level direct connection helper behind the legacy CONNECT* macros.
static PIObject::Connection	piConnectU (PIObject *src, const PIString &sig, PIObject *dest_o, void *dest, const PIString &hname, const char *loc, PIObject *performer=0)
	Low-level name-based connection helper behind CONNECTU() and CONNECTU_QUEUED().
static PIObject::Connection	piConnectLS (PIObject *src, const PIString &sig, std::function< void()> *f, const char *loc)
	Low-level helper that connects an event to a lambda or functor wrapper.
static void	piDisconnect (PIObject *src, const PIString &sig, PIObject *dest, void *ev_h)
	Disconnects source object "src" from a specific destination handler for event "sig".
static void	piDisconnect (PIObject *src, const PIString &sig, PIObject *dest)
	Disconnects source object "src" from all connections of event "sig" to destination object "dest".
static void	piDisconnect (PIObject *src, const PIString &sig)
	Disconnects source object "src" from all connections of event "sig".
static void	raiseEvent (PIObject *sender, const uint eventID)
	Internal event delivery helper for registered events without arguments.
template<typename T0 >
static void	raiseEvent (PIObject *sender, const uint eventID, const T0 &v0=T0())
	Internal event delivery helper for registered events with one argument.
template<typename T0 , typename T1 >
static void	raiseEvent (PIObject *sender, const uint eventID, const T0 &v0=T0(), const T1 &v1=T1())
	Internal event delivery helper for registered events with two arguments.
template<typename T0 , typename T1 , typename T2 >
static void	raiseEvent (PIObject *sender, const uint eventID, const T0 &v0=T0(), const T1 &v1=T1(), const T2 &v2=T2())
	Internal event delivery helper for registered events with three arguments.
template<typename T0 , typename T1 , typename T2 , typename T3 >
static void	raiseEvent (PIObject *sender, const uint eventID, const T0 &v0=T0(), const T1 &v1=T1(), const T2 &v2=T2(), const T3 &v3=T3())
	Internal event delivery helper for registered events with four arguments.
static PIObject *	findByName (const PIString &name)
	Returns the first live object with name "name", or nullptr.
static bool	isPIObject (const PIObject *o)
	Returns whether "o" points to a live PIObject instance.
static bool	isPIObject (const void *o)
	Overload of isPIObject() for an untyped pointer.
template<typename T >
static bool	isTypeOf (const PIObject *o)
	Returns whether "o" belongs to class "T" or one of its registered descendants.
template<typename T >
static bool	isTypeOf (const void *o)
	Overload of isTypeOf() for an untyped pointer.
static PIString	simplifyType (const char *a, bool readable=true)
	Simplifies a C++ type spelling for registered-method metadata.

Protected Member Functions
virtual void	dataReceived (const PIString &from, const PIByteArray &data)
	Called after raw data is received from source "from".
virtual void	packetReceived (const PIString &from, const PIByteArray &data)
	Called after filter "from" produces a packet.
virtual PIByteArray	senderData (const PIString &sender_name)
	Returns dynamic payload for sender "sender_name".
Protected Member Functions inherited from PIObject
PIObject *	emitter () const
	Returns the source object that raised the current event. More...
virtual void	propertyChanged (const char *name)
	Virtual method called after property "name" has been changed by setProperty().

Events
void	dataReceivedEvent (const PIString &from, const PIByteArray &data)
	Emitted when raw data is received from source "from".
void	packetReceivedEvent (const PIString &from, const PIByteArray &data)
	Emitted when filter "from" produces a packet.
void	qualityChanged (const PIIODevice *dev, PIDiagnostics::Quality new_quality, PIDiagnostics::Quality old_quality)
	Emitted when diagnostics quality of "device" changes.

Additional Inherited Members
Related Functions inherited from PIObject
#define	piCoutObj
	Macro used for conditional (piDebug && PIObject::debug()) output to PICout(StdOut) for subclasses of PIObject.
#define	piCerrObj
	Macro used for conditional (piDebug && PIObject::debug()) output to PICout(StdErr) for subclasses of PIObject.
#define	PIOBJECT(name)
	Put this macro inside a direct PIObject subclass definition to enable registered events, event handlers and class metadata.
#define	PIOBJECT_SUBCLASS(name, parent)
	Put this macro inside a PIObject subclass definition to inherit registered methods and class scope from "parent".
#define	EVENT_HANDLER0(ret, name)   ret name()
	Declare a registered event handler method with signature ret name().
#define	EVENT_HANDLER1(ret, name, type0, var0)   ret name(type0 var0)
	Declare a registered event handler method with one argument.
#define	EVENT_HANDLER2(ret, name, type0, var0, type1, var1)   ret name(type0 var0, type1 var1)
	Declare a registered event handler method with two arguments.
#define	EVENT_HANDLER3(ret, name, type0, var0, type1, var1, type2, var2)   ret name(type0 var0, type1 var1, type2 var2)
	Declare a registered event handler method with three arguments.
#define	EVENT_HANDLER4(ret, name, type0, var0, type1, var1, type2, var2, type3, var3)    ret name(type0 var0, type1 var1, type2 var2, type3 var3)
	Declare a registered event handler method with four arguments.
#define	EVENT_HANDLER   EVENT_HANDLER0
	Synonym of EVENT_HANDLER0.
#define	EVENT_VHANDLER0(ret, name)   virtual ret name()
	Declare a virtual registered event handler method with signature virtual ret name().
#define	EVENT_VHANDLER1(ret, name, type0, var0)   virtual ret name(type0 var0)
	Declare a virtual registered event handler method with one argument.
#define	EVENT_VHANDLER2(ret, name, type0, var0, type1, var1)   virtual ret name(type0 var0, type1 var1)
	Declare a virtual registered event handler method with two arguments.
#define	EVENT_VHANDLER3(ret, name, type0, var0, type1, var1, type2, var2)   virtual ret name(type0 var0, type1 var1, type2 var2)
	Declare a virtual registered event handler method with three arguments.
#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 a virtual registered event handler method with four arguments.
#define	EVENT_VHANDLER   EVENT_VHANDLER0
	Synonym of EVENT_VHANDLER0.
#define	EVENT0(name)   void name();
	Declare an event method with no arguments.
#define	EVENT1(name, type0, var0)   void name(type0 var0);
	Declare an event method with one argument.
#define	EVENT2(name, type0, var0, type1, var1)   void name(type0 var0, type1 var1);
	Declare an event method with two arguments.
#define	EVENT3(name, type0, var0, type1, var1, type2, var2)   void name(type0 var0, type1 var1, type2 var2);
	Declare an event method with three arguments.
#define	EVENT4(name, type0, var0, type1, var1, type2, var2, type3, var3)   void name(type0 var0, type1 var1, type2 var2, type3 var3);
	Declare an event method with four arguments.
#define	EVENT   EVENT0
	Synonym of EVENT0.
#define	RAISE_EVENT0(src, event)
	Compatibility helper that raises event "event" on source object "src".
#define	RAISE_EVENT1(src, event, v0)
	Compatibility helper that raises event "event" with one argument.
#define	RAISE_EVENT2(src, event, v0, v1)
	Compatibility helper that raises event "event" with two arguments.
#define	RAISE_EVENT3(src, event, v0, v1, v2)
	Compatibility helper that raises event "event" with three arguments.
#define	RAISE_EVENT4(src, event, v0, v1, v2, v3)
	Compatibility helper that raises event "event" with four arguments.
#define	CONNECTU(src, event, dest, handler)
	Connect event "event" from object "src" to event handler or event "handler" of object "dest". More...
#define	CONNECTU_QUEUED(src, event, dest, handler, performer)
	Connect event "event" from object "src" to event handler or event "handler" of object "dest". More...
#define	CONNECTL(src, event, functor)
	Connect event "event" from object "src" to lambda-expression "functor". More...
#define	CONNECT0(ret, src, event, dest, handler)
	Legacy compatibility helper that connects an event to a registered handler with compile-time signature spelling. More...
#define	CONNECT1(ret, type0, src, event, dest, handler)
	Legacy compatibility helper for a one-argument registered event or handler. More...
#define	CONNECT2(ret, type0, type1, src, event, dest, handler)
	Legacy compatibility helper for a two-argument registered event or handler. More...
#define	CONNECT3(ret, type0, type1, type2, src, event, dest, handler)
	Legacy compatibility helper for a three-argument registered event or handler. More...
#define	CONNECT4(ret, type0, type1, type2, type3, src, event, dest, handler)
	Legacy compatibility helper for a four-argument registered event or handler. More...
#define	CONNECT   CONNECT0
	Synonym of CONNECT0. More...
#define	WEAK_CONNECT0(ret, src, event, dest, handler)
	Legacy compatibility helper that skips source method verification. More...
#define	WEAK_CONNECT1(ret, type0, src, event, dest, handler)
	Legacy compatibility helper that skips source method verification for one argument. More...
#define	WEAK_CONNECT2(ret, type0, type1, src, event, dest, handler)
	Legacy compatibility helper that skips source method verification for two arguments. More...
#define	WEAK_CONNECT3(ret, type0, type1, type2, src, event, dest, handler)
	Legacy compatibility helper that skips source method verification for three arguments. More...
#define	WEAK_CONNECT4(ret, type0, type1, type2, type3, src, event, dest, handler)
	Legacy compatibility helper that skips source method verification for four arguments. More...
#define	WEAK_CONNECT   WEAK_CONNECT0
	Synonym of WEAK_CONNECT0. More...
#define	DISCONNECT0(ret, src, event, dest, handler)
	Disconnect a registered event from a registered event handler.
#define	DISCONNECT1(ret, type0, src, event, dest, handler)
	Disconnect a one-argument registered event from a registered event handler.
#define	DISCONNECT2(ret, type0, type1, src, event, dest, handler)
	Disconnect a two-argument registered event from a registered event handler.
#define	DISCONNECT3(ret, type0, type1, type2, src, event, dest, handler)
	Disconnect a three-argument registered event from a registered event handler.
#define	DISCONNECT4(ret, type0, type1, type2, type3, src, event, dest, handler)
	Disconnect a four-argument registered event from a registered event handler.
#define	DISCONNECT   DISCONNECT0
	Synonym of DISCONNECT0.
#define	HANDLER(handler)
	Low-level helper that expands to the registered handler entry point.

Detailed Description

Routes data between shared devices, packet extractors, channels and periodic senders.

Complex Input/Output point.

PIConnection uses a process-wide device pool so several connections can share the same physical device. Raw device data may be forwarded into named filters, routed through channels, monitored with diagnostics and emitted by periodic senders.

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

configureFromConfig()

bool PIConnection::configureFromConfig	(	const PIString &	config,
		const PIString &	name = PIString::fromAscii ("connection")
	)

Reconfigures the connection from section "name" of file "config".

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

configureFromString()

bool PIConnection::configureFromString	(	PIString *	string,
		const PIString &	name = PIString::fromAscii ("connection")
	)

Reconfigures the connection from section "name" stored in "string".

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

addDevice()

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

Adds device "full_path" to the shared device pool and binds it to this connection.

Returns the shared device instance or nullptr when creation fails. When "start" is true, threaded read starts immediately.

removeDevice()

bool PIConnection::removeDevice

(

const PIString &

full_path

)

Unbinds device "full_path" from this connection.

The shared device object is deleted from the pool only when no connections still use it.

removeAllDevices()

void PIConnection::removeAllDevices

(

)

Removes all devices currently bound to this connection.

Devices remain in the shared pool while they are still referenced by other connections.

addFilter()

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

Creates or reuses filter "name" and binds source "full_path_name" to it.

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.

Note

Attention! "mode" is altual olny if new filter was created!

See also

PIPacketExtractor

removeFilter()

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

Unbinds source "full_path_name" from filter "name".

Removes the filter itself when it no longer has any bound sources.

addChannel()

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

Adds a routing channel from "name_from" to "name_to".

Both endpoints may reference a device full path, a device alias or a filter name.

addSender()

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

Creates or reuses sender "name" and binds device "full_path_name" to it.

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

Note

Attention! "frequency" is actual olny if new sender was created!

See also

startSender()

removeSender()

bool PIConnection::removeSender	(	const PIString &	name,
		const PIString &	full_path_name
	)

Unbinds device "full_path_name" from sender "name".

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

senderFrequency()

float PIConnection::senderFrequency

(

const PIString &

name

)

const

Returns sender timer frequency.

Returns -1 when the sender does not exist and 0 when it exists but is not running.