Rcp Javascript library

The Rpc class allows to make calls to an JSON-RPC server.

The server address is given by the "PFS" Jad property and cannot be modified. The API automatically adds the "JSON-RPC" path to the "PFS" property to access the JSON-RPC service.

If multiple connections are made simultaneously, then will be queued and done one after the

Warning:
This API uses "opaque" references that must be passed from one call to another and must be freed at the end of the operation by calling Rpc.getResult(ref) or Rpc.cancel(ref). The number of references is limited so all references must always be freed.

Warning:
Do not use the synchronous mode of the JSON-RPC request. This will freeze your application during all the request and parsing.

This API is only supported on Mobile Widgets version of the MeMo, and should now only be used to support data provided by the Rpc API.
It is not supproted by Tiny Mobile Widgets version.

1.4.0

ref call (true, string methodCall, [arg1, arg2, ..., argN]):
Make a asynchronous JSON-RPC request to the server and return a reference to this request.

methodCall must define the method to call on the server side (e.g. "Weather.getForcast").
arg1, arg2, ..., argN are the optional parameters to pass to the method. These arguments can be either a string, an integer, a float or a reference to an array or collection of the Array API.

result call (false, string methodCall, [arg1, arg2, ..., argN]):
DEPRECATED Make a synchronous JSON-RPC request.

void cancel (ref):
Cancel the asynchronous request referenced by ref. Calling this methods frees the reference ref.

result getResult (ref):
Retrieve the result of the asynchronous request referenced by ref. The result is either a string, an integer, a float or a reference to an array or collection of the Array API, or -1 on error. Calling this methods frees the reference ref.

void addCallback (ref, event, callback, [arg1, arg2, ..., argN]):
Add a callback to an asynchronous request referenced by ref. This allows to monitor the progress and completion of an asynchronous request.

event can be one of Rpc.ON_SUCESS, Rpc.ON_ERROR, Rpc.ON_PROGRESS, Rpc.ON_START, Rpc.ALL_STATES.
callback : name of the function to call when the event occurs on the request.
arg1 arg2, ..., argN : operational parameters to pass to the callback.

The callback will then have the following signature : function callback (ref, [arg1, arg2, ..., argN][, progress], time).

void clean ():
Cancel all queued requests and free all data associated to this API.

ON_SUCCESS:
To use as the event argument for addCallback.
The callback will be called if the asynchronous request is successful.

ON_ERROR:
To use as the event argument for addCallback.
The callback will be called if the asynchronous request triggers an error.

ON_START:
To use as the event argument for addCallback.
The callback will be called when the asynchronous request starts.

ON_PROGRESS:
To use as the event argument for addCallback.
The callback will then be called during the download the events on the asynchronous request with an additional progress parameter (ranging from 0 to 100).

ALL_STATES:
DEPRECATED To use as the event argument for addCallback.
The callback will be called for all the events on the asynchronous request with an additional event parameter.
The additional parameter is an integer with values 0=UNKNOWN, 1=QUEUED, 2=START, 4=SUCCESS, 8=ERROR.

This is an example for a imaginary weather forecast service.

function testRpc () {
  var ref = Rpc.call (true, 'Weather.getForecast', 'Rennes');
  Rpc.addCallback (ref, Rpc.ON_SUCCESS, onSuccess, 'Weather for Rennes', 'this is a test', 'a third arg');
  Rpc.addCallback (ref, Rpc.ON_ERROR, onError, 'Rennes');
  Rpc.addCallback (ref, Rpc.ON_PROGRESS, onProgress, 'Rennes');
}

function onSuccess (ref, arg1, arg2, arg3) {
  var forecastResult = Rpc.getResult (ref); // retreive collection from the server and free the request reference

  // Parse and display forecast
  var forecast = Array.getElement(forecastResult, 'forecast');
  Browser.print ('Weather on monday : '+Array.getElement (forecast, 'monday'));
  Browser.print ('Weather on sunday : '+Array.getElement (forecast, 'sunday'));
  Array.free (forecast);
  Array.free (forecastResult);
}

function onError (ref, arg1) {
  Browser.print ('Could not request forecast for city '+arg1);
}

function onProgress (ref, arg1, progress) {
  Browser.print ('Downloading forecast for city '+arg1+': '+(progress/100.0)+'%');
}