PdCom  5.3
Process data communication client
Classes | Public Member Functions | Protected Member Functions | Friends | List of all members
PdCom::Process Class Referenceabstract

Base class for PdCom protocol handler. More...

#include <Process.h>

Inheritance diagram for PdCom::Process:
PdCom::SecureProcess

Classes

struct  SubscriptionInfo
 

Public Member Functions

 Process ()
 Constructor.
 
 Process (Process &&)=delete
 
 Process (Process const &)=delete
 
Processoperator= (Process &&)=delete
 
Processoperator= (Process const &)=delete
 
std::string name () const
 Remote process name string.
 
std::string version () const
 Remote process version string.
 
void asyncData ()
 Library entry point for new data. More...
 
void callPendingCallbacks ()
 Call delayed callbacks. More...
 
void broadcast (const std::string &message, const std::string &attr="text")
 Send a broadcast message to the server and other clients. More...
 
std::vector< SubscriptionInfogetActiveSubscriptions () const
 

Protected Member Functions

virtual ~Process ()
 Destructor. More...
 
void reset ()
 Reset communications and clean up internal buffers.
 
virtual std::string applicationName () const
 Name of application user application. More...
 
virtual std::string hostname () const
 Host name of remote server. More...
 
virtual int read (char *buf, int count)=0
 Read data from server. More...
 
virtual void write (const char *buf, size_t count)=0
 Write data to server. More...
 
virtual void flush ()=0
 Flush unsent data in output buffer. More...
 
virtual void connected ()=0
 Protocol initialization completed. More...
 
bool list (const std::string &path="")
 List a directory path. More...
 
virtual void listReply (std::vector< Variable > variables, std::vector< std::string > dirs)
 Reply to list() call. More...
 
bool find (const std::string &path)
 Find a variable with a corresponding path. More...
 
virtual void findReply (const Variable &variable)
 Reply to find() More...
 
void getClientStatistics ()
 Request client statistics from the server. More...
 
virtual void clientStatisticsReply (std::vector< ClientStatistics > statistics)
 Reply for getClientStatistics(). More...
 
void ping ()
 Ping server.
 
virtual void pingReply ()
 Ping reply. More...
 
virtual bool alive ()
 Test from process whether client is alive. More...
 
void setAuthManager (Sasl *)
 Register a SASL handler. More...
 
SaslgetAuthManager () const
 Get the current SASL handler. More...
 
void setMessageManager (MessageManagerBase *)
 Register a Message handler. More...
 
virtual void broadcastReply (const std::string &message, const std::string &attr, std::chrono::nanoseconds time_ns, const std::string &user)
 Recieve a broadcast message from other clients. More...
 

Friends

class impl::Process
 
class SecureProcess
 

Detailed Description

Base class for PdCom protocol handler.

This is the base class to interact with real time process server. The PdCom protocol ist implemented using this class.

For socket input and output, the library completely relies on a derived class where read(), write(), flush() and connected() methods are reimplemented.

When data is available for reading, call asyncData() which in turn calls the reimplemented read() method.

When the protocol is initialized, the reimplemented connected() method is called.

After connected(), the following commands can be issued:

All these commands are non-blocking asynchronous calls and either return the result immediately with the corresponding reply methods or issue a command to the server using excessive (!) calls to write(). Data should be written to a buffer to optimize network communication. To flush the buffer to wire, flush() is issued by the library when required.

The server may query presence of the user by issuing an alive() call. Using this call, certain actions could be undertaken by the server if the user is not active any more.

Examples:
advanced_example.cpp, and sasl_example.cpp.

Constructor & Destructor Documentation

◆ ~Process()

virtual PdCom::Process::~Process ( )
protectedvirtual

Destructor.

The destructor cleans up all internally allocated structures

Member Function Documentation

◆ alive()

virtual bool PdCom::Process::alive ( )
inlineprotectedvirtual

Test from process whether client is alive.

In some cases the server may want to know whether the client is still alive. Default implementation is to return true. Reimplement this if you wish to control presence

