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

RPC server base class. More...

#include <rec_rpc_Server.h>

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

Public Slots

bool listen (bool blocking=false)
 Start server. More...
 
void close (bool blocking=false)
 Stop server. More...
 
void exit ()
 Shutdown the server. More...
 
void disconnectAllClients ()
 Disconnect all clients. More...
 
void disconnectClient (const QHostAddress &peerAddress, quint16 peerPort)
 Disconnect a specific client. More...
 
void setMultiThreadedSerializationEnabled (bool enabled)
 Enable or disable multi-threaded serialization. Disabled by default. More...
 
void setPort (int port=rec::rpc::defaultPort)
 Set the port the Server is supposed to use. More...
 
void setLocalIPCEnabled (bool enabled)
 Enable or Disable local IPC. Enabled by default. More...
 
void setClientMsgWaitTime (int clientMsgWaitTime=DefaultClientMsgWaitTime)
 Set client message wait time. More...
 
void setHttpKeepAliveTimeout (int httpKeepAliveTimeout=DefaultHttpKeepAliveTimeout)
 Set HTTP keep-alive timeout. More...
 
void setHttpKeepAliveMaxRequests (int httpKeepAliveMaxRequests=DefaultHttpKeepAliveMaxRequests)
 Set maximum number of requests for HTTP connections. More...
 
void setCustomTimeout (int customTimeout=DefaultCustomTimeout)
 "et timeout for custom connections More...
 
void setGreeting (const QString &greeting)
 Set a custom greeting message. More...
 

Signals

void listening ()
 
void closed ()
 
void finished ()
 
void serverError (QAbstractSocket::SocketError error, const QString &errorString)
 
void clientError (QAbstractSocket::SocketError error, const QString &errorString)
 
void clientConnected (const rec::rpc::ClientInfo &info)
 
void clientDisconnected (const rec::rpc::ClientInfo &info)
 
void registeredTopicListener (const QString &name, const rec::rpc::ClientInfo &info)
 
void unregisteredTopicListener (const QString &name, const rec::rpc::ClientInfo &info)
 
void numClientsConnectedChanged (int num)
 
void log (const QString &message, int level=1)
 

Public Member Functions

 Server (QObject *parent=0)
 Constructor. More...
 
virtual ~Server ()
 Destructor. More...
 
bool isMultiThreadedSerializationEnabled () const
 Get multi-threaded serialization flag state. More...
 
int port () const
 Get the port the Server is supposed to use. More...
 
bool isLocalIPCEnabled () const
 Get local IPC enabled flag state. More...
 
int clientMsgWaitTime () const
 Get client message wait time. More...
 
int httpKeepAliveTimeout () const
 Get HTTP keep-alive timeout. More...
 
int httpKeepAliveMaxRequests () const
 Get maximum number of requests for HTTP connections. More...
 
int customTimeout () const
 Get timeout for custom connections. More...
 
bool isListening () const
 Get the Server's listening state. More...
 
unsigned short serverPort () const
 Get the TCP port currently in use. More...
 
QString greeting () const
 The server's greeting message. More...
 
int numClientsConnected () const
 Get the number connected clients. More...
 

Static Public Attributes

static const int DefaultClientMsgWaitTime = 5000
 Default value for the maximum amount of time (in milliseconds) the server waits for a message from the client after a connection has been established. More...
 
static const int DefaultHttpKeepAliveTimeout = 20
 Default value for the http keep-alive timeout (in seconds). More...
 
static const int DefaultHttpKeepAliveMaxRequests = 10
 Default value for the maximum number of requests for a persistent HTTP connection. More...
 
static const int DefaultCustomTimeout = 2
 Default value for the timeout for custom connections (in seconds). More...
 
static int sendFailSocketTimeout
 Close socket if sending fails for sendFailSocketTimeout() milli seconds. More...
 

Protected Member Functions

void registerFunction (const QString &name, RPCFunctionBasePtr function)
 Register a RPC function. More...
 
void unregisterFunction (const QString &name)
 Unregister a RPC function. More...
 
bool isFunctionRegistered (const QString &name) const
 Check if a RPC function with a given 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...
 
void addTopic (const QString &name, int sharedMemorySize=0, bool serverOnly=false)
 Add a non permanent topic. More...
 
void addEnqueuedTopic (const QString &name, bool serverOnly=false)
 Add a non permanent enqueued topic. More...
 
void addPermanentTopic (const QString &name, int sharedMemorySize=0, bool serverOnly=false)
 Add a permanent topic. More...
 
void beginAddTopicGroup ()
 
void endAddTopicGroup ()
 
void publishTopic (const QString &name, serialization::SerializablePtrConst data)
 Publish new topic data. More...
 
