Samsung Electronics logo

Samsung Web API: Alarm


Introduction

This API provides the functionality for setting and unsetting of alarms.

Each client application has its own individual alarm storage, that is, applications cannot view (or edit) alarms set by other applications. For more information on the Alarm features, see Alarm Guide.


Table of Contents


Summary of Interfaces and Methods

Interface Method
AlarmManagerObject
AlarmManager void add(Alarm alarm, ApplicationId applicationId, ApplicationControl? appControl)
void remove(AlarmId id)
void removeAll()
Alarm get(AlarmId id)
Alarm[] getAll()
Alarm
AlarmRelative long? getRemainingSeconds()
AlarmAbsolute Date? getNextScheduledDate()

1. Type Definitions

1.1. AlarmId

An alarm identifier.

    typedef DOMString AlarmId;

2. Interfaces

2.1. AlarmManagerObject

This interface defines what is instantiated by the WebAPIs object. There will be a webapis.alarm object that allows access to the functionality of the Alarm API.

    [NoInterfaceObject] interface AlarmManagerObject {
        readonly attribute AlarmManager alarm;
    };
    WebAPIs implements AlarmManagerObject;

2.2. AlarmManager

This 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 remove(AlarmId id) raises(WebAPIException);


        void removeAll() raises(WebAPIException);


        Alarm get(AlarmId id) raises(WebAPIException);


        Alarm[] getAll() raises(WebAPIException);
    };

CONSTANTS

long PERIOD_MINUTE

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

long PERIOD_HOUR

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

long PERIOD_DAY

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

long PERIOD_WEEK

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

METHODS

add

Adds an alarm to the storage.

Signature
void add(Alarm alarm, ApplicationId applicationId, optional ApplicationControl? appControl);

For more information about the arguments, see The Application API.

Parameters
  • alarm
    • Optional: No.
    • Nullable: No.
    • Type: Alarm.
    • Description: An alarm to add.
  • applicationId
    • Optional: No.
    • Nullable: No.
    • Type: ApplicationId.
    • Description: The ID of the application to execute when the alarm is triggered.
  • appControl
    • Optional: Yes.
    • Nullable: Yes.
    • Type: ApplicationControl.
    • Description: The data structure describing application control details.
Exceptions
  • WebAPIException:

    with error type UnknownError, if any other error occurs.

    with error type NotSupportedError, if this feature is not supported.

    with error type SecurityError, if the client does not have the permission to add alarms.

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

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

Code example
 // Triggers an alarm on a given date/time
 var alarm = new webapis.AlarmAbsolute(new Date(2014, 10, 4, 8, 0));
 var appControl = new webapis.ApplicationControl("http://samsungapps.com/appcontrol/operation/view", "http://developer.samsung.com/SamsungWebAPI");
 webapis.alarm.add(alarm, webapis.application.getCurrentApplication().appInfo.id, appControl);
 console.log("Alarm added with id: " + alarm.id);
 

remove

Removes an alarm from the storage.

Signature
void remove(AlarmId id);
Parameters
  • id
    • Optional: No.
    • Nullable: No.
    • Type: AlarmId.
    • Description: The ID of the alarm to remove
Exceptions
  • WebAPIException:

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

    with error type NotSupportedError, if this feature is not supported.

    with error type SecurityError, if the client does not have the permission to remove alarms.

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

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

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

