www.webOShelp.net

Services enable access to low-level hardware hardware capabilities such as GPS and acceelerometer data, and higher-level data services such as Palm Synergy, cloud services, and any other web service APIs.

Services can be divided into the following groups:

• Application services, which include
  • Core application services
  • Palm Synergy Services
  • Viewers & Players
  • Third-party Applications
• System services, which include
  
  • Alarms
  • Connection Manager
  • Location Services (including GPS)
  • Power Management
  • System Properties
  • System Settings
  • System Sounds
• Cloud servivces, which includes
  • Mojo Messaging
  • [Palm implies additional services will be offered later]

Most Application services will launch an application in its own card and will not return automatically to the calling application. System and Cloud services typically return some data to the calling application through one or more calls to a callback function that is defined in the calling application.

All Mojo service calls are asynchronous, meaning that you must define a callback function to receive the data returned from the service request.

There are some constraints to using services in applications that are not in the foreground that Palm has not yet revealed (will come in Chapter 10). Briefly, in many cases the application should limit or stop service requests altogether when it is minimized or in the background.

Service architecture

Most services are Linux servers registered on the Palm Bus, accessed through the Mojo.Service.Request object. Application services are all accessed through a single service method; all other services are individually handled by the named service.

Mojo.Service.Request() should be used for all service calls. However, for convenience, the serviceRequest() method is attached as a property to the scene controller, so this.controller.serviceRequest() can be used within scenes. The basic call includes a service name and method, with a parameters object specific to the method.

Example:

this.controller.serviceRequest('palm://com.palm.serviceName, {
  method: 'methodName',
  parameters{},
  onSuccess: this.successHandler,
  onFailure: this.failureHandler 
  },
  requestOptions
);

There are three situations in which you might need to create a Mojo.Service.Request() object instead of using this.controller.serviceRequest():

• Within App Assistants this.controller.serviceRequest() will not be available.
• All requests made with this.controller.serviceRequest() are removed upon completion of the request or, for subscription requests (subscribe: true), when the scene is popped. If a subscription request needs to be retained beyond the lifetime of the scene, then you will need to use Mojo.Service.Request() to save the request object and manage the request yourself.
• Service requests are asynchronous, so if it's possible your request will not be completed by the time the scene is popped, you should use Mojo.Service.Request().

Click here for an example usage of the Mojo.Service.Request() object.

Most service requests require callback functions to return results to the calling application. The onSuccess function may be called multiple times if the service is designed to return a series of results over time, such as GPS tracking data.

Here's a specific example with a GPS call:

this.controller.serviceRequest('palm://com.palm.location', {
  method:"getCurrentPosition",
  parameters: {},
  onSuccess: this.onSuccessHandler,
  onFailure: this.onFailureHandler
  }  
);

All callbacks are passed a single JSON object that will include some or all of the conventional properties described below, plus method-specific properties if provided.

That's a quick intro to webOS Mojo services. In our next (not quite) daily tutorial series, we'll check out Application Services! Grab the www.webOShelp.net RSS feed to stay on top of your webOS game.

Much of the information in this article was presented in Chapter 7 of Palm webOS by Mitch Allen.