Returns
true to indicate user presence

◆ applicationName()

virtual std::string PdCom::Process::applicationName ( ) const
inlineprotectedvirtual

Name of application user application.

The application name is transferred to the server to be able to identify the clients more easily.

Returns
a descriptive name of your application.

◆ asyncData()

void PdCom::Process::asyncData ( )

Library entry point for new data.

Calling this method tells the library that new data has arrived from the server and is waiting to be processed.

The library prepares an input buffer and then calls the reimplemented read() virtual method to read incoming data.

This method can throw many exceptions, especially protocol_error and all exceptions which are thrown in the callbacks.

◆ broadcast()

void PdCom::Process::broadcast ( const std::string &  message,
const std::string &  attr = "text" 
)

Send a broadcast message to the server and other clients.

Parameters
messageBroadcast message.
attrXml tag name, can be text or action.

◆ broadcastReply()

virtual void PdCom::Process::broadcastReply ( const std::string &  message,
const std::string &  attr,
std::chrono::nanoseconds  time_ns,
const std::string &  user 
)
protectedvirtual

Recieve a broadcast message from other clients.

time_ns and user will be filled in by the server. If the sending client is not authenticated, user will be anonymous.

Parameters
messageMessage
attrAttribute name, can be action or text.
time_nsTime since epoch, will be filled in by the server.
userClient which sent the broadcast, will be filled in by the server.

◆ callPendingCallbacks()

void PdCom::Process::callPendingCallbacks ( )

Call delayed callbacks.

This method is used to call queued callbacks, for example Subscriber::stateChanged() after a Subscription has been created. It is also called twice by asyncData(), so usually you don't have to bother with it.

◆ clientStatisticsReply()

virtual void PdCom::Process::clientStatisticsReply ( std::vector< ClientStatistics statistics)
protectedvirtual

Reply for getClientStatistics().

Parameters
statisticsThe stats for all connected clients.

◆ connected()

virtual void PdCom::Process::connected ( )
protectedpure virtual

Protocol initialization completed.

This is a signal emitted by the library to indicate that protocol initialization has been completed and that library operations can be performed thereafter.

Reimplement this method to get the signal.

