Resuming applications in the background

Description

Use callback settings to define how you want your Flash Lite application to behave if an asynchronous method call returns data while the application is in the background and paused.

By default, when a Flash Lite application is moved to the background, it is paused. If the application has ongoing asynchronous calls to one or more S60 Platform Services, and if one of the calls returns data while the application is in the background, the application cannot process the data until it is returned to the foreground and resumed. To avoid this situation, you can program your application to resume processing in the background or to bring itself back to the foreground and then resume processing.

This feature is supported since Flash Lite Player 3.1 on S60 5th Edition devices.

Syntax

Define the callback settings in the callbackSettings parameter of the Service API method call:

result = serviceInstance.Operation(parameters, callback, callbackSettings);

The callbackSettings parameter is an object that contains the following properties:

**Table:** callbackSettings object properties
Property	Description	Values
`callbackSettings.resumeOnEvent`	This is a boolean property that specifies whether the backgrounded application resumes processing when the asynchronous call returns data. If you set this property to `true`, processing is resumed.	Possible values: `true` `false`
`callbackSettings.bringToForeground`	This is a boolean property that specifies whether the backgrounded application is brought to the foreground when the asynchronous call returns data. If you set this property to `true`, the application is brought to the foreground. Note: If `resumeOnEvent` is set to `false`, this property has no effect. Setting `bringToForeground` to `true` does not bring the application to the foreground if `resumeOnEvent` is set to `false`.	Possible values: `true` `false`

The following figure shows how different callback setting combinations affect how the application behaves when a callback event occurs.

Figure: Callback setting combinations

Remarks

You can define callback settings only for asynchronous Service API methods that provide repeated callback events. These methods include:
Do not define callback settings for Service API methods other than the ones listed above.
Running a Flash Lite application in the background increases battery drain and can have a negative impact on system performance. Consider carefully whether your application needs to run in the background.

Example code

The following code snippet registers the application to receive notifications on incoming SMS messages. If the application is paused in the background when a notification is received, the application is brought to the foreground to resume processing.

import com.nokia.lib.Service;

var messaging = new Service("Service.Messaging", "IMessaging");
var inParams = {Type:"NewMessage"};
// Define the callback settings.
var callbackSettings = {
  resumeOnEvent:true,
  bringToForeground:true
};
// Make the method call with the callback settings.
messaging.RegisterNotification(inParams, callback, callbackSettings);

function callback(transactionID:Number, eventID:String, outParam:Object)
{
  // Perform tasks on SMS notification.
}

To download an example Flash Lite application that uses the callbackSettings parameter in a Service API method call, see section Flash Lite applications.