Code example
 var alarms = webapis.alarm.getAll();

 // Removes the first alarm
 if (alarms.length > 0) {
   try {
     webapis.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.

Signature
void removeAll();

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

Exceptions
  • WebAPIException:

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

    with error type NotSupportedError, if this feature is not supported.

    with error type SecurityError, if the client does not have the permission to remove alarms.

Code example
 webapis.alarm.removeAll();
 console.log("remove all registered alarms in the storage.");
 

get

Returns an alarm as per the specified identifier.

Signature
Alarm get(AlarmId id);
Parameters
  • id
    • Optional: No.
    • Nullable: No.
    • Type: AlarmId.
    • Description: The ID of the alarm to retrieve.
Return value
Alarm An alarm object with the specified ID.
Exceptions
  • WebAPIException:

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

    with error type NotSupportedError, if this feature is not supported.

    with error type SecurityError, if the client does not have the permission to get an alarm.

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

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

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

Code example
 // Sets an alarm
 var date = new Date(2014, 10, 10, 8, 0);
 var abs_alarm = new webapis.AlarmAbsolute(date);

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

 // Gets an alarm
 var alarm = webapis.alarm.get(abs_alarm.id);
 console.log("The alarm will trigger at " + alarm.getNextScheduledDate());
 

getAll

Returns all alarms

Signature
Alarm[] getAll();

This method returns all alarms in an application storage. 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.

    with error type NotSupportedError, if this feature is not supported.

    with error type SecurityError, if the client does not have the permission to get alarms.

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

2.3. Alarm

This interface is an abstract interface for alarm types.

    [NoInterfaceObject] interface Alarm {

        readonly attribute AlarmId? id;
    };

ATTRIBUTES

readonly AlarmId? id

The alarm identifier.

This attribute is read-only.

2.4. AlarmRelative

This 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);
    };

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

Code example
 // Gets the current application id.
 var appId = webapis.application.getCurrentApplication().appInfo.id;

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

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

ATTRIBUTES

readonly long delay

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

This attribute is read-only.

readonly long? period

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.

This attribute is read-only.

METHODS

getRemainingSeconds

Returns duration in seconds before the next alarm is triggered.

Signature
long? getRemainingSeconds();

If the alarm has expired, this method returns null.

Return value
long The duration before the next alarm trigger.
Exceptions
  • WebAPIException:

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

    with error type NotSupportedError, if this feature is not supported.

    with error type SecurityError, if the client does not have the permission to get alarms.

Code example
 // Gets the current application id.
 var appId = webapis.application.getCurrentApplication().appInfo.id; 

 // Sets an alarm in 3 hours from now
 var alarm = new webapis.AlarmRelative(3 * webapis.alarm.PERIOD_HOUR);
 webapis.alarm.add(alarm, appId);
 
 var sec = alarm.getRemainingSeconds();
 console.log("remaining time is " + sec);
 

2.5. AlarmAbsolute

This interface provides an absolute alarm, which triggers at a specified absolute date. 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 date attribute.

    [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);
    };
Code example
 // Gets the current application id.
 var appId = webapis.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 webapis.AlarmAbsolute(date);
 webapis.alarm.add(alarm1, appId);

 // Sets an alarm on January 1st 2014 08:00, repeating every 2 days
 var alarm2 = new webapis.AlarmAbsolute(date, 2 * webapis.alarm.PERIOD_DAY);
 webapis.alarm.add(alarm2, appId);

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

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.

This attribute is read-only.

readonly long? period

An attribute to store the duration in seconds between each trigger of the alarm.

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

This attribute is read-only.

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.

This attribute is read-only.

METHODS

getNextScheduledDate

Returns the date / time of the next alarm trigger.

Signature
Date? getNextScheduledDate();

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

Return value
Date 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.

    with error type NotSupportedError, if this feature is not supported.

    with error type SecurityError, if the client does not have the permission to get alarms.

Code example
 // Gets the current application id.
 var appId = webapis.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 webapis.AlarmAbsolute(date);
 webapis.alarm.add(alarm1, appId);
 
 var date = alarm1.getNextScheduledDate();
 console.log("next scheduled time is " + date);
 

3. Full WebIDL

module Alarm {

    typedef DOMString AlarmId;



    [NoInterfaceObject] interface AlarmManagerObject {
        readonly attribute AlarmManager alarm;
    };
    WebAPIs implements AlarmManagerObject;


    [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 remove(AlarmId id) raises(WebAPIException);


        void removeAll() raises(WebAPIException);


        Alarm get(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),

     Constructor(Date date, long period)]

    interface AlarmAbsolute : Alarm {

        readonly attribute Date date;


        readonly attribute long? period;


        readonly attribute ByDayValue[] daysOfTheWeek;


        Date? getNextScheduledDate() raises(WebAPIException);
    };
};