REC RPC library
Public Slots | Signals | Public Member Functions | Static Public Attributes | Protected Member Functions | List of all members
rec::rpc::Client Class Reference

RPC client base class. More...

#include <rec_rpc_Client.h>

Inheritance diagram for rec::rpc::Client:
Inheritance graph
[legend]
Collaboration diagram for rec::rpc::Client:
Collaboration graph
[legend]

Public Slots

void setName (const QString &name)
 Set the Client's name. Default is the application name. More...
 
void setMultiThreadedSerializationEnabled (bool enabled)
 Enable or disable multi-threaded serialization. Disabled by default. More...
 
void setLocalIPCEnabled (bool enabled)
 Enable or Disable local IPC. Enabled by default. More...
 
void setAddress (const QString &address)
 Set the network address of the RPC server. More...
 
void setExpectedGreeting (const QString &greeting)
 Set the greeting message that is expected from the server when connecting. More...
 
void setMsTimeout (unsigned int timeout)
 Set the timeout for RPC requests. More...
 
void setAutoReconnectEnabled (bool enable, unsigned int ms=200)
 Enable/disable automatic reconnection. More...
 
void connectToServer (unsigned int msTimeout=DefaultTimeout)
 Connect to a RPC server. More...
 
void disconnectFromServer ()
 Disconnect from the RPC server. More...
 

Signals

void connected ()
 
void disconnected (rec::rpc::ErrorCode error)
 
void stateChanged (QAbstractSocket::SocketState state)
 
void error (QAbstractSocket::SocketError socketError, const QString &errorString)
 
void log (const QString &message, int level=1)
 

Public Member Functions

 Client (QObject *parent=0)
 Constructor. More...
 
virtual ~Client ()
 Destructor. More...
 
QString name () const
 Get the Client's name. More...
 
bool isMultiThreadedSerializationEnabled () const
 Get multi-threaded serialization flag state. More...
 
bool isLocalIPCEnabled () const
 Get local IPC enabled flag state. More...
 
bool isConnected () const
 Get connection state. More...
 
QString address () const
 Get RPC server's network address. More...
 
QHostAddress localAddress () const
 Get the clients local address. More...
 
quint16 localPort () const
 Get the clients local port. More...
 
QHostAddress peerAddress () const
 Get the clients peer address. More...
 
quint16 peerPort () const
 Get the clients peer port. More...
 
QString expectedGreeting () const
 The greeting message that is expected from the server when connecting. More...
 
unsigned int msTimeout () const
 Timeout for RPC requests. More...
 
void getServerVersion (int *major, int *minor, int *patch, int *date=0, QString *suffix=0)
 Get the server's version. More...
 
QString getServerVersion ()
 Get the server's version. More...
 

Static Public Attributes

static const unsigned int DefaultTimeout = 2000
 Default value for the maximum amount of time the client has to wait for a response from the server. More...
 

Protected Member Functions

void invoke (const QString &name, serialization::SerializablePtrConst param, serialization::SerializablePtr result, bool blocking)
 Invoke a RPC function on the server. More...
 
void publishTopic (const QString &name, serialization::SerializablePtrConst data)
 Publish new topic data. More...
 
void registerNotifier (const QString &name, NotifierBasePtr notifier)
 Register a RPC response notifier. More...
 
void unregisterNotifier (const QString &name)
 Unregister a RPC response notifier. More...
 
bool isNotifierRegistered (const QString &name) const
 Check if a RPC response notifier for a given function name is registered. More...
 
void registerTopicListener (const QString &name, TopicListenerBasePtr listener)
 Register a topic listener. More...
 
void unregisterTopicListener (const QString &name)
 Unregister a topic listener. More...
 
bool isTopicListenerRegistered (const QString &name) const
 Check if a topic listener for a given topic is registered. More...
 

Detailed Description

RPC client base class.

Base class to implement a RPC client. Derive from that class to implement your own client.

Definition at line 99 of file rec_rpc_Client.h.

Constructor & Destructor Documentation

rec::rpc::Client::Client ( QObject *  parent = 0)

Constructor.

Parameters
parentParent object.
virtual rec::rpc::Client::~Client ( )
virtual

Destructor.

Member Function Documentation

QString rec::rpc::Client::address ( ) const

Get RPC server's network address.

Returns
The network address of the RPC server.
See also
setAddress()
void rec::rpc::Client::connected ( )
signal

This signal is emitted when a connection has been established.

See also
connectToServer(), disconnectFromServer(), disconnected()
void rec::rpc::Client::connectToServer ( unsigned int  msTimeout = DefaultTimeout)
slot

Connect to a RPC server.

The client trys to establish a connection to a RPC server. This methood does not block. If the connection is successfully established, the connected() signal will be emittet. If the connection attempt fails, disconnected() will be emitted.

Parameters
msTimeoutConnection timeout in milliseconds (default is 2000).
See also
connected(), disconnected(), disconnectFromServer()
void rec::rpc::Client::disconnected ( rec::rpc::ErrorCode  error)
signal

This signal is emitted when the client has been disconnected.

