Base class for PdCom protocol handler. More...

#include <Process.h>

Inheritance diagram for PdCom::Process:

Classes
struct	SubscriptionInfo

Public Member Functions
	Process ()
	Constructor.

	Process (Process &&)=delete

	Process (Process const &)=delete

Process &	operator= (Process &&)=delete

Process &	operator= (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< SubscriptionInfo >	getActiveSubscriptions () 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...

Sasl *	getAuthManager () 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:

list(): list a directory; returns result in listReply()
find(): find a variable; returns result in findReply()
ping(): ping the server; returns result in pingReply()

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

message	Broadcast message.
attr	Xml 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

message	Message
attr	Attribute name, can be action or text.
time_ns	Time since epoch, will be filled in by the server.
user	Client 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

statistics The 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

path	path 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

variable Variable, 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

path	directory 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

variables	List of variables.
dirs	List 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

buf	data destination
count	buffer 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

buf	data to be sent
count	number 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:

/builds/etherlab.org/pdcom/include/pdcom5/Process.h

Classes

Public Member Functions

Protected Member Functions

Friends

Detailed Description

Constructor & Destructor Documentation

◆ ~Process()

Member Function Documentation

◆ alive()

◆ applicationName()

◆ asyncData()

◆ broadcast()

◆ broadcastReply()

◆ callPendingCallbacks()

◆ clientStatisticsReply()

◆ connected()

◆ find()

◆ findReply()

◆ flush()

◆ getAuthManager()

◆ getClientStatistics()

◆ hostname()

◆ list()

◆ listReply()

◆ pingReply()

◆ read()

◆ setAuthManager()

◆ setMessageManager()

◆ write()