Alarm API

The Alarm API provides functionality for scheduling the system alarm. It allows you to run other applications and have them perform operations at a specific time. You can schedule an alarm to go off once or to repeat at specific intervals.

Each application has its own individual alarm storage, that is, applications cannot view or edit alarms set by other applications.

Once an alarm goes off, it will be removed from the alarm storage automatically. AlarmManager provides methods to manage alarms such as adding and removing.

Remark: In order to access files, a proper privilege has to be defined additionally:

For more information on the Alarm features, see Alarm Guide.

Since: 1.0

Table of Contents

Summary of Interfaces and Methods

Interface Method
AlarmManagerObject
AlarmManager
void add (Alarm alarm, ApplicationId applicationId, optional ApplicationControl? appControl)
void addAlarmNotification (Alarm alarm, Notification notification)
void remove (AlarmId id)
void removeAll ()
Alarm
AlarmRelative
AlarmAbsolute

1. Type Definitions

1.1. AlarmId

An alarm identifier. 
  typedef DOMString AlarmId;

Since: 1.0

1.2. ByDayValue

Specifies the values for the daysOfTheWeek attribute. 
  enum ByDayValue { "MO", "TU", "WE", "TH", "FR", "SA", "SU" };

Since: 1.0

  • "MO" corresponds to "Monday"
  • "TU" corresponds to "Tuesday"
  • "WE" corresponds to "Wednesday"
  • "TH" corresponds to "Thursday"
  • "FR" corresponds to "Friday"
  • "SA" corresponds to "Saturday"
  • "SU" corresponds to "Sunday"

2. Interfaces

2.1. AlarmManagerObject

The AlarmManagerObject interface defines what is instantiated by the Tizen object from the Tizen Platform. The tizen.alarm object allows access to the functionality of the Alarm API. 
  [NoInterfaceObject] interface AlarmManagerObject {
    readonly attribute AlarmManager alarm;
  };
  Tizen implements AlarmManagerObject;

Since: 1.0

Attributes

  • readonly AlarmManager alarm
    Object representing an alarm manager.

    Since: 1.0

2.2. AlarmManager

The AlarmManager interface provides methods to manage alarms. 
  [NoInterfaceObject] interface AlarmManager {
    const long PERIOD_MINUTE = 60;
    const long PERIOD_HOUR = 3600;
    const long PERIOD_DAY = 86400;
    const long PERIOD_WEEK = 604800;
    void add(Alarm alarm, ApplicationId applicationId, optional ApplicationControl? appControl) raises(WebAPIException);
    void addAlarmNotification(Alarm alarm, Notification notification) raises(WebAPIException);
    void remove(AlarmId id) raises(WebAPIException);
    void removeAll() raises(WebAPIException);
    Alarm get(AlarmId id) raises(WebAPIException);
    UserNotification getAlarmNotification(AlarmId id) raises(WebAPIException);
    Alarm[] getAll() raises(WebAPIException);
  };

Since: 1.0

Constants

  • PERIOD_MINUTE
    The period of a minute. It defines the number of seconds per minute.

    Since: 1.0



  • PERIOD_HOUR
    The period of an hour. It defines the number of seconds per hour.

    Since: 1.0



  • PERIOD_DAY
    The period of a day. It defines the number of seconds per day.

    Since: 1.0



  • PERIOD_WEEK
    The period of a week. It defines the number of seconds in a week.

    Since: 1.0



    • Methods

    add
    Adds an alarm to the storage. 
    void add(Alarm alarm, ApplicationId applicationId, optional ApplicationControl? appControl);

    Since: 1.0

    Sets an alarm with the application ID to be run. You should definitely provide the application ID to run and the application control information if it is necessary. For more information about the application control, see The Application API.

    Privilege level: public

    Privilege: http://tizen.org/privilege/alarm

    Parameters:

    • alarm: An alarm to add. It can be either AlarmRelative or AlarmAbsolute.
    • applicationId: The application ID to run when the alarm is triggered.
    • appControl [optional] [nullable]: The data structure describing application control details.

    Exceptions:

    • WebAPIException

      • with error type TypeMismatchError, if any input parameter is not compatible with the expected type for that parameter.

      • with error type InvalidValuesError, if any input parameter does not contain a valid value.

      • with error type SecurityError, if the application does not have the privilege to call this method.

      • with error type UnknownError, if any other error occurs.

    Code example:

    /* Triggers an alarm on a given date/time. */