Parameters
errorError code. If the client disconnected regularly, it is NoError.
See also
connectToServer(), disconnectFromServer(), connected()
void rec::rpc::Client::disconnectFromServer ( )
slot

Disconnect from the RPC server.

The client disconnects from the RPC server. After disconnecting, the disconnected() signal will be emitted.

See also
connected(), disconnected(), connectToServer()
void rec::rpc::Client::error ( QAbstractSocket::SocketError  socketError,
const QString &  errorString 
)
signal

This signal is emitted when an error occurs.

Parameters
socketErrorError code
errorStringHuman readable description of the error that occurred.
QString rec::rpc::Client::expectedGreeting ( ) const

The greeting message that is expected from the server when connecting.

When a client connects to the server, the server sends a "greeting" (which is just a short ASCII string) to the client. If the expected greeting string is not empty, it will be compared with the greeting sent by the server. If they are different, an Exception with error code IncompatibleServer will be thrown.

Returns
Expected greeting string.
See also
setExpectedGreeting()
void rec::rpc::Client::getServerVersion ( int *  major,
int *  minor,
int *  patch,
int *  date = 0,
QString *  suffix = 0 
)

Get the server's version.

Send a RPC blocking request to the server to retrieve its version.

Parameters
majorPointer to an int that shall contain the major version number.
minorPointer to an int that shall contain the minor version number.
patchPointer to an int that shall contain the patch version number.
datePointer to an int that shall contain the date when this version was released (format YYYYMMDD).
suffixPointer to a string that is appended to the version number (can be empty or "a", "beta" or so).
QString rec::rpc::Client::getServerVersion ( )

Get the server's version.

Send a RPC blocking request to the server to retrieve its version.

Returns
Version string.
void rec::rpc::Client::invoke ( const QString &  name,
serialization::SerializablePtrConst  param,
serialization::SerializablePtr  result,
bool  blocking 
)
protected

Invoke a RPC function on the server.

This method is used to invoke a RPC function on the server. It is recommended to use the preprocessor macro instead of calling the method directly.

Parameters
nameName if the RPC function.
paramRPC function parameters. This must be a shared pointer containing an instance of a rec::rpc::serialization::Serializable subclass.
resultRPC function return values. This must be a shared pointer containing an instance of a rec::rpc::serialization::Serializable subclass.
blockingIf true, the function call will block until a response has been received. If an error occurs during a blocking function call, a rec::rpc::Exception will be thrown.
Exceptions
rec::rpc::ExceptionError codes: NoConnection, UnknownFunction, WrongDataFormat, ExecutionTimeout, ExecutionCancelled.
See also
PREPARE, INVOKE, INVOKE_SIMPLE, INVOKE_SIMPLE_EMPTY
bool rec::rpc::Client::isConnected ( ) const

Get connection state.

Returns
true if the client is connected to a server.
See also
connectToServer, disconnectFromServer
bool rec::rpc::Client::isLocalIPCEnabled ( ) const

Get local IPC enabled flag state.

Returns
True if local IPC is enabled.
See also
setLocalIPCEnabled
bool rec::rpc::Client::isMultiThreadedSerializationEnabled ( ) const

Get multi-threaded serialization flag state.

Returns
True if serialization is performed by multiple threads.
See also
setMultiThreadedSerializationEnabled
bool rec::rpc::Client::isNotifierRegistered ( const QString &  name) const
protected

Check if a RPC response notifier for a given function name is registered.

It is recommended to use the preprocessor macro instead of calling the method directly.

Parameters
nameName of the RPC function.
See also
IS_NOTIFIER_REGISTERED
bool rec::rpc::Client::isTopicListenerRegistered ( const QString &  name) const
protected

Check if a topic listener for a given topic is registered.

It is recommended to use the preprocessor macro instead of calling the method directly.

Parameters
nameName of the topic.
See also
IS_TOPICLISTENER_REGISTERED, IS_TOPICINFOCHANGED_REGISTERED
QHostAddress rec::rpc::Client::localAddress ( ) const

Get the clients local address.

Returns
The local address
quint16 rec::rpc::Client::localPort ( ) const

Get the clients local port.

Returns
The local port
void rec::rpc::Client::log ( const QString &  message,
int  level = 1 
)
signal

This signal is used to forward log messages from the client to the application.

Parameters
messageThe log message.
levelThe log level. Default is 1.
unsigned int rec::rpc::Client::msTimeout ( ) const

Timeout for RPC requests.

When a RPC request is sent to the server and no response arrived within a certain time period, the request will be cancelled with error code ExecutionTimeout. Default value is 2000.

Returns
Timeout in milliseconds.
See also
setMsTimeout()
QString rec::rpc::Client::name ( ) const

Get the Client's name.

Returns
Client's name that will be transmitted to the server.
See also
setName
QHostAddress rec::rpc::Client::peerAddress ( ) const

Get the clients peer address.

Returns
The peer address
quint16 rec::rpc::Client::peerPort ( ) const

Get the clients peer port.

Returns
The peer port
void rec::rpc::Client::publishTopic ( const QString &  name,
serialization::SerializablePtrConst  data 
)
protected