Absolutely NO process operations other than asyncData(), and Sasl::login() (and then only due to a previous loginReply() are permitted before this signal has been emitted.

Examples:
advanced_example.cpp, gnutls_example.cpp, and sasl_example.cpp.

◆ find()

bool PdCom::Process::find ( const std::string &  path)
protected

Find a variable with a corresponding path.

If the path search is known (be it successful or unsuccessful), the variable is returned in the call to the reimplemented virtual findReply() method immediately and the method returns true;

If unsuccessful, the command is sent to the server to and the call returns immediately with false. Later on during asyncData(), findReply() is called when the server's reply is processed.

Parameters
pathpath of variable to find
Returns
true if path is found immediately (cached)

◆ findReply()

virtual void PdCom::Process::findReply ( const Variable variable)
protectedvirtual

Reply to find()

This virtual method is called within the context of asyncData() when the server's reply to a variable discovery is processed.

findReply()ies are called in strict order of find()

Parameters
variableVariable, empty if variable was not found.
Examples:
advanced_example.cpp.

◆ flush()

virtual void PdCom::Process::flush ( )
protectedpure virtual

Flush unsent data in output buffer.

Reimplement this method to flush data in the output buffer.

This method tells the user that it is time to flush the output buffer to the wire. The library only expects that data is sent to the server within this call.

Essentially this method is a little wrapper around your socket's fflush() function:

void MyProcess::flush()
{
if (::fflush(this->socket_file)) {
// react to errors
}
}
Examples:
advanced_example.cpp, and sasl_example.cpp.

◆ getAuthManager()

Sasl* PdCom::Process::getAuthManager ( ) const
protected

Get the current SASL handler.

Returns
The current SASL handler, may be NULL.

◆ getClientStatistics()

void PdCom::Process::getClientStatistics ( )
protected

Request client statistics from the server.

Override clientStatisticsReply() to process the reply.

◆ hostname()

virtual std::string PdCom::Process::hostname ( ) const
inlineprotectedvirtual

Host name of remote server.

Reimplement this method to return the remote server host name this library connects to. This is especially important in multi-hosted TLS environments, where multiple hosts resolv to the same IP address. TLS needs to know the original server host name.

Returns
server host name

◆ list()

bool PdCom::Process::list ( const std::string &  path = "")
protected

List a directory path.

A process command to return all variables and directories within a directory path. The path parameter has typical unix character, with forward slashes '/' separating directories.

listReply() must be reimplemented to receive the reply to this call.

If the directory is cached (for instance a previous call to a similar path, or an entire server listing has been performed), listReply() is called within the context of this call and no server query is performed.

If uncached, the library sends a server query and returns immediately. Later on during asyncData(), the virtual method listReply(), is called when the server's reply is processed.

As a special case, an empty string (std::string()) for path will let the server list all its variables in one go. This possibility must be used with caution, as it can cause heavy network traffic.

Parameters
pathdirectory path
Returns
true if the path was cached
Examples:
gnutls_example.cpp, and sasl_example.cpp.

◆ listReply()

virtual void PdCom::Process::listReply ( std::vector< Variable variables,
std::vector< std::string >  dirs 
)
protectedvirtual

Reply to list() call.

You must reimplement this method to receive replies to list() calls.

Note that a variable can have the same path as a directory! An example is a vector variable with atomized elements.

Replies are in strict order of list() calls.

Parameters
variablesList of variables.
dirsList of directories.
Examples:
gnutls_example.cpp, and sasl_example.cpp.

◆ pingReply()

virtual void PdCom::Process::pingReply ( )
inlineprotectedvirtual

Ping reply.

You must reimplement this method to receive the reply to a ping() call.

◆ read()

virtual int PdCom::Process::read ( char *  buf,
int  count 
)
protectedpure virtual

Read data from server.

Reimplement this method to transfer data from the server to the library. This method is called within the call to asyncData().

Essentially this method is a little wrapper around your socket's read() function:

int MyProcess::read(char *buf, size_t count)
{
return ::read(this->socket_fd, buf, count);
}

The method must return the number of bytes read, which may of coarse be less than count or even 0. Return values of <= 0 are not interpreted by the protocol handler.

Parameters
bufdata destination
countbuffer size
Returns
number of bytes read, 0 on connection close, -EAGAIN on when no data is available or <0 on error.
Examples:
advanced_example.cpp, gnutls_example.cpp, and sasl_example.cpp.

◆ setAuthManager()

void PdCom::Process::setAuthManager ( Sasl )
protected

Register a SASL handler.

A previous registered handler will be unregistered. Note that the registered handler has to outlive the process. Passing a nullptr will unregister the handler.

Examples:
sasl_example.cpp.

◆ setMessageManager()

void PdCom::Process::setMessageManager ( MessageManagerBase )
protected

Register a Message handler.

A previous registered handler will be unregistered. Note that the registered handler has to outlive the process. Passing a nullptr will unregister the handler.

◆ write()

virtual void PdCom::Process::write ( const char *  buf,
size_t  count 
)
protectedpure virtual

Write data to server.

Reimplement this method to transfer data from the library to the server. This method is called when any library operation requires data to be sent to the server.

Note: the library makes many calls to write(), so use buffered output otherwise you're in for performance problems!

Essentially this method is a little wrapper around your socket's write() function:

void MyProcess::write(const char *buf, size_t count)
{
if (count != ::fwrite(buf, 1, count, this->socket_file)) {
// react to errors, set flags, etc
}
}

Note: the library does not have an internal buffer and expects that all data is sent. If your implementation might send less than count, it is your responsibility to buffer the data and send it later.

Parameters
bufdata to be sent
countnumber of bytes to send
Examples:
advanced_example.cpp, gnutls_example.cpp, and sasl_example.cpp.

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