This class is for internal use only. More...

#include <rpc/RPCManager.h>

Inheritance diagram for RPCManager:

Classes
class	RemoteFinishHandler
	Handler that must be implemented by the remote module to send RPC responses to a remote server which sent a previous RPC request. More...

class	RemoteRequestHandler
	Handler that must be implemented by the remote module to send RPC requests to a remote server. More...

Public Types
typedef boost::shared_ptr< RemoteRequestHandler >	RemoteRequestHandlerPtr

typedef boost::shared_ptr< RemoteFinishHandler >	RemoteFinishHandlerPtr

typedef RPCServer::ServiceInfo< RPCServer::MethodInfoSet >	RemoteService

Public Member Functions
template<typename Reflector >
void	reflect (Reflector &r)
	Reflect method for serialization. More...

template<typename Service >
void	addLocalService (const std::string &name, Service &service, AbstractRPCHandlerPtr handler)
	Adds a local service. More...

void	removeLocalService (const std::string &name)
	Remove the local service. More...

std::set< std::string >	getLocalServices () const
	Get all registered local services. More...

const RPCServer::Service &	getLocalService (const std::string &name) const
	Returns a reference to the local service object with the given name. More...

void	addRemoteService (const RemoteService &serviceInfo, RemoteRequestHandlerPtr handler, uint8 binaryFormatVersion=BinaryBufferSerializer::getSerializerFormatVersion())
	Adds a remote service. More...

void	removeRemoteService (const std::string &name)
	Remove a remote service. More...

std::set< std::string >	getRemoteServices () const
	Get all registered remote services. More...

const RemoteService &	getRemoteService (const std::string &name) const
	Returns a reference to the remote service info object with the given name. More...

void	registerCallback (const std::string &interface, AbstractInterfaceCallbackHandlerPtr callback)
	Registers a callback handler that is called whenever a service registers the interface, which is specified as first parameter. More...

void	unregisterCallback (const std::string &interface, AbstractInterfaceCallbackHandlerPtr callback)
	Unregisters a callback handler for a specific interface. More...

void	unregisterCallback (AbstractInterfaceCallbackHandlerPtr callback)
	Unregisters a callback handler for all interfaces. More...

bool	existsService (const std::string &name) const
	Returns true, if a service with the given name exists, otherwise false. More...

bool	waitForService (const std::string &name, Duration timeout=Duration::invalid()) const
	Waits until a service with the specified name becomes available. More...

std::string	waitForServiceInterface (const std::string &interface, Duration timeout=Duration::invalid()) const
	Waits until a service with the specified interface becomes available. More...

std::list< std::string >	queryServicesForInterface (const std::string &interface) const
	Returns a string list with the names of all registered services (local and remote), that implement the specified interface. More...

bool	implementsInterface (const std::string &name, const std::string &interface) const
	Returns if the given service implements a certain interface. More...

void	handleRemoteRequest (Buffer< uint8 > buffer, RemoteFinishHandlerPtr handler=RemoteFinishHandlerPtr())
	Request to handle the given remote request, whose content is stored in the specified buffer. More...

void	handleRemoteRequest (Buffer< uint8 > buffer, RemoteFinishHandlerPtr handler, uint8 binaryFormatVersion)
	Request to handle the given remote request, whose content is stored in the specified buffer. More...

void	handleRemoteResponse (Buffer< uint8 > buffer)
	Handles the response on a previous remote request, that was sent through a RemoteRequestHandler. More...

void	handleRemoteResponse (Buffer< uint8 > buffer, uint8 binaryFormatVersion)
	Handles the response on a previous remote request, that was sent through a RemoteRequestHandler. More...

template<typename R , typename... ARGS>
RPCFuture< R >	call (const std::string &service, const std::string &method, ARGS &&... args)
	Method that is used by local C++ clients for requesting an rpc call. More...

RPCFuture< JSONRPCResponse >	callJSON (const json::Value &jsonCall)
	Invokes a JSON RPC call. More...

RPCFuture< JSONRPCResponse >	callJSON (const std::string &jsonCall)
	Provided for convenience. More...

RPCFuture< JSONRPCResponse >	callJSON (const std::string &service, const std::string &method, const json::Value &params=json::Value())
	Invokes a JSON RPC call, on the specified service and method with the given params by generating a JSON RPC 2.0 conform json request. More...

