Using Nokia’s S60 Platform Services API in Flash Lite Mobile

The S60 Platform Services API library, which is referenced here, can be found on the Forum Nokia Developers website at http://library.forum.nokia.com/.

S60 Platform Services Overview

The S60 Platform is the software platform specially created for mobile phones that runs on Symbian OS, one of the leading smartphone platforms in the world. You’ll frequently come across references to the platform in various guises. For one, there have been several releases of the platform over the years, including: S60 (2001), S60 2nd Edition (2003), S60 3rd Edition (2005), and S60 5th Edition (2008). Between each major release and the next, there have been iterations containing significant changes or features that were updated in the platform, such as support for higher screen resolutions and increased security for installing third-party applications. One of the features introduced in S60 5th Edition was support for a higher screen resolution of 640 x 360 px, with touch input support.

The S60 5th Edition also introduced specific ActionScript extensions for Flash Lite 3.0 that give you access to specific phone features such as calendars, contacts, messaging, and sensors.

In this section, you’ll review some of the common elements in the S60 Platform Services that are found in the How to Use the API Methods section.

NOTE: At the time of writing, the S60 Platform Services were supported on the devices running S60 5th Edition Symbian OS, which runs Flash Lite 3.0. For each of the examples, it is envisaged that you will have a supported device to run content on.

Download and Install the Library

Before you start to use the services, you need to download and install the ActionScript S60 Platform Services API Library. The .zip file can be downloaded from the Forum Nokia website at http://library.forum.nokia.com/topic/Flash_Lite_Developers_Library/ActionScript_library_for_S60_Platform_Services.zip

Depending on your platform, you also need to download the appropriate folder:

  • For Mac—Copy the extracted folder to /Users/<user name>/Library/Application/Support/Adobe/Flash CS4/en/Configuration/Classes/.

  • For Windows Vista—Extract the folder to /Users/<user name>/AppData/Local/Adobe/Flash CS4/en/Configuration/Classes.

  • For Windows XP—Extract the folder to /<user name>/Local Settings/Application Data/Adobe/Flash CS4/en/Configuration/Classes/.

You should now be ready to progress through the examples in this chapter.

How to Use the API Methods

Each service’s API call requires two parameters: the name of the service provider and an interface. In Table 10-1 you’ll see a current list of S60 Platform Services APIs available. In the table you’ll see the list of Service API names with their corresponding provider, which is its class reference, and the name of the interface required; both are used for instantiating their respective service.

Table 10-1: S60 Platform Services 

Service API
Provider
Interface
AppManager
Service.AppManager
IAppManager
Calendar
Service.Calendar
IDataSource
Contacts
Service.Contact
IDataSource
Landmarks
Service.Landmarks
IDataSource
Location
Service.Location
ILocation
Logging
Service.Logging
IDataSource
Media Management
Service.MediaManagement
IDataSource
Messaging
Service.Messaging
IMessaging
Sensor
Service.Sensor
ISensor
SystemInfo
Service.SysInfo
ISysInfo

Source: Forum Nokia ActionScript Service object page at http://library.forum.nokia.com/index.jsp?topic=/Flash_Lite_Developers_Library/GUID-BB53CD32-F898-418C-BA1D-013E7678C8C9.html

There are two types of methods within the API as specified by Forum Nokia Library: synchronous and asynchronous. Understanding these forms a small but significant part of learning the libraries and syntax of each of the methods.

Synchronous Methods

The method signature for assigning synchronous methods of the Services API requires you to supply a single input parameter object as an argument. For the examples given in this chapter, you’ll notice that the APIs specify the parameter object as params and have specific properties. When you call a synchronous method, it returns the result of the method instantly (see Listing 10-1 and you can download the code from Wrox.com).

Listing 10-1: Calling a synchronous method

import com.nokia.lib.Service;

 

var messaging = new Service("Service.Messaging", "IMessaging");

 

var params:Object = { MessageType:"SMS",

                      To:"recipient number 1.",

                      BodyText:"Hello World" };

 

var result:Object = messaging.Send(params);

A service call returns an object; in Listing 10-1 and throughout this chapter, this is assigned to result. This can have up to three properties defined:

  • ReturnValue—This is an object specific to the Services API method being called. Some methods do not return this property, but the majority will. You’ll learn more about this object for each method throughout this chapter.

  • ErrorCode—This is a number defining a specific error that occurs from a method call. These are not discussed at length, but a few examples are provided for reference.

  • ErrorMessage—This is a string representation of an error and ErrorCode. This property is only defined when an error has occurred.