Publish new topic data.

Use this method to modify topic data and notify all clients that listen to that topic. It is recommended to use the preprocessor macro instead of calling the method directly.

Parameters
nameName of the topic.
dataPointer to the data to be serialized and published.
Exceptions
rec::rpc::ExceptionError codes: NoConnection, NoSuchTopic, AccessDenied.
See also
PREPARE_TOPIC, PUBLISH_TOPIC, PUBLISH_TOPIC_SIMPLE
void rec::rpc::Client::registerNotifier ( const QString &  name,
NotifierBasePtr  notifier 
)
protected

Register a RPC response notifier.

This method is used to add a response notifier for a RPC function. In case of a non-blocking function call the notifier is invoked when the result is received from the server or a timeout has occurred. It is recommended to use the preprocessor macro instead of calling the method directly.

Parameters
nameName of the RPC function.
notifierResponse notifier. This must be a QSharedPointer pointing to an instance of a struct derived from NotifierBase.
See also
REGISTER_NOTIFIER
void rec::rpc::Client::registerTopicListener ( const QString &  name,
TopicListenerBasePtr  listener 
)
protected

Register a topic listener.

This method is used to add a topic listener that is invoked when the data of a topic change. It is recommended to use the preprocessor macro instead of calling the method directly.

Parameters
nameName of the topic.
listenerTopic listener. This must be a QSharedPointer pointing to an instance of a struct derived from TopicListenerBase.
Exceptions
rec::rpc::ExceptionError codes: NoSuchTopic.
See also
REGISTER_TOPICLISTENER, REGISTER_TOPICINFOCHANGED
void rec::rpc::Client::setAddress ( const QString &  address)
slot

Set the network address of the RPC server.

Parameters
addressAddress of the RPC server (can be IPv4 or IPv6).
See also
address()
void rec::rpc::Client::setAutoReconnectEnabled ( bool  enable,
unsigned int  ms = 200 
)
slot

Enable/disable automatic reconnection.

When enabled the client tries to reconnect automatically after the specified number of milliseconds.

Parameters
enableIf true the automatic reconnect will be enabled. If false the client does not reconnect to the server automatically.
msThe time in millisconds after which to automatically reconnect to the server.
See also
connected(), disconnected(), disconnectFromServer()
void rec::rpc::Client::setExpectedGreeting ( const QString &  greeting)
slot

Set the greeting message that is expected from the server when connecting.

When a client connects to the server, the server sends a "greeting" (which is just a short ASCII string) to the client. If the expected greeting string is not empty, it will be compared with the greeting sent by the server. If they are different, an Exception with error code IncompatibleServer will be thrown.

Parameters
greetingNew expected greeting string.
See also
expectedGreeting()
void rec::rpc::Client::setLocalIPCEnabled ( bool  enabled)
slot

Enable or Disable local IPC. Enabled by default.

Parameters
enabledIf false, the client will always use TCP to connect to the server, even if the client runs on the same machine as the server.
Remarks
The Client must be disconnected and reconnected for the change to take effect!
See also
isLocalIPCEnabled
void rec::rpc::Client::setMsTimeout ( unsigned int  timeout)
slot

Set the timeout for RPC requests.

When a RPC request is sent to the server and no response arrived within a certain time period, the request will be cancelled with error code ExecutionTimeout. Default value is 2000.

Parameters
timeoutTimeout in milliseconds.
See also
msTimeout()
void rec::rpc::Client::setMultiThreadedSerializationEnabled ( bool  enabled)
slot

Enable or disable multi-threaded serialization. Disabled by default.

Parameters
enabledIf true, (de)serialization tasks will be performed by multiple threads. This should perform better on multi core CPUs.
Remarks
The Client must be disconnected and reconnected for the change to take effect!
See also
isMultiThreadedSerializationEnabled
void rec::rpc::Client::setName ( const QString &  name)
slot

Set the Client's name. Default is the application name.

Parameters
nameClient's name that will be transmitted to the server.
See also
name
void rec::rpc::Client::stateChanged ( QAbstractSocket::SocketState  state)
signal

This signal is emitted when the client's socket state has changed

Parameters
stateNew socket state.
void rec::rpc::Client::unregisterNotifier ( const QString &  name)
protected

Unregister a RPC response notifier.

This method is used to remove a notifier. It is recommended to use the preprocessor macro instead of calling the method directly.

Parameters
nameName of the RPC function.
See also
UNREGISTER_NOTIFIER
void rec::rpc::Client::unregisterTopicListener ( const QString &  name)
protected

Unregister a topic listener.

This method is used to remove a topic listener. It is recommended to use the preprocessor macro instead of calling the method directly.

Parameters
nameName of the topic.
See also
UNREGISTER_TOPICLISTENER, UNREGISTER_TOPICINFOCHANGED

Member Data Documentation

const unsigned int rec::rpc::Client::DefaultTimeout = 2000
static

Default value for the maximum amount of time the client has to wait for a response from the server.

Definition at line 104 of file rec_rpc_Client.h.


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