RPCFuture< JSONRPCResponse >	callJSON (const std::string &service, const std::string &method, const std::string &params)
	Provided for convenience. More...

RPCFuture< JSONRPCResponse >	callJSON (const RPCCallDefinition &rpc)
	Provided for convenience. More...

Protected Member Functions
RPCFuture< JSONRPCResponse >	callJSONIntern (const std::string &service, const std::string &callID, const json::Value &request)
	Internally doing a JSON RPC call. More...

template<typename Backend >
void	handleLocalRequest (typename Backend::ContainerType buffer, const std::string &service)
	Internally used, to handle rpc requests for services that are also maintained by this local RPCManager, taking into account that these service may be handled from the same thread that sent the request. More...

template<typename Backend >
void	handleRequest (typename Backend::ContainerType buffer, RemoteFinishHandlerPtr finishHandler, bool remote)
	Internally used, to handle incoming rpc requests. More...

virtual void	onRPCfinished (AbstractDeferredInvoker *invoker)
	called upon finish of the RPC call, the ID of the call is passed as parameter. More...

Detailed Description

This class is for internal use only.

Be aware, that the interface may change significantly in future versions.

Invokation of a remote service:
                                                     remote         remote
               RPCManager                           RPCManager      service
                  |                                     |              |
  call() -----—>|                 handleRemoteRequest |              |
                  |---------------------------------—>| invoke       |
                  |                                     |----------—>|
                  | handleRemoteResponse                |<----------—|
result via future |<---------------------------------—|              |
         <-----—|                                     |              |

Invokation of a local service:
           RPCManager                          local service
              |                                      |

  call() -----—>| handleLocalBinaryRequest      invoke |
                  |----------------------------------—>|
result via future |<----------------------------------—|
         <-----—|                                      |

Member Typedef Documentation

◆ RemoteRequestHandlerPtr

typedef boost::shared_ptr<RemoteRequestHandler> RemoteRequestHandlerPtr

◆ RemoteFinishHandlerPtr

typedef boost::shared_ptr<RemoteFinishHandler> RemoteFinishHandlerPtr

◆ RemoteService

typedef RPCServer::ServiceInfo<RPCServer::MethodInfoSet> RemoteService

Member Function Documentation

◆ reflect()

void reflect ( Reflector & r )

inline

Reflect method for serialization.

◆ addLocalService()

void addLocalService	(	const std::string &	name,
		Service &	service,
		AbstractRPCHandlerPtr	handler
	)

inline

Adds a local service.

The specified handler is used to process the actual RPC call. It usually is part of a dispatcher thread that belongs to an authority. Hence, the call is handled within the authorities thread that registered the service.

◆ removeLocalService()

void removeLocalService ( const std::string & name )

Remove the local service.

◆ getLocalServices()

std::set<std::string> getLocalServices ( ) const

Get all registered local services.

◆ getLocalService()

const RPCServer::Service& getLocalService ( const std::string & name ) const

inline

Returns a reference to the local service object with the given name.

Exceptions

XInvalidParameter If no such service exists.

◆ addRemoteService()

void addRemoteService	(	const RemoteService &	serviceInfo,
		RemoteRequestHandlerPtr	handler,
		uint8	binaryFormatVersion = `BinaryBufferSerializer::getSerializerFormatVersion()`
	)

Adds a remote service.

The specified handler is called, whenever a method of the registered service is requested. The handler must ship the request to the remote side, where it is passed to the remote RPCManager via handleRemoteRequest(). When registering the service, its implemented interfaces need to be specified.

◆ removeRemoteService()

void removeRemoteService ( const std::string & name )

Remove a remote service.

◆ getRemoteServices()

std::set<std::string> getRemoteServices ( ) const

Get all registered remote services.

◆ getRemoteService()

const RemoteService& getRemoteService ( const std::string & name ) const

Returns a reference to the remote service info object with the given name.

Exceptions

XInvalidParameter If no such service exists.

◆ registerCallback()

void registerCallback	(	const std::string &	interface,
		AbstractInterfaceCallbackHandlerPtr	callback
	)

Registers a callback handler that is called whenever a service registers the interface, which is specified as first parameter.

When a new service is registered that implements the interface the handler is notified with the name of the service and the interface.

◆ unregisterCallback() [1/2]