var alarm = new tizen.AlarmAbsolute(new Date(2014, 10, 4, 8, 0));
var appControl = new tizen.ApplicationControl("http://tizen.org/appcontrol/operation/view");
tizen.alarm.add(alarm, tizen.application.getCurrentApplication().appInfo.id, appControl);
console.log("Alarm added with id: " + alarm.id);
    addAlarmNotification
    Adds an alarm notification to the storage. 
    void addAlarmNotification(Alarm alarm, Notification notification);

    Since: 4.0

    Adds an alarm which causes notification to appear instead of launching an AppControl. For more information about the notification, see The Notification API.

    Privilege level: public

    Privilege: http://tizen.org/privilege/alarm

    Privilege: http://tizen.org/privilege/notification

    Warning: Since Tizen 4.0 constructor AlarmAbsolute(Date date, long period) is deprecated thus it is not allowed to pass AlarmAbsolute created from such constructor.

    Parameters:

    • alarm: An alarm to add. It can be either AlarmRelative or AlarmAbsolute.
    • notification: Notification to be added to the alarm.

    Exceptions:

    • WebAPIException

      • with error type TypeMismatchError, if any input parameter is not compatible with the expected type for that parameter.

      • with error type InvalidValuesError, if any input parameter does not contain a valid value (e.g. recursive AlarmAbsolute, created from constructor AlarmAbsolute(Date date, long period) is passed).

      • with error type SecurityError, if the application does not have the privilege to call this method or the application does not have privilege to access the storage. For more information, see Storage privileges.

      • with error type AbortError, if any other error occurs.

    Code example:

    /* Triggers an alarm notification on a given date/time. */
var alarm = new tizen.AlarmAbsolute(new Date(2017, 10, 4, 8, 0));
var notificationGroupDict =
{
  content: "This is a simple user notification.",
  actions: {soundPath: "music/Over the horizon.mp3", vibration: true}
};

var notification = new tizen.UserNotification("SIMPLE", "User notification", notificationGroupDict);

tizen.alarm.addAlarmNotification(alarm, notification);
console.log("Alarm notification added with id: " + alarm.id);

    Output example:

    Alarm notification added with id: 660485805
    remove
    Removes an alarm from the storage. 
    void remove(AlarmId id);

    Since: 1.0

    If an alarm goes off, it will be removed from the storage automatically.

    Privilege level: public

    Privilege: http://tizen.org/privilege/alarm

    Parameters:

    • id: The ID of the alarm to remove.

    Exceptions:

    • WebAPIException

      • with error type NotFoundError, if this alarm identifier cannot be found in the storage.

      • with error type InvalidValuesError, if any input parameter does not contain a valid value.

      • with error type SecurityError, if the application does not have the privilege to call this method.

      • with error type UnknownError, if the method cannot be completed because of an unknown error.

    Code example:

    var alarms = tizen.alarm.getAll();

/* Removes the first alarm. */
if (alarms.length > 0)
{
  try
  {
    tizen.alarm.remove(alarms[0].id);
    console.log("Successfully removed the first alarm.");
  }
  catch (error)
  {
    console.log("Failed to remove the first alarm.");
  }
}
    removeAll
    Removes all alarms added by an application. 
    void removeAll();

    Since: 1.0

    Because each application has its own alarm storage, this method removes alarms only added by the calling application.

    Privilege level: public

    Privilege: http://tizen.org/privilege/alarm

    Exceptions:

    • WebAPIException

      • with error type SecurityError, if the application does not have the privilege to call this method.

      • with error type UnknownError, if the method cannot be completed because of an unknown error.

    Code example:

    tizen.alarm.removeAll();