void registerHttpGetHandler (HTTPGetHandlerBasePtr handler=HTTPGetHandlerBasePtr())
 Register a HTTP GET handler. More...
 
void registerCustomRequestHandler (CustomRequestHandlerBasePtr handler=CustomRequestHandlerBasePtr())
 Register a custom request handler. More...
 

Detailed Description

RPC server base class.

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

Definition at line 176 of file rec_rpc_Server.h.

Constructor & Destructor Documentation

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

Constructor.

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

Destructor.

Member Function Documentation

void rec::rpc::Server::addEnqueuedTopic ( const QString &  name,
bool  serverOnly = false 
)
protected

Add a non permanent enqueued topic.

This method is used to register a topic in the server. The server and the clients can publish data via the topic. The data is distributed via local IPC or the TCP connection. It is recommended to use the preprocessor macro instead of calling the method directly.

With a non permanent enqueued topic topic listeners are called only when someone published new data to the topic. It is ensured that no data published is dropped. This is different to a non enqueued topic where data can be dropped if published to fast. Enqueued topics can not use shared memory.

Parameters
nameName of the topic.
serverOnlySet to true if only the server should be able to publish data via this topic
Exceptions
rec::rpc::ExceptionError codes: ImproperTopicName, TopicAlreadyExists.
See also
ADD_TOPIC, addPermanentTopic
void rec::rpc::Server::addPermanentTopic ( const QString &  name,
int  sharedMemorySize = 0,
bool  serverOnly = false 
)
protected

Add a permanent topic.

This method is used to register a topic in the server. The server and the clients can publish data via the topic. The data is distributed via shared memory, local IPC or the TCP connection. It is recommended to use the preprocessor macro instead of calling the method directly.

With a permanent topic topic listeners are called once after they registered to the topic and someone already published data into this topic.

Parameters
nameName of the topic.
sharedMemorySizeMinimum size of the shared memory segment in bytes. If 0 (default), no shared memory will be used.
serverOnlySet to true if only the server should be able to publish data via this topic
Exceptions
rec::rpc::ExceptionError codes: ImproperTopicName, TopicAlreadyExists.
See also
ADD_TOPIC, addTopic
void rec::rpc::Server::addTopic ( const QString &  name,
int  sharedMemorySize = 0,
bool  serverOnly = false 
)
protected

Add a non permanent topic.

This method is used to register a topic in the server. The server and the clients can publish data via the topic. The data is distributed via shared memory, local IPC or the TCP connection. It is recommended to use the preprocessor macro instead of calling the method directly.

With a non permanent topic topic listeners are called only when someone published new data to the topic.

Parameters
nameName of the topic.
sharedMemorySizeMinimum size of the shared memory segment in bytes. If 0 (default), no shared memory will be used.
serverOnlySet to true if only the server should be able to publish data via this topic
Exceptions
rec::rpc::ExceptionError codes: ImproperTopicName, TopicAlreadyExists.
See also
ADD_TOPIC, addPermanentTopic
void rec::rpc::Server::beginAddTopicGroup ( )
protected
void rec::rpc::Server::clientConnected ( const rec::rpc::ClientInfo info)
signal

This signal is emitted when a client has established a connection to the server.

Parameters
infoClient info containing the client's address, port and name.
void rec::rpc::Server::clientDisconnected ( const rec::rpc::ClientInfo info)
signal

This signal is emitted when a client has disconnected from the server.

Parameters
infoClient info containing the client's address, port and name.
void rec::rpc::Server::clientError ( QAbstractSocket::SocketError  error,
const QString &  errorString 
)
signal

This signal is emitted when an error occurs on a client.

Parameters
errorError code
errorStringHuman readable description of the error that occurred.
int rec::rpc::Server::clientMsgWaitTime ( ) const

Get client message wait time.

Returns
maximum amount of time (in milliseconds) the server waits for a message from the client after a connection has been established.
See also
setClientMsgWaitTime
void rec::rpc::Server::close ( bool  blocking = false)
slot

Stop server.

After calling this method, the server stops listening.

Parameters
blockingIf true, this method blocks the calling thread until the server has really stopped listening!
Remarks
When the operation has been finished, the closed() signal will be emitted even if the server was not listening!
See also
closed
void rec::rpc::Server::closed ( )
signal

This signal is emitted when the server has been stopped.

See also
close, isListening
int rec::rpc::Server::customTimeout ( ) const

Get timeout for custom connections.

Returns
timeout for custom connections (in seconds).
See also
setCustomTimeout
void rec::rpc::Server::disconnectAllClients ( )
slot

Disconnect all clients.

void rec::rpc::Server::disconnectClient ( const QHostAddress &  peerAddress,
quint16  peerPort 
)
slot

Disconnect a specific client.