void unregisterCallback	(	const std::string &	interface,
		AbstractInterfaceCallbackHandlerPtr	callback
	)

Unregisters a callback handler for a specific interface.

◆ unregisterCallback() [2/2]

void unregisterCallback ( AbstractInterfaceCallbackHandlerPtr callback )

Unregisters a callback handler for all interfaces.

◆ existsService()

bool existsService ( const std::string & name ) const

inline

Returns true, if a service with the given name exists, otherwise false.

◆ waitForService()

bool waitForService	(	const std::string &	name,
		Duration	timeout = `Duration::invalid()`
	)		const

Waits until a service with the specified name becomes available.

If a timeout is specified, the method times out if no such service becomes available after the given time. Returns true, if the desired services became available, or false, if the method timed out or the thread was interrupted.

◆ waitForServiceInterface()

std::string waitForServiceInterface	(	const std::string &	interface,
		Duration	timeout = `Duration::invalid()`
	)		const

Waits until a service with the specified interface becomes available.

If a timeout is specified, the method times out if no such service becomes available after the given time. Returns the name of the service, if the desired services became available, or an empty string, if the method timed out or the thread was interrupted.

◆ queryServicesForInterface()

std::list<std::string> queryServicesForInterface ( const std::string & interface ) const

inline

Returns a string list with the names of all registered services (local and remote), that implement the specified interface.

◆ implementsInterface()

bool implementsInterface	(	const std::string &	name,
		const std::string &	interface
	)		const

inline

Returns if the given service implements a certain interface.

◆ handleRemoteRequest() [1/2]

void handleRemoteRequest	(	Buffer< uint8 >	buffer,
		RemoteFinishHandlerPtr	handler = `RemoteFinishHandlerPtr()`
	)

Request to handle the given remote request, whose content is stored in the specified buffer.

The specified finish handler is called when the RPC request has finished in order to return the response to the caller.

◆ handleRemoteRequest() [2/2]

void handleRemoteRequest	(	Buffer< uint8 >	buffer,
		RemoteFinishHandlerPtr	handler,
		uint8	binaryFormatVersion
	)

Request to handle the given remote request, whose content is stored in the specified buffer.

The specified finish handler is called when the RPC request has finished in order to return the response to the caller. The specified format version is used when encoding binary data, enabling communication with a framework still using legacy format.

◆ handleRemoteResponse() [1/2]

void handleRemoteResponse ( Buffer< uint8 > buffer )

Handles the response on a previous remote request, that was sent through a RemoteRequestHandler.

◆ handleRemoteResponse() [2/2]

void handleRemoteResponse	(	Buffer< uint8 >	buffer,
		uint8	binaryFormatVersion
	)

Handles the response on a previous remote request, that was sent through a RemoteRequestHandler.

The specified format version is used when checking the response matches the original request type.

◆ call()

RPCFuture<R> call	(	const std::string &	service,
		const std::string &	method,
		ARGS &&...	args
	)

inline

Method that is used by local C++ clients for requesting an rpc call.

It will internally call handleLocalRequest, if the service is managed by this RPCManager. Otherwise it looks for the service within the registered remote services and calls the onRPCrequested method of the service handler. If the service is completely unknown an XRPC exception is thrown.

◆ callJSON() [1/5]

RPCFuture<JSONRPCResponse> callJSON ( const json::Value & jsonCall )

Invokes a JSON RPC call.

jsonCall must follow the JSON RPC 2.0 protocol. It must contain:

"jsonrpc" with exactly the value "2.0"
"id" an id that can be anything (int, string, null) but should be an unique identifier
"method" a service-method combination of the service to call (e.g. "/MyService.myMethod")
"params" Optional. Required only for methods with parameters. An array containing the parameters of the method to call (e.g. [1, "Hello World"]).
{
"jsonrpc" : "2.0",
"id" : 1,
"method" : "/ns/Service.setInt",
"params" : [255]
}

Returns
Returns a future that will enclose the JSON RPC response containing the result of the call.

◆ callJSON() [2/5]

RPCFuture<JSONRPCResponse> callJSON ( const std::string & jsonCall )

Provided for convenience.

See callJSON above. Will convert jsonCall into a json::Value and calls callJSON(const json::Value& jsonCall) internally.

Parameters

jsonCall Must contain the JSON RPC request in valid JSON syntax.

