Search in book...
Toggle Font Controls
Create new playlist

Name your new playlist

Playlist description (optional)
Sign In

Email address

Password

Forgot Password?

or

Continue with Facebook

Continue with Google
Sign Up

Full Name

Email address

Confirm Email Address

Password

or

Continue with Facebook

Continue with Google

Using Services

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.

Service Overview

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
`returnValue`	`true` on success or `false` on failure of this request	Required
`errorCode`	The error code from the service when `returnValue` is false	Required
`errorText`	Description of the failure when `returnValue` is false	Required
`subscribed`	Set to `true` if a subscription request was successful	Optional

Mojo.Service.Request()

You can use this.controller.serviceRequest() within scenes where you would make most service requests. However, if you need to make a service request within your application assistant, you’ll need to create a service request object.

A common case is a call to the Alarm service to wake up the application after an interval:

this.alarm = new Mojo.Service.Request("palm://com.palm.power/timeout", {
    method: "set",
    parameters: {
        key: "com.palm.app.news.update",
        in: feedUpdateInterval,
        uri: "palm://com.palm.applicationManager/open",
        params: {
            id: "com.palm.app.news",
            params: {action: "updateFeed"}
        }
    },
    onSuccess: this.onSuccessHandler,
    onFailure: this.onFailureHandler
});

In this example, the new request object is created and a service request issued, with the object stored as this.alarm.

The request references are managed by the scene when creating a service request using this.controller.serviceRequest(), and are removed upon completion of the request, unless the request has subscribe: true, in which case the requests are cleaned up when the scene is popped.

All requests made with this.controller.serviceRequest() are cleaned up when the scene is popped, meaning they are garbage collected and destroyed. If the subscription request needs to be retained beyond the lifetime of the scene, you will also need to use Mojo.Service.Request() to save the request object and manage the request yourself.

Remember that service requests are asynchronous, so they don’t complete when you make the call; if there’s a chance they will not be completed by the time the scene is popped, use Mojo.Service.Request().

Application Manager

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.

Open

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).

Launch

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.

Cross-App Launch

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.

..................Content has been hidden....................

You can't read the all page of ebook, please click here login for view all page.

Table of Contents for Using Services

Create new playlist

Sign In