void rec::rpc::Server::endAddTopicGroup ( )
protected
void rec::rpc::Server::exit ( )
slot

Shutdown the server.

After calling this method, the server is down and it is save to quit the application

void rec::rpc::Server::finished ( )
signal

This signal is emitted when the server has been shutdown.

See also
exit
QString rec::rpc::Server::greeting ( ) const

The server's greeting message.

When a client connects to the server, the server sends a "greeting" (which is just a short ASCII string) to the client. If you connect to the server via telnet, this is the first message you will see. Default is "REC RPC Server <Version>".

Returns
Greeting string.
See also
setGreeting()
int rec::rpc::Server::httpKeepAliveMaxRequests ( ) const

Get maximum number of requests for HTTP connections.

Returns
maximum number of requests for a persistent HTTP connection.
See also
setHttpKeepAliveMaxRequests
int rec::rpc::Server::httpKeepAliveTimeout ( ) const

Get HTTP keep-alive timeout.

Returns
http keep-alive timeout (in seconds).
See also
setHttpKeepAliveTimeout
bool rec::rpc::Server::isFunctionRegistered ( const QString &  name) const
protected

Check if a RPC function with a given 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_FUNCTION_REGISTERED
bool rec::rpc::Server::isListening ( ) const

Get the Server's listening state.

Returns
true if the server is listening.
See also
listen, close, listening, closed
bool rec::rpc::Server::isLocalIPCEnabled ( ) const

Get local IPC enabled flag state.

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

Get multi-threaded serialization flag state.

Returns
True if serialization is performed by multiple threads.
See also
setMultiThreadedSerializationEnabled
bool rec::rpc::Server::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
bool rec::rpc::Server::listen ( bool  blocking = false)
slot

Start server.

After calling this method, the server will listen for connecting clients at the specified port.

Parameters
blockingIf true, this method blocks the calling thread until the server has really been set up or the operation has been cancelled.
Returns
If blocking, return value will be true if the server has been successfully set up and false if the operation has been cancelled. If non-blocking, return value will always be true.
Remarks
If the server has been successfully started, the listening() signal will be emitted. Otherwise (e.g because the port is already in use) the closed() signal will be emitted.
See also
listening, isListening
void rec::rpc::Server::listening ( )
signal

This signal is emitted when the server has been started.

See also
listen, isListening
void rec::rpc::Server::log ( const QString &  message,
int  level = 1 
)
signal

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

Parameters
messageThe log message.
levelThe log level. Default is 1.
int rec::rpc::Server::numClientsConnected ( ) const

Get the number connected clients.

Returns
Number of connected clients.
void rec::rpc::Server::numClientsConnectedChanged ( int  num)
signal

This signal is emitted when a client establishes a connection or is disconnected and hence the number of connected clients changes.

Parameters
numNew number of connected clients.
int rec::rpc::Server::port ( ) const

Get the port the Server is supposed to use.

Returns
The port the Server is supposed to use. If it is already in use, the server will use a different port which will be returned by serverPort().
See also
setPort, serverPort
void rec::rpc::Server::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::Server::registerCustomRequestHandler ( CustomRequestHandlerBasePtr  handler = CustomRequestHandlerBasePtr())
protected

Register a custom request handler.

This method is used to set a handler for custom (non-RPC and non-HTTP) requests from a client. It is recommended to use the preprocessor macro instead of calling the method directly.

Parameters
handlercustom request handler. This must be a QSharedPointer pointing to an instance of a struct derived from CustomRequestHandlerBase. It replaces the existing handler. If NULL, the existing handler will be removed.
See also
REGISTER_CUSTOM_REQUEST_HANDLER
void rec::rpc::Server::registeredTopicListener ( const QString &  name,
const rec::rpc::ClientInfo info 
)
signal

This signal is emitted when a client has registered a topic listener.

Parameters
nameName of the topic.
infoClient info containing the client's address, port and name.
void rec::rpc::Server::registerFunction ( const QString &  name,
RPCFunctionBasePtr  function 
)
protected

Register a RPC function.

This method is used to add a RPC function that can be invoked by a client. It is recommended to use the preprocessor macro instead of calling the method directly.

Parameters
nameName of the RPC function.
functionRPC function wrapper. This must be a QSharedPointer pointing to an instance of a struct derived from RPCFunctionBase.
Exceptions
rec::rpc::ExceptionError codes: ImproperFunctionName.
See also
REGISTER_FUNCTION
void rec::rpc::Server::registerHttpGetHandler ( HTTPGetHandlerBasePtr  handler = HTTPGetHandlerBasePtr())
protected

Register a HTTP GET handler.

This method is used to set a handler for HTTP GET requests from a client. It is recommended to use the preprocessor macro instead of calling the method directly.

