Summary

Class to handle MAE (two-way) messages between MAE apps.

Synchronous messages are managed by RpcBroker.

This class works in conjunction with the MAETask class, which maintains the connection to CommHub, which is required to reach the RpcBroker daemon.

Caution about using remote services: A calling app suspends execution until the response comes back. If the daemon handling the service makes a service call to the app (or perhaps indirectly through a third daemon), you'll have a deadlock condition, causing a timeout.

To register to receive and process these messages, the registering daemon creates an instance of RemoteService; as long as that instance exists, the daemon will be registered to receive the requests; when the instance is destroyed, the daemon will no longer receive requests to process the service.

Public Methods

static XMLData call(service, params)

const string& service	the name of the service requested
const XMLData& params	the input paramters to that service

Call a remote service with the provided service name and parameters. This is synchronous SOA. If the service has been registered with RpcBroker, then the registered daemon will process the request and send back a response. Otherwise, an error is returned.

Return value: the response from that service (status, return data); if an error occured, result["rpc_error"] holds the error message. The response comes directly from the registered daemin, with these additional XML fields:

static string getError(result)

const XMLData& result

the value returned by call()

Get the error message after a call

Return value: a string that is the error message

RemoteService(service, cbfn, cbdata, timeout)

const string& service	the unique (within MAE) name of the service to register (a keyword)
RemoteServiceFN cbfn	the method to handle all requests for this service
void* cbdata	any data to accompany the method call Default value: NULL
int timeout	number of seconds to allow for a response before issuing a timeout to the calling app Default value: 60

Setup/Register a new remote service

static void setError(result, error)

XMLData& result	a structure that will be passed back as a result
const string& error	the error message to insert into the structure

Set error message into response

inline const string& getServiceName() const

Get the name of this remote service.

Return value: the name of the service.

Private Properties

string name	The name of the RPC service
int timeout	Time (in seconds) before a timeout response is sent to the calling app
RemoteServiceFN cbfn	Callback function pointer
void* cbdata	Callback function data
static vector <RemoteService* list	App-wide list of all registered RPC services handled by this app

Private Methods

static string lineEncode(text)

string text

the message to send

Prepare a message to be sent through commhub

Return value: encoded text that is compatible for transmission

static string lineDecode(text)

string text

the message that was sent

Process a message sent from commhub to restore it to the original request.

Return value: decoded text that is restored and ready for processing

static void mastercb(sock, text, data)

SuperSocket& sock	the socket for communication with commhub
const string& text	the message to handle
void* data	callback data

Master callback handler for inbound RPC responses