All service calls are asynchronous operations. Each application service has a distinct service name, and exposes one or more named methods. Most application services will launch an application in its own card and will not return to the calling application. Device and cloud services will typically return some data or result to the calling application through a callback function defined by the calling application. Some services, such as Location tracking, will return data in a series of calls to the callback function. You need to design your applications with this asynchronous interface in mind.
There are additional constraints when you are using services in background applications; these will be covered in Chapter 10. Background applications must moderate service use to conserve CPU and battery resources, plus with limited to no user interaction, the background application must handle service responses directly and use notifications and the dashboard to communicate with the user.
In many cases, the application should limit or stop service requests when minimized or in the background. For example, a game that takes accelerometer input should stop tracking the accelerometer when minimized. Without any visible display, there is no value in expending resources to collect that data.
Most services are Linux servers registered on the Palm bus,
wrapped and accessed through the Mojo.Service.Request
object. Application services are all accessed through a single
service method, provided by the Application Manager, which routes the
requests either implicitly based on resource or file type, or explicitly
using the passed application ID. All other services are individually
handled by the named service.
Use a Mojo.Service.Request()
object for all service calls. For convenience, the serviceRequest()
method
is attached as a property to the scene controller, so a commonly used
alternative is this.controller.serviceRequest()
. The basic
call includes a service name and method
, with a method-specific parameters
object:
this.controller.serviceRequest("palm://com.palm.serviceName", { method: "methodname" parameters: {}, onSuccess: this.successHandler, onFailure: this.failureHandler } );
Palm webOS uses the URI (Uniform Resource Identifier) scheme for identifying
services, similar to the way a
standard web URI is used. The service name is typically a string that
begins with palm://com.palm
, followed
by a specific service name. The method
defines the service method to use for
this specific call, and parameters
is
a method-specific JSON object for passing arguments. For example, to get
a GPS fix, make the following request in a scene assistant:
this.controller.serviceRequest("palm://com.palm.location", { method:"getCurrentPosition", parameters: {}, onSuccess: this.onSuccessHandler, onFailure: this.onFailureHandler } });
The string palm://com.palm.location
is the service name
and getCurrentPosition
is the service
method. There are optional parameters defined for this method, but this
example is simply using the default settings. In general, parameters
will vary from service method to service method.
Most service requests require callback functions to return results
to the calling application. The onSuccess
function is
called if the service call is successful and may be called multiple
times for service requests that result in a series of results, such as a
request for Location tracking data instead of just a single fix. The
onFailure
function is
called if the service call results in an error. Both callbacks include a
single response object whose properties are service method
dependent.
There are some conventions for response handling. All callbacks will be passed a single JSON object, and that will include some or all of the conventional properties described in Table 8-1, plus method-specific properties where appropriate.
Table 8-1. Response properties
Name | Description | Required |
---|---|---|
|
| Required |
| The error code from the
service when | Required |
| Description of the
failure when | Required |
| Set to | Optional |
The Application Manager is a specific service that provides functions related to finding and launching applications. Applications launched through the Application Manager will open and maximize a new window for the targeted application while minimizing the current application window.
The Application Manager, through one or both of its service methods, provides access to most of the application services:
open
Accepts a single argument, a formatted URI for a document you wish to display. The mime type of the referenced document is used to identify the appropriate application to handle the content indicated.
launch
Launches the application indicated by the application ID argument passing any included parameters.
Generally, the open
method is used
when you intend to display or process some targeted content, but you
don’t know the specific type of content or the best application
available in the system to handle it. The Application Manager will use
the content type to find the appropriate application to use for that
content:
this.controller.serviceRequest("palm://com.palm.applicationManager", { method: "open", parameters: { target: "http://www.irs.gov/pub/irs-pdf/fw4.pdf" }, onFailure: this.onFailureHandler });
The target includes a command, the string up to and including
the colon and forward slashes (://), and the resource. In this
example, the command is http://
,
but before launching the browser, the Application Manager will
retrieve the HTTP header and attempt to extract the resource type.
Since the URI specifies a file target, the Application Manager will
try to match the file type to the resource list and find a match with
com.palm.app.pdfviewer
. The file
will be downloaded to /media/internal
and the PDF View application
will be launched with a file reference to the downloaded file.
If there’s no header, the Application Manager will download the file anyway and try to match the file extension in the resource list. If there is a match, the associated application will be launched with the file reference as a launch parameter. If there’s no match at this point, the Application Manager will exit and return an error code to the failure callback.
The same process is used when streaming audio or video formats, but instead of downloading the content and then launching the application, the launch is done first and the content URI is passed as an argument. The audio or video player handles the connection and data streaming in these cases; the data is never actually stored on device.
If the command is file://
,
it’s a local file reference and the Application Manager will use the
file extension to launch the associated application (if there is
one).
There are many cases in which you already know which application you’d like to handle the request, and it’s inconvenient to force the parameters into a URI format. In these cases, you’d want a command to launch a specific application and pass in parameters in the form that the application has specified. Here is an example of launching the Maps application to show a street address:
this.controller.serviceRequest("palm://com.palm.applicationManager", { method: "launch", parameters: { id: "com.palm.app.maps", params: { query: "950 W. Maude Ave, Sunnyvale,CA"} } } });
The Command and Resource Table in Appendix B includes the full list of all supported content types and the application resource handlers. This list is very likely to change, so refer to the Palm Developer site for the most current information.
In some cases, a Cross-App launch is used to keep the context of the
calling application, but with a faster transition. The target
application’s scene is pushed directly in the current application’s card
stage, and when the target application is popped, it returns results as
arguments to the calling application’s activate()
method. You
can learn more about the Cross-App launch by referring to the Camera and
People Pickers, both of which use this technique and are covered later
in this chapter.
18.118.142.245