Parameters
handlerHTTP GET handler. This must be a QSharedPointer pointing to an instance of a struct derived from HTTPGetHandlerBase. It replaces the existing handler. If NULL, the existing handler will be removed.
See also
REGISTER_HTTP_GET_HANDLER
void rec::rpc::Server::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::Server::serverError ( QAbstractSocket::SocketError  error,
const QString &  errorString 
)
signal

This signal is emitted when an error occurs on the server.

Parameters
errorError code
errorStringHuman readable description of the error that occurred.
unsigned short rec::rpc::Server::serverPort ( ) const

Get the TCP port currently in use.

This can be a different port than the one specified in setPort (in case that the specified port is already in use a differen one will be chosen automatically).

Returns
TCP port the server is currently using.
See also
port, setPort
void rec::rpc::Server::setClientMsgWaitTime ( int  clientMsgWaitTime = DefaultClientMsgWaitTime)
slot

Set client message wait time.

Parameters
clientMsgWaitTimemaximum amount of time (in milliseconds) the server waits for a message from the client after a connection has been established. Default is 5000ms.
Remarks
The Server must be stopped and restarted for the change to take effect!
See also
clientMsgWaitTime
void rec::rpc::Server::setCustomTimeout ( int  customTimeout = DefaultCustomTimeout)
slot

"et timeout for custom connections

Parameters
customTimeouttimeout for custom connections (in seconds). Default is 2s.
Remarks
The Server must be stopped and restarted for the change to take effect!
See also
customTimeout
void rec::rpc::Server::setGreeting ( const QString &  greeting)
slot

Set a custom greeting message.

When a client connects to the server, the server sends a "greeting" (which is just a short ASCII string) to the client. If you connect to the server via telnet, this is the first message you will see. Default is "REC RPC Server <Version>".

Parameters
greetingNew custom greeting.
See also
greeting()
void rec::rpc::Server::setHttpKeepAliveMaxRequests ( int  httpKeepAliveMaxRequests = DefaultHttpKeepAliveMaxRequests)
slot

Set maximum number of requests for HTTP connections.

Parameters
httpKeepAliveMaxRequestsmaximum number of requests for a persistent HTTP connection. Default is 10.
Remarks
The Server must be stopped and restarted for the change to take effect!
See also
httpKeepAliveMaxRequests
void rec::rpc::Server::setHttpKeepAliveTimeout ( int  httpKeepAliveTimeout = DefaultHttpKeepAliveTimeout)
slot

Set HTTP keep-alive timeout.

Parameters
httpKeepAliveTimeouthttp keep-alive timeout (in seconds). Default is 20s.
Remarks
The Server must be stopped and restarted for the change to take effect!
See also
httpKeepAliveTimeout
void rec::rpc::Server::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 Server must be stopped and restarted for the change to take effect!
See also
isLocalIPCEnabled
void rec::rpc::Server::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 Server must be stopped and restarted for the change to take effect!
See also
isMultiThreadedSerializationEnabled
void rec::rpc::Server::setPort ( int  port = rec::rpc::defaultPort)
slot

Set the port the Server is supposed to use.

Parameters
portTCP port used by the server. Default is 9280.
Remarks
The Server must be stopped and restarted for the change to take effect!
See also
port
void rec::rpc::Server::unregisteredTopicListener ( const QString &  name,
const rec::rpc::ClientInfo info 
)
signal

This signal is emitted when a client has unregistered a topic listener.

Parameters
nameName of the topic.
infoClient info containing the client's address, port and name.
void rec::rpc::Server::unregisterFunction ( const QString &  name)
protected

Unregister a RPC function.

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

Parameters
nameName of the RPC function.
See also
UNREGISTER_FUNCTION
void rec::rpc::Server::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 int rec::rpc::Server::DefaultClientMsgWaitTime = 5000
static

Default value for the maximum amount of time (in milliseconds) the server waits for a message from the client after a connection has been established.

Definition at line 181 of file rec_rpc_Server.h.

const int rec::rpc::Server::DefaultCustomTimeout = 2
static

Default value for the timeout for custom connections (in seconds).

Definition at line 190 of file rec_rpc_Server.h.

const int rec::rpc::Server::DefaultHttpKeepAliveMaxRequests = 10
static

Default value for the maximum number of requests for a persistent HTTP connection.

Definition at line 187 of file rec_rpc_Server.h.

const int rec::rpc::Server::DefaultHttpKeepAliveTimeout = 20
static

Default value for the http keep-alive timeout (in seconds).

Definition at line 184 of file rec_rpc_Server.h.

int rec::rpc::Server::sendFailSocketTimeout
static

Close socket if sending fails for sendFailSocketTimeout() milli seconds.

Definition at line 195 of file rec_rpc_Server.h.


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