#include <IConnect.h>

Inheritance diagram for IConnect:

Collaboration diagram for IConnect:

Public Member Functions
	IConnect (const string &configurationname)
virtual void	SetupLogger (const string &parentlogger, const string &spec="Comms")
	Setupp the Logger.
virtual	~IConnect ()
	Desctructor.
virtual bool	Connect (ICommand *callback=NULL)=0
virtual bool	Disconnect (ICommand *callback=NULL)=0
virtual bool	Send (const char tosend, unsigned int len, ICommand callback=NULL)=0
virtual bool	Send (const string &tosend, ICommand *callback=NULL)
virtual bool	Receive (ICommand *cmd)=0
virtual bool	CheckConfig (void)=0
virtual bool	IsConnected (void)
Protected Member Functions
virtual void	_main (void)
virtual void	StartWorkerThread (void)
	Start the Worker thread.
virtual bool	IsTermRequested (void)
	Check if termination of the worker thread has been requested.
virtual bool	IsThreadRunning (void)
Protected Attributes
string	ConfigurationPath
	Storage for the Configuration Path to extract settings.
ILogger	logger
boost::thread	workerthread
	ASYNC OPERATION.
boost::recursive_mutex	mutex
	Mutex to protect data.

Detailed Description

Interface for all communication classes

This Interface is the API for all concrete comm methods. The class is abstract, so it cannot be instanciated by itself.

Anyway, it is intended, that the class is only created by the IConnectFactory.

Synchronous and asyncronous operations

(Prelimiary, as currently in developement) FIXME Update docs when ready! When the asynch operations are implemented, synchronous operations should be depreciated, as the might infer with the timings of other inverters.

The IConnect methods can be used synchronous and asyncronous,( if the communication classes support this. But the plans are to make these all async-capable)

The customers of the IConnect classes can choose if they want to use the async or sync methods by specifying optional ICommand arguments. If they are obmitted (and therefore defaulting to NULL pointers) the command will use synchronous methods, so returning the result directly (boolean). The booleans are used because of how solarpowerlog developed

If the asynchronous commands are used, the result is placed into the ICommand-data void pointer, which has to be casted to an int. Here "errno" conventions are used. Negative numbers tell that an error occured, zero means success. Please see the documentation of the methods for expected error codes.

Note:: A convention developed during implemention of the first async classes, is, when programming methods, only return errors if the object cannot perform its function. So, for example, if the call requires the object in a specific state, only return an error if this state cannot be easily reache. For example, if Connect()-ing, don't return an error when already connected, just return silently success.

ICommand ownership As usual, ICommands that are submitted to this class, will be owned by this class. So do not delete them, as they will be automatically deleted by the WorkScheduler.

Note:: If Async operations would be overkill, because the result is immediatly known, one can also implement the async ops as synchronous as long as it uses the async notification methods.

Definition at line 118 of file IConnect.h.

Constructor & Destructor Documentation

IConnect::IConnect ( const string & configurationname )

Constructor.

The constructor gets the configuration path to be used to extract its configuration.

Definition at line 43 of file IConnect.cpp.

IConnect::~IConnect ( ) [virtual]

Desctructor.

Definition at line 56 of file IConnect.cpp.

Member Function Documentation

virtual void IConnect::_main ( void ) [inline, protected, virtual]

function of the thread.

Note:: : if overridden, the overriding function has to call this one right before exiting!

Reimplemented in CConnectDummy.

Definition at line 279 of file IConnect.h.

virtual bool IConnect::CheckConfig ( void ) [pure virtual]

Check the configuration for validty. Retrurn false on config errors. (program will abort then!)

Implemented in CConnectDummy.

virtual bool IConnect::Connect ( ICommand * callback = NULL ) [pure virtual]

Connect to something NOTE: Needed to be overriden! ALWAYS Open in a NON_BLOCK way, or implement a worker thread Connect to the target, so comms can happen.

The target and the settings are retrieved out of the configuration.

SYNCHRONOUNS OPERATION: Connect and return if it has succeeded. May block, but should be limited to some seconds.

ASYNCHRONOUS OPERATION: Connect async and use the ICommand to tell the result.

Note:: If a connection is already up, return "true" or success (async); On asynch operation, the return can be ignored.; If Async operations would be overkill, because the result is immediatly known, one can also implement the async ops as synchronous as long as it uses the async notification methods.

Implemented in CConnectDummy.

virtual bool IConnect::Disconnect ( ICommand * callback = NULL ) [pure virtual]

Tear down the connection.