Asynchronous Methods

For asynchronous methods you need to supply a second argument in addition to params. The callback argument is essentially a reference to an event handler method. The handler is invoked when the result or requested information is retrieved from the service call.

There are three properties that you can obtain from within each callback method:

  • transactionID—A unique number assigned to the callback invoked.

  • eventID—A string representation for the status code of the current service callback and transactionID. This can be any one of the following seven string status code values, relating to the asynchronous service call request:

  • completed—The service call is completed.

  • cancel—The service call is canceled.

  • error—An error occurs during the service call.

  • inprogress—The service call is currently in progress.

  • started—A service call has just started.

  • stopped—A service call has just stopped.

  • unknown—A service call invoked an unknown event.

  • result—An object, which can consist of the three properties returned for synchronous calls in the Services API: Returnvalue, ErrorCode, and ErrorMessage.

Listing 10-2 demonstrates a way in which you can define an asynchronous method with a callback handler.

Listing 10-2: Calling an asynchronous method

import com.nokia.lib.Service;

 

var messaging = new Service("Service.Messaging", "IMessaging");

 

var params:Object = { MessageType:"SMS",

                      To:"recipient number 1.",

                      BodyText:"Hello World" };

 

var result:Object = messaging.Send(params, onSend);

 

function onSend(transactionID:Number, eventID:String, result:Object){

 

}

Canceling Asynchronous Method Calls

With asynchronous calls there may be a small time delay in retrieving results, and you may want to simply cancel the request. Each API has a Cancel() method specifically for this purpose, an example of which is shown in Listing 10-3. Here, the TransactionID is retrieved from the result object, which can be obtained from asynchronous method calls across the API. The transactionID is then passed to the Cancel() method.

Listing 10-3: Canceling an asynchronous call

import com.nokia.lib.Service;

 

var messaging = new Service("Service.Messaging", "IMessaging");

 

var params:Object = { MessageType:"SMS",

                      To:"recipient number 1.",

                      BodyText:"Hello World" };

 

var result:Object = messaging.Send(params, onSend);

 

var transactionID:Number = result.TransactionID;

var hasCancelled:Boolean = messaging.Cancel(transactionID); 

function onSend(transactionID:Number, eventID:String, result:Object){

 

}

NOTE: There are some methods in the S60 Services API that give you the option of calling either the synchronous or asynchronous implementation.  When implementing either of the services, you should consider the type of call you want to make as this will impact the overall structure of your code.  For the majority of the examples in this chapter, the synchronous implementation is used.

The ReturnValue

The ReturnValue is where you will obtain the results of your synchronous or asynchronous method calls. Each method in the API will provide a different ReturnValue depending on the service call implemented.

Defining Filter and Sort Objects

The majority of the methods in the API allow you to set the criteria for the results returned in ReturnValue. By using a Filter object property in the parameters for the call, you can specify what results should be returned. Using the Sort object property you can also order the results returned by the call.

Both these objects are handy, especially where the data you require is complex.

Error Codes

Every service API call returns an ErrorCode and ErrorMessage property, whether synchronous or asynchronous. These are not covered by this chapter in depth; however, in Table 10-2 you’ll see a brief list of some of the service API error codes found in the S60 Platform Services for Flash Lite, with their corresponding description.

Table 10-2: Service API Error Codes 

Error Code
Description
-304
General error
This error occurs if the transaction ID returned by an asynchronous call is -1.
0
Success
1000
Invalid service argument
1001
Unknown argument name

 

Listing 10-4 demonstrates how to retrieve ErrorCode and ErrorMessage from a synchronous call to the Messaging Service API.

Listing 10-4: Retrieving ErrorCode and ErrorMessage properties from a synchronous call

import com.nokia.lib.Service;

 

var messaging = new Service("Service.Messaging", "IMessaging");

 

var params:Object = { MessageType:"SMS",

                      To:"recipient number 1.",

                      BodyText:"Hello World" };

 

var result:Object = messaging.Send(params);

var errorCode:Number = result.ErrorCode;

var errorMsg:String = result.ErrorMessage;

This article is excerpted from chapter 10 "Using Nokia’s S60 Platform Services API" of the book "Professional Flash Lite Mobile Development" by J. G. Anderson (ISBN: 978-0-470-54748-9, Wrox, 2010, Copyright Wiley Publishing Inc.)

Tags:

Comments

Leave a Reply

Your email address will not be published. Required fields are marked *