# Mojo.Service

## Namespace Detail

A service is an on-device "server" for any resource, data, or configuration that can be exposed for developers to use with their applications. They are called "services" instead of "servers" to make it clear that they are on the device rather than "in the cloud".

The Web is built on Uniform Resource Identifiers (URIs), so Palm uses this scheme for identifying resources. Here is an example:

>     palm://com.palm.contacts/

This is the name of the Contacts service in the system. Each service is then able to provide methods, with an optional category, for clients to invoke.

It becomes the responsibility of the service to provide both service names to the service and maintain backwards compatibility. Helpers in the APIs aid this process.

## Method Summary

- Mojo.Service.Request(url, options, requestOptions)

## Method Detail

### Mojo.Service.Request(url, options, requestOptions)

Mojo.Service.Request is a constructor, so you will need to use "new" to instantiate the request object.

All data passed in a request to a service, and all data returned from a service is encoded as a JSON object. The exact names and values passed in and out are service-dependent, but some conventions must be followed for a service to be considered correct and conforming.

If a client wants to get the system time of the device, they would make a request to

>     palm://com.palm.systemservice/getSystemTime

with the optional JSON argument {subscribe:true} if they wish to subscribe for updates. "Subscribing" means that the request will return to the onSuccess, onFailure, and onComplete calls specified in the initial request each time. Subscribed requests will return with a subscriberId.

If the request is successful, the returned result of this request would be:

>     {"localtime": localTimeInSecs, "offset", offsetFromUTCInMins,
>       "timezone": timeZone}.

The onSuccess callback is called back during a successful request, onFailure is called for a failed request (either a failure at the dbus or the service side will cause this), and onComplete, if specified, is always called last after a request returns.

Or for the request in code (this would be placed in an application scene assistant):

>     var request = new Mojo.Service.Request('palm://com.palm.systemservice', {
>       method: 'getSystemTime',
>       parameters: {subscribe:true},
>       onSuccess: this.handleResponse //this is a callback function you would declare
>                                      // in the scene assistant
>     });

When creating a serviceRequest in the manner above, request references are managed by the scene and are removed on completion of the request, unless the request has `subscribe: true`, in which case the requests are cleaned up when the scene is popped. If the request needs to be retained beyond the lifetime of the scene, create a new Mojo.Service.Request and manage the request variable yourself.

#### Parameters

- url - URL of the service request as defined in the developer guide
- options - hash value containing the options for the specific service request call
- requestOptions - either true, meaning to resubscribe automatically on error, or an object with a resubscribe property of true or false

#### Unsubscribing from a Service

When you are ready to unsubscribe from a Service, use the cancel() method on the service request object.

>     var myRequest = new Mojo.Service.Request({ subscribe: true });
>     ...
>     myRequest.cancel(); // Kills the subscription