Returns: Returns a future that will enclose the JSON RPC response containing the result of the call.

◆ callJSON() [3/5]

RPCFuture<JSONRPCResponse> callJSON	(	const std::string &	service,
		const std::string &	method,
		const json::Value &	params = `json::Value()`
	)

Invokes a JSON RPC call, on the specified service and method with the given params by generating a JSON RPC 2.0 conform json request.

Call id will be automatically generated.

Parameters

[in]	service	The service to call
[in]	method	The method on the service to call
[in]	params	The parameters for the method to call (must be a json::Array or json null value (default))

Returns: Returns a future that will enclose the JSON RPC response containing the result of the call.

◆ callJSON() [4/5]

RPCFuture<JSONRPCResponse> callJSON	(	const std::string &	service,
		const std::string &	method,
		const std::string &	params
	)

Provided for convenience.

See callJSON above. Will convert params string into an json::Array and calls callJSON(const std::string& service, const std::string& method, const json::Value& params) internally.

Parameters

[in]	service	The service to call
[in]	method	The method on the service to call
[in]	params	The parameters of the method as comma separated strings (JSON notation, no enclosing [], empty string if no parameters)

Returns: Returns a future that will enclose the JSON RPC response containing the result of the call.

◆ callJSON() [5/5]

RPCFuture<JSONRPCResponse> callJSON ( const RPCCallDefinition & rpc )

Provided for convenience.

Extracts parameters to call callJSON(const std::string& service, const std::string& method, const std::string& params) internally.

Parameters

[in] service The service to call

Returns: Returns a future that will enclose the JSON RPC response containing the result of the call.

◆ callJSONIntern()

RPCFuture<JSONRPCResponse> callJSONIntern	(	const std::string &	service,
		const std::string &	callID,
		const json::Value &	request
	)

protected

Internally doing a JSON RPC call.

◆ handleLocalRequest()

void handleLocalRequest	(	typename Backend::ContainerType	buffer,
		const std::string &	service
	)

protected

Internally used, to handle rpc requests for services that are also maintained by this local RPCManager, taking into account that these service may be handled from the same thread that sent the request.

In this case the method is called immediately to avoid deadlocks. For all other local requests the handleRequest method below is called. The content of the request (method name, parameters, etc) is contained in the specified buffer.

◆ handleRequest()

void handleRequest	(	typename Backend::ContainerType	buffer,
		RemoteFinishHandlerPtr	finishHandler,
		bool	remote
	)

protected

Internally used, to handle incoming rpc requests.

The specified buffer contains all necessary data for the RPC call (service name, method name, parameters, etc). Moreover, a finishHandler must be specified whose onRPCfinished method is called, when the RPC request was processed. The last parameter specifies whether the service request is coming from a remote side. This flag will be stored within the AbstractRequestContext that is created internally.

◆ onRPCfinished()

virtual void onRPCfinished ( AbstractDeferredInvoker * invoker )

protectedvirtual

called upon finish of the RPC call, the ID of the call is passed as parameter.

Implements DeferredInvokerFinishHandler.

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

base/include/rpc/RPCManager.h

Classes

Public Types

Public Member Functions

Protected Member Functions

Detailed Description

Member Typedef Documentation

◆ RemoteRequestHandlerPtr

◆ RemoteFinishHandlerPtr

◆ RemoteService

Member Function Documentation

◆ reflect()

◆ addLocalService()

◆ removeLocalService()

◆ getLocalServices()

◆ getLocalService()

◆ addRemoteService()

◆ removeRemoteService()

◆ getRemoteServices()

◆ getRemoteService()

◆ registerCallback()

◆ unregisterCallback() [1/2]

◆ unregisterCallback() [2/2]

◆ existsService()

◆ waitForService()

◆ waitForServiceInterface()

◆ queryServicesForInterface()

◆ implementsInterface()

◆ handleRemoteRequest() [1/2]

◆ handleRemoteRequest() [2/2]

◆ handleRemoteResponse() [1/2]

◆ handleRemoteResponse() [2/2]

◆ call()

◆ callJSON() [1/5]

◆ callJSON() [2/5]

◆ callJSON() [3/5]

◆ callJSON() [4/5]

◆ callJSON() [5/5]

◆ callJSONIntern()

◆ handleLocalRequest()

◆ handleRequest()

◆ onRPCfinished()