console.log("remove all registered alarms in the storage.");
    get
    Returns an alarm as per the specified identifier. 
    Alarm get(AlarmId id);

    Since: 1.0

    Parameters:

    • id: The alarm ID to retrieve.

    Return value:

      Alarm: An alarm object with the specified ID.

    Exceptions:

    • WebAPIException

      • with error type NotFoundError, if this alarm identifier cannot be found in the storage.

      • with error type InvalidValuesError, if any input parameter does not contain a valid value.

      • with error type UnknownError, if the method cannot be completed because of an unknown error.

    Code example:

    /* Sets an alarm. */
var date = new Date();
date.setHours(date.getHours() + 1);
var abs_alarm = new tizen.AlarmAbsolute(date);

/* Adds an alarm. */
tizen.alarm.add(abs_alarm, tizen.application.getCurrentApplication().appInfo.id);

/* Gets an alarm. */
var alarm = tizen.alarm.get(abs_alarm.id);
console.log("The alarm will trigger at " + alarm.getNextScheduledDate());
    getAlarmNotification
    Gets the notification to be posted when an alarm is triggered. Returned UserNotification contains exactly the same data like passed to method addAlarmNotification. 
    UserNotification getAlarmNotification(AlarmId id);

    Since: 4.0

    Privilege level: public

    Privilege: http://tizen.org/privilege/alarm

    Remark: This method is designed to return only UserNotification objects, even if the added alarm was using StatusNofitication.

    Parameters:

    • id: ID which uniquely identifies a scheduled alarm.

    Return value:

      UserNotification: Notification to be posted when the alarm is triggered.

    Exceptions:

    • WebAPIException

      • with error type NotFoundError, if alarm with given identifier was already triggered or alarm identifier cannot be found in the storage.

      • with error type SecurityError, if the application does not have the privilege to call this method or the application does not have privilege to access the storage. For more information, see Storage privileges.

      • with error type AbortError, if any other error occurs.

    Code example:

    var date = new Date();
date.setHours(date.getHours() + 1);
var alarm = new tizen.AlarmAbsolute(date);

var notificationGroupDict =
{
  content: "This is a simple user notification.",
  actions: {soundPath: "music/Over the horizon.mp3", vibration: true}
};

var notification = new tizen.UserNotification("SIMPLE", "User notification", notificationGroupDict);

/* Adds an alarm. */
tizen.alarm.addAlarmNotification(alarm, notification);

/* Gets a notification. */
var notification = tizen.alarm.getAlarmNotification(alarm.id);
console.log(
    "User Notification title: " + notification.title + ", content: " + notification.content);

    Output example:

    User Notification title: User notification, content: This is a simple user notification.
    getAll
    Retrieves all alarms in an application storage. 
    Alarm[] getAll();

    Since: 1.0

    Alarms that have already been triggered are removed automatically from the storage.

    Return value:

      Alarm[]: All Alarm objects.

    Exceptions:

    • WebAPIException

      • with error type UnknownError, if the method cannot be completed because of an unknown error.

    Code example:

    var alarms = tizen.alarm.getAll();
console.log(alarms.length + " alarms present in the storage.");

    2.3. Alarm

    The Alarm interface is an abstract interface for alarm types. 
      [NoInterfaceObject] interface Alarm {
    readonly attribute AlarmId? id;
  };

    Since: 1.0

    Attributes

    • readonly AlarmId id [nullable]
      The alarm identifier.

      Since: 1.0

    2.4. AlarmRelative

    The AlarmRelative interface provides the relative alarm, which occurs at a fixed interval in future. 
      [Constructor(long delay, optional long? period)]
  interface AlarmRelative : Alarm {
    readonly attribute long delay;
    readonly attribute long? period;
    long? getRemainingSeconds() raises(WebAPIException);
  };

    Since: 1.0

    This alarm triggers after a duration mentioned in the delay attribute from the moment the alarm is added. If a period is provided, the alarm keeps triggering for the given interval.

    Remark: Since Tizen 2.4 behavior of this alarm has changed. In order to decrease the power consumption, the operating system decides when this alarm is going to be fired and what is the period between subsequent executions. It is guaranteed that this alarm will be fired after at least delay seconds. If period is provided, it will be adjusted by the operating system, however this value will not be lower than 600 seconds.

    Code example:

    /* Gets the current application ID. */
