Alarm: Scheduling an Application to Be Launched at a Specific Time

This tutorial demonstrates how you can manage alarms in the device to automatically launch applications when an alarm is triggered.

The Alarm API is mandatory for both Tizen mobile and wearable profiles, which means that it is supported in all mobile and wearable devices. All mandatory APIs are supported on the Tizen Emulators.

Warm-up

Become familiar with the Alarm API basics by learning about:

Managing Alarms
Create an absolute and relative alarm, retrieve a list of alarms and delete an alarm.
Launching Applications with Alarms
Launch an application or application service when an alarm is triggered.
Checking for Alarm Events
Check when the next absolute or relative alarm is going to be triggered.

Managing Alarms

Learning how to create and delete alarms is a basic alarm management skill:

To create an absolute alarm, create an instance of the AlarmAbsolute interface (in mobile and wearable applications).

You must define the time and date when the alarm is triggered as a Date object.
```
/* Alarm is triggered at 8:00 on April 4, 2012 */
var date = new Date(2012, 3, 4, 8, 0);
var alarm1 = new tizen.AlarmAbsolute(date);
```
To create a relative alarm, create an instance of the AlarmRelative interface (in mobile and wearable applications).

You must define the delay after which the alarm is triggered.
```
/* Alarm is triggered in 3 hours */
var alarm2 = new tizen.AlarmRelative(3 * tizen.alarm.PERIOD_HOUR); 
```

To create a recurring absolute alarm, create an instance of the AlarmAbsolute interface.

You must define the time and date when the alarm is triggered as a Date object. In addition, you can define a time period or the weekdays when the alarm is repeated.

/* Alarm is triggered for the first time at 8:00 on April 4, 2012 */
var date = new Date(2012, 3, 4, 8, 0);

/* Alarm repeats every 2 days, at 08:00, starting after April 4, 2012 */
var alarm3 = new tizen.AlarmAbsolute(date, 2 * tizen.alarm.PERIOD_DAY);

/* Alarm repeats every Saturday and Sunday, at 08:00, starting after April 4, 2012 */
var alarm4 = new tizen.AlarmAbsolute(date, ["SA", "SU"]);

Note
You cannot define both a time period and a weekday recurrence for the same alarm.

To create a recurring relative alarm, create an instance of the AlarmRelative interface.

You must define the delay after which the alarm is triggered, and the period after which it is repeated.
```
/* Alarm is triggered for the first time in 1 hour, and then repeated every 2 minutes */
var alarm5 = new tizen.AlarmRelative(tizen.alarm.PERIOD_HOUR, 2 * tizen.alarm.PERIOD_MINUTE);
```
To obtain a list of all the alarms that have been set on a device but not yet triggered, use the getAll() method:
```
var alarms = tizen.alarm.getAll(); 
console.log(alarms.length + " alarms present in the storage.");
```

To delete an alarm, use the remove() method with the alarm ID:

/* First add created alarm to the device */
tizen.alarm.add(alarm1, "tizen.internet"); /* Tizen alias ID is deprecated since Tizen 2.3.1 */
/* Then remove it */
tizen.alarm.remove(alarm1.id);

To delete all alarms at once, use the removeAll() method.

Launching Applications with Alarms

Learning how to launch application with alarms is a basic alarm management skill:

To launch an application when an alarm is triggered, you must define the application as a parameter in the add() method used to add the created alarm to the system:

/* Run the browser */
var alarm = new tizen.AlarmAbsolute(new Date(2012, 10, 4, 8, 0));
tizen.alarm.add(alarm, "tizen.internet"); /* Tizen alias ID is deprecated since Tizen 2.3.1 */

To launch an application with additional information when an alarm is triggered, you must use the application control and define the required arguments as a parameter in the add() method used to add the created alarm to the system:

/* Run the browser and open the defined browser page with the operation/view application control */

var alarm = new tizen.AlarmAbsolute(new Date(2012, 10, 4, 8, 0));
var appControl = new tizen.application.ApplicationControl("http://tizen.org/appcontrol/operation/view",
                                                          "http://www.tizen.org");

tizen.alarm.add(alarm, "org.tizen.browser", appControl);

Checking for Alarm Events

Learning how to check for the next alarm to be triggered is a basic alarm management skill:

Create an absolute alarm:

/* Alarm is triggered at 8:00 on April 4, 2012 */
var alarm = new tizen.AlarmAbsolute(new Date(2012, 3, 4, 8, 0)); 
tizen.alarm.add(alarm, "org.tizen.browser");

Use the getNextScheduledDate() method to retrieve the time and date of the next absolute alarm to be triggered:
```
console.log("The alarm will trigger at " + alarm.getNextScheduledDate());
```

Create a relative alarm:

/* Alarm is triggered in 3 hours */
var alarm = new tizen.AlarmRelative (3 * tizen.alarm.PERIOD_HOUR); 
tizen.alarm.add(alarm, "org.tizen.browser");

Use the getRemainingSeconds() method to retrieve the number of seconds till the next relative alarm is triggered:
```
console.log("The alarm triggers " + alarm.getRemainingSeconds() + " seconds later");
```