SYNCHRONOUNS OPERATION: Just Disconnect. If this could fail, return false on failure, else true.

ASYNCHRONOUS OPERATION: Disconnect async and use the ICommand to tell the result.

Note:: If a connection is already up, return "true" or success (async)

Returns:: true on successful reading (synchronous operation only), will always return true on asynch operation, as error notification solely to be done by the supplied cmd.

ASYNCHRNOUNS ERROR CODES. The result will be placed in the supplied ICommand's data field.

The value will be usually EIO, as one hs to ask himself: What can go wrong here?

Note:: Try hard to get the comm into a known state, where connect will be able to recover, or reconnection might be futile as recovery strategy.

Implemented in CConnectDummy.

virtual bool IConnect::IsConnected ( void ) [inline, virtual]

Check if we believe the connection is still active Note: if the concrete implementation cannot tell, it should always return true, as the default implementaion does. (the inverter class has to do some kind of timeout-handling anyway)

Definition at line 254 of file IConnect.h.

bool IConnect::IsTermRequested ( void ) [protected, virtual]

Check if termination of the worker thread has been requested.

Definition at line 79 of file IConnect.cpp.

bool IConnect::IsThreadRunning ( void ) [protected, virtual]

Check if thread is running

Note:: this does not check if the thread has crashed, only if it has not self-terminated or never started..

Definition at line 87 of file IConnect.cpp.

virtual bool IConnect::Receive ( ICommand * cmd ) [pure virtual]

Receive data from connection and place it into a std::string

Try to receive data from the other end and place everything readed into the supplied std::string.

Parameters:

wheretoplace	object for data storage.
cmd	ICommand to be used for async notification.

Note:: on async operation, where to place has to be valid until the notification has been received.; When the read operation has failed, the contents of the string-object is undefined. (The class might alter it, even when the read fails.

Returns:: true on successful reading (synchronous operation only), will always return true on asynch operation, as error notification solely to be done by the supplied cmd.

ASYNCHRONOUS ERRORS: The implementation might use errors out of error.h to specify the cause of the error.

These error values are defined in their meaning:

EIO I/O Error on the comms. Reason unknown or something unexpected happended. (one should close and reopen the connection)

ETIMEDOUT Read request timed out: No bytes received during configured timeout.

ENOTCONN Connection went down, e.g. eof received.

Implemented in CConnectDummy.

virtual bool IConnect::Send	(	const char *	tosend,
		unsigned int	len,
		ICommand *	callback = `NULL`
	)		`[pure virtual]`

Send a array of characters (can be used as binary transport, too)

Warning:: not all classes might understand binary transport. Check the concrete implmentation for details!

Parameters:

tosend	what to send
len	how many bytes

Returns:: true on success, false on error.

Implemented in CConnectDummy.

virtual bool IConnect::Send	(	const string &	tosend,
		ICommand *	callback = `NULL`
	)		`[inline, virtual]`

Send a string

Note:: Standard implementation only wraps to above Send-binray.

Parameters:

tosend std::string to send

Returns:: true on success, false on error. Override for better performance!

Definition at line 202 of file IConnect.h.

void IConnect::SetupLogger	(	const string &	parentlogger,
		const string &	spec = `"Comms"`
	)		`[virtual]`

Setupp the Logger.

Definition at line 51 of file IConnect.cpp.

void IConnect::StartWorkerThread ( void ) [protected, virtual]

Start the Worker thread.

Definition at line 69 of file IConnect.cpp.

Here is the call graph for this function:

Member Data Documentation

string IConnect::ConfigurationPath [protected]

Storage for the Configuration Path to extract settings.

Definition at line 261 of file IConnect.h.

ILogger IConnect::logger [protected]

Associated logger.

Note:: : By default, it will attached to the root logger. If unwanted, use the SetupLogger() call. (As IInverterBase derived classes do)

Definition at line 266 of file IConnect.h.

boost::recursive_mutex IConnect::mutex [protected]

Mutex to protect data.

Definition at line 274 of file IConnect.h.

boost::thread IConnect::workerthread [protected]

ASYNC OPERATION.

Thread

Definition at line 271 of file IConnect.h.

The documentation for this class was generated from the following files:

/home/tobi/workspace/solarpowerlog/src/Connections/interfaces/IConnect.h
/home/tobi/workspace/solarpowerlog/src/Connections/interfaces/IConnect.cpp

Public Member Functions

Protected Member Functions

Protected Attributes

Detailed Description

Constructor & Destructor Documentation

Member Function Documentation

Member Data Documentation