var appId = tizen.application.getCurrentApplication().appInfo.id;

/* Sets an alarm in 3 hours from now. */
var alarm1 = new tizen.AlarmRelative(3 * tizen.alarm.PERIOD_HOUR);
tizen.alarm.add(alarm1, appId);

/* Sets an alarm in one hour, recurring after every 10 minutes. */
var alarm2 = new tizen.AlarmRelative(tizen.alarm.PERIOD_HOUR, 10 * tizen.alarm.PERIOD_MINUTE);
tizen.alarm.add(alarm2, appId);

    Constructors

    Constructor (long, long?) 
    AlarmRelative(long delay, optional long? period);

    Attributes

    • readonly long delay
      An attribute to store the difference in time (in seconds) between when an alarm is added and when it is triggered.

      Since: 1.0

      Remark: Since Tizen 2.4 the operating system adjusts this value to decrease the power consumption.

    • readonly long period [nullable]
      An attribute to store the duration in seconds between each trigger of an alarm. By default, this attribute is set to null, indicating that this alarm does not repeat.

      Since: 1.0

      Remark: Since Tizen 2.4 the operating system adjusts this value to decrease the power consumption.

    Methods

    getRemainingSeconds
    Returns the duration in seconds before the next alarm is triggered. 
    long? getRemainingSeconds();

    Since: 1.0

    If the alarm has expired, this method returns null.

    Return value:

      long [nullable]: The duration before the next alarm is triggered.

    Exceptions:

    • WebAPIException

      • with error type UnknownError, if the method cannot be completed because of an unknown error.

    Code example:

    /* Gets the current application ID. */
var appId = tizen.application.getCurrentApplication().appInfo.id;

/* Sets an alarm in 3 hours from now. */
var alarm = new tizen.AlarmRelative(3 * tizen.alarm.PERIOD_HOUR);
tizen.alarm.add(alarm, appId);

var sec = alarm.getRemainingSeconds();
console.log("remaining time is " + sec);

    2.5. AlarmAbsolute

    The AlarmAbsolute interface provides an absolute alarm, which triggers at a specified absolute date. 
      [Constructor(Date date),
   Constructor(Date date, ByDayValue[] daysOfTheWeek),
   Constructor(Date date, long period)]
  interface AlarmAbsolute : Alarm {
    readonly attribute Date date;
    readonly attribute long? period;
    readonly attribute ByDayValue[] daysOfTheWeek;
    Date? getNextScheduledDate() raises(WebAPIException);
  };

    Since: 1.0

    If a period is provided, the alarm keeps triggering for the given interval. If the daysOfTheWeek array is not empty, the alarm triggers every week, for the given days, at the time defined by the date attribute.

    Code example:

    /* Gets the current application ID. */
var appId = tizen.application.getCurrentApplication().appInfo.id;

/* Sets an alarm on January 1st 2014 08:00. */
var date = new Date(2014, 0, 1, 8, 0);
var alarm1 = new tizen.AlarmAbsolute(date);
tizen.alarm.add(alarm1, appId);

/* Sets an alarm on January 1st 2014 08:00, repeating every 2 days. */
/* Since Tizen 4.0 below constructor is deprecated. */
var alarm2 = new tizen.AlarmAbsolute(date, 2 * tizen.alarm.PERIOD_DAY);
tizen.alarm.add(alarm2, appId);

