Titanium.Android.Service

Object of Titanium.Android.

Platform	Since
Android	1.5

Summary

The Titanium binding of an Android Service. Can be used to start/stop the service directly and listen for service-specific events. In the Javascript-based services you write, this can be referenced with Titanium.Android.currentService. You can create an instance of the service with Titanium.Android.createService.

Code Examples

Hello World Service

Your service code in its own Javascript file. It reads the Titanium.Android.Intent which created it, to see what it should say besides "Hello World".

File: myservice.js:

var service = Titanium.Android.currentService;
var intent = service.intent;
var message = intent.getStringExtra("message_to_echo");
Titanium.API.info("Hello World!  I am a Service.  I have this to say: " + message);

&lt;android xmlns:android="http://schemas.android.com/apk/res/android"&gt;
    &lt;services&gt;
        &lt;service url="myservice.js" type="interval"/&gt;
    &lt;/services&gt;
&lt;/android&gt;

Code in "regular" Titanium file to launch the service and listen for pause/resume events. Code also stops the service after its code runs 3 times.

var intent = Titanium.Android.createServiceIntent( { url: 'myservice.js' } );
// Service should run its code every 2 seconds.
intent.putExtra('interval', 2000);
// A message that the service should 'echo'
intent.putExtra('message_to_echo', 'Titanium rocks!');
 
var service = Titanium.Android.createService(intent);
service.addEventListener('resume', function(e) {
    Titanium.API.info('Service code resumes, iteration ' + e.iteration);
});
service.addEventListener('pause', function(e) {
    Titanium.API.info('Service code pauses, iteration ' + e.iteration);
    if (e.iteration === 3) {
        Titanium.API.info('Service code has run 3 times, will now stop it.');
        service.stop();
    }
});
service.start();

Console Output:

[INFO] [29,1942] Service code resumes, iteration 1
[INFO] [70,2029] Hello World! I am a Service. I have this to say: Titanium rocks!
[INFO] [3,2070] Service code pauses, iteration 1
[INFO] [2,3915] Service code resumes, iteration 2
[INFO] [31,3961] Hello World! I am a Service. I have this to say: Titanium rocks!
[INFO] [5,3968] Service code pauses, iteration 2
[INFO] [2,5917] Service code resumes, iteration 3
[INFO] [27,5961] Hello World! I am a Service. I have this to say: Titanium rocks!
[INFO] [16,5980] Service code pauses, iteration 3
[INFO] [1,5981] Service code has run 3 times, will now stop it.

Methods

Name	Summary
addEventListener	Adds the specified callback as an event listener for the named event.
fireEvent	Fires a synthesized event to any registered listeners.
removeEventListener	Removes the specified callback as an event listener for the named event.
start	Start the Service. Effective only if this instance of `Titanium.Android.Service` was created with `Titanium.Android.createService`.
stop	Stop this running instance of the Service.

Properties

Name	Type	Summary
intent	`Titanium.Android.Intent`	The `Titanium.Android.Intent` used to start or bind to the Service. read-only
serviceInstanceId	Number	A service can be started more than once -- this number (based on an incrementing integer) indicates which "start number" in the sequence the current service instance is. read-only

Events

Name	Summary
pause	For Javascript-based Services which you create, `pause` fires after each time the Javascript code executes. `resume` and `pause` happen in pairs, with `resume` firing just before your Javascript service code executes, and `pause` just after.
resume	For Javascript-based Services which you create, `resume` fires each time the Javascript code executes. For example, if your Service runs on an interval of 10000 (10 seconds), you would expect to see `resume` fired every 10 seconds, just as the Javascript service code you wrote is about to execute.
start	Fired when the bound Service instance starts. Bound service instances are created via `Titanium.Android.createService`.
stop	Fired when the bound Service instance stops, meaning `Titanium.Android.Service.stop` or `Titanium.Android.stopService` has been called and there are no more bound, un-stopped clients.