/* Sets an alarm occurring on every Saturday and Sunday, at 08:00, starting from January 1st 2014. */
var alarm3 = new tizen.AlarmAbsolute(date, ["SA", "SU"]);
tizen.alarm.add(alarm3, appId);

    Constructors

    Constructor (Date) 
    AlarmAbsolute(Date date);
    Constructor (Date, ByDayValue[]) 
    AlarmAbsolute(Date date, ByDayValue[] daysOfTheWeek);
    Constructor (Date, long) 
    AlarmAbsolute(Date date, long period);

    Deprecated. Since Tizen 4.0 constructor AlarmAbsolute(Date date, long period) is deprecated.

    Attributes

    • readonly Date date
      An attribute to store the absolute date/time when the alarm is initially triggered.

      This attribute is precise to the second. Milliseconds will be ignored.

      Since: 1.0

    • readonly long period [nullable]
      An attribute to store the duration in seconds between each trigger of the alarm.

      Deprecated. Since Tizen 4.0 constructor AlarmAbsolute(Date date, long period) is deprecated, thus this attribute should not be used.

      By default, this attribute is set to null, indicating that this alarm does not repeat. The period and daysOfTheWeek attributes are mutually exclusive.

      Since: 1.0

    • readonly ByDayValue[] daysOfTheWeek
      An attribute to store the days of the week associated with the recurrence rule.

      By default, this attribute is set to an empty array. The period and daysOfTheWeek attributes are mutually exclusive.

      Since: 1.0

    Methods

    getNextScheduledDate
    Returns the date / time of the next alarm trigger. 
    Date? getNextScheduledDate();

    Since: 1.0

    If the alarm has expired, this method returns null. The returned date is precise to the second.

    Return value:

      Date [nullable]: The date/time of the next alarm trigger.

    Exceptions:

    • WebAPIException

      • with error type UnknownError, if the method cannot be completed because of an unknown error.

    Code example:

    /* Gets the current application ID. */
var appId = tizen.application.getCurrentApplication().appInfo.id;

/* Sets an alarm on January 1st 2014 08:00. */
var date = new Date(2014, 0, 1, 8, 0);
var alarm1 = new tizen.AlarmAbsolute(date);
tizen.alarm.add(alarm1, appId);

var date = alarm1.getNextScheduledDate();
console.log("next scheduled time is " + date);

    3. Full WebIDL

    module Alarm {
  typedef DOMString AlarmId;
  enum ByDayValue { "MO", "TU", "WE", "TH", "FR", "SA", "SU" };
  Tizen implements AlarmManagerObject;
  [NoInterfaceObject] interface AlarmManagerObject {
    readonly attribute AlarmManager alarm;
  };
  [NoInterfaceObject] interface AlarmManager {
    const long PERIOD_MINUTE = 60;
    const long PERIOD_HOUR = 3600;
    const long PERIOD_DAY = 86400;
    const long PERIOD_WEEK = 604800;
    void add(Alarm alarm, ApplicationId applicationId, optional ApplicationControl? appControl) raises(WebAPIException);
    void addAlarmNotification(Alarm alarm, Notification notification) raises(WebAPIException);
    void remove(AlarmId id) raises(WebAPIException);
    void removeAll() raises(WebAPIException);
    Alarm get(AlarmId id) raises(WebAPIException);
    UserNotification getAlarmNotification(AlarmId id) raises(WebAPIException);
    Alarm[] getAll() raises(WebAPIException);
  };
  [NoInterfaceObject] interface Alarm {
    readonly attribute AlarmId? id;
  };
  [Constructor(long delay, optional long? period)]
  interface AlarmRelative : Alarm {
    readonly attribute long delay;
    readonly attribute long? period;
    long? getRemainingSeconds() raises(WebAPIException);
  };
  [Constructor(Date date),
   Constructor(Date date, ByDayValue[] daysOfTheWeek)]
  interface AlarmAbsolute : Alarm {
    readonly attribute Date date;
    readonly attribute ByDayValue[] daysOfTheWeek;
    Date? getNextScheduledDate() raises(WebAPIException);
  };
};
    Except as noted, this content - excluding the Code Examples - is licensed under Creative Commons Attribution 3.0 and all of the Code Examples contained herein are licensed under BSD-3-Clause.
    For details, see the Content License.