alarm-api.js - Alarms JS API

# Alarms JS API: alarm-api.js

API Docs for: 0.1

#### alarm-api.js

    /**
     * AlarmApi gives access to Alarm management.

     * @module AlarmApi
     */
    function createAlarmApi(backendBridge) {
        var PLUGIN_URI = 'Alarm';

    /**
     * An Alarm.

     * @class Alarm
     * @constructor
     * @example

          var date = new Date();
          <set a valid date in the future>

          var api = external.getUnityObject('1.0');
          api.AlarmApi.api.createAndSaveAlarmFor(
              date,
              api.AlarmApi.AlarmType.OneTime,
              api.AlarmApi.AlarmDayOfWeek.AutoDetect,
              "alarm triggered",
              function(errorid) {
                  console.log(api.AlarmApi.api.errorToMessage(errorid));
              });
     */
        function Alarm(id) {
            this._proxy = backendBridge.createRemoteObject(
                PLUGIN_URI, 'Alarm', id);
        };
        Alarm.prototype = {

            // properties

            /**
             * The property holds the error code occurred during the last performed operation.
             *
             * @method error
             * @param callback {Function(Error)}
             */
            error: function(callback) {
                this._proxy.call('error', [], callback);
            },

            /**
             * Retrieves the alarm date.
             *
             * The date property holds the date the alarm will be triggered.
             * The default value is the current date and time the alarm object was created.
             * Further reset calls will bring the value back to the time the reset was called.
             *
             * @method error
             * @param callback {Function(Date)}
             */
            date: function(callback) {
                this._proxy.call('date', []
                                 , function(datems) {
                                     var d = new Date(); d.setTime(datems); return d;
                                 });
            },
            /**
             * Sets the alarm date.
             *
             * @method setDate
             * @param date {Date}
             * @param callback (optional) {Function()} To be called after the date is set.
             */
            setDate: function(date, callback) {
                this._proxy.call('setDate', [date.getTime(), callback]);
            },

            /**
             * Retrieves the alarm's enabled state.
             *
             * The property specifies whether the alarm is enabled or not.
             * Disable dalarms are not scheduled. The default value is true
             *
             * @method enabled
             * @param callback {Function(Boolean)}
             */
            enabled: function(callback) {
                this._proxy.call('enabled', [], callback);
            },
            /**
             * Sets the alarm's enabled state.
             *
             * @method setEnabled
             * @param enabled {Boolean}
             * @param callback (optional) {Function()} To be called after the enabled state is set.
             */
            setEnabled: function(enabled, callback) {
                this._proxy.call('setEnabled', [enabled, callback]);
            },

            /**
             * Retrieves the alarm message.
             *
             * The property holds the message string which will be displayed when the alarm is triggered.
             * The default value is the localized "Alarm" text
             *
             * @method message
             * @param callback {Function(String)}
             */
            message: function(callback) {
                this._proxy.call('message', [], callback);
            },
            /**
             * Sets the alarm message.
             *
             * @method setMessage
             * @param message {String}
             * @param callback (optional) {Function()} To be called after the message is set.
             */
            setMessage: function(message, callback) {
                this._proxy.call('setMessage', [message, callback]);
            },

            /**
             * Retrieves the alarm sound.
             *
             * The property holds the alarm's sound to be played when the alarm is triggered.
             * An empty url will mean to play the default sound.
             *
             * The default value is an empty url.
             *
             * @method sound
             * @param callback {Function(String)}
             */
            sound: function(callback) {
                this._proxy.call('sound', [], callback);
            },
            /**
             * Sets the alarm sound.
             *
             * @method setSound
             * @param sound {String}
             * @param callback (optional) {Function()} To be called after the sound is set.
             */
            setSound: function(sound, callback) {
                this._proxy.call('setSound', [sound, callback]);
            },

            /**
             * Retrieves the alarm status.
             *
             * The property holds the status of the last performed operation
             *
             * @method status
             * @param callback {Function(String)}
             */
            status: function(callback) {
                this._proxy.call('status', [], callback);
            },

            /**
             * Retrieves the alarm type.
             *
             * The property holds the type of the alarm.
             * The default value is AlarmType.OneTime
             *
             * @method type
             * @param callback {Function(AlarmType)}
             */
            type: function(callback) {
                this._proxy.call('type', [], callback);
            },
            /**
             * Sets the alarm type.
             *
             * @method setType
             * @param type {AlarmType}
             * @param callback (optional) {Function()} To be called after the type is set.
             */
            setType: function(type, callback) {
                this._proxy.call('setType', [type, callback]);
            },

            /**
             * Retrieves the alarm day of the week.
             *
             * The property holds the days of the week the alarm is scheduled.
             * This property can have only one day set for one time alarms and multiple days for repeating alarms.
             *
             * @method daysOfWeek
             * @param callback {Function(AlarmType)}
             */
            daysOfWeek: function(callback) {
                this._proxy.call('daysOfWeek', [], callback);
            },
            /**
             * Sets the alarm day of the week.
             *
             * @method setDaysOfWeek
             * @param daysOfWeek {AlarmDayOfWeek}
             * @param callback (optional) {Function()} To be called after the day of the week is set.
             */
            setDaysOfWeek: function(daysOfWeek, callback) {
                this._proxy.call('setDaysOfWeek', [daysOfWeek, callback]);
            },

            // methods

            /**
             * Cancels a given Alarm.
             *
             * @method cancel
             */
            cancel: function() {
                this._proxy.call('cancel', []);
            },

            /**
             * Resets a given Alarm.
             *
             * @method reset
             */
            reset: function() {
                this._proxy.call('reset', []);
            },

            /**
             * Saves the alarm as a system wide alarm with the parameters previously set.
             *
             * @method save
             */
            save: function() {
                this._proxy.call('save', []);
            },

            // extras

            /**
             * Destroys the remote object. This proxy object is not valid anymore.
             *
             * @method destroy
             */
            destroy: function() {
                this._proxy.call('destroy', []);
            },
        };

        function _constructorFromName(className) {
            var constructorPerName = {
                "Alarm": Alarm,
            };
            return className in constructorPerName
                    ? constructorPerName[className]
                    : null;
        };

    /**
     * The AlarmApi object

     * @class AlarmApi
     * @constructor
     * @example

           var date = new Date();
           <set a valid date in the future>

           var api = external.getUnityObject('1.0');
           api.AlarmApi.api.createAndSaveAlarmFor(
              date,
              api.AlarmApi.AlarmType.OneTime,
              api.AlarmApi.AlarmDayOfWeek.AutoDetect,
              "alarm triggered",
              function(errorid) {
                  console.log(api.AlarmApi.api.errorToMessage(errorid));
              });
     */
        return {
            /**
               Enumeration of the available types of Alarm.

                 Values:

                   OneTime: The alarm occurs only once

                   Repeating: The alarm is a repeating one,
                       either daily, weekly on a given day
                       or on selected days

               @static
               @property AlarmType {Object}

               @example

                   var api = external.getUnityObject('1.0');
                   var alarmtype = api.AlarmApi.AlarmType;
                   // use alarmtype.OneTime or alarmtype.Repeating
             */
            AlarmType: {
                // The alarm occurs only once.
                OneTime: "OneTime",

                // The alarm is a repeating one, either daily, weekly on a given day or on selected days.
                Repeating: "Repeating",
            },

            /**
               Flags for the week days an Alarm should be triggered.

                 Values:

                   Monday: The alarm will kick on Mondays

                   Tuesday: The alarm will kick on Tuesdays

                   Wednesday: The alarm will kick on Wednesday

                   Thursday: The alarm will kick on Thursday

                   Friday: The alarm will kick on Friday

                   Saturday: The alarm will kick on Saturday

                   Sunday: The alarm will kick on Sunday

                   AutoDetect: The alarm day will be detected
                     from the alarm date.

               @static
               @property AlarmDayOfWeek {Integer}

               @example

                   var api = external.getUnityObject('1.0');
                   var dayofweek = api.AlarmApi.AlarmDayOfWeek;
                   // use dayofweek.Monday or/and dayofweek.Tuesday, etc.
             */
            AlarmDayOfWeek: {
                // The alarm will kick on Mondays.
                Monday: 1,

                // The alarm will kick on Tuesdays.
                Tuesday: 2,

                // The alarm will kick on Wednesdays.
                Wednesday: 4,

                // The alarm will kick on Thursdays.
                Thursday: 8,

                // The alarm will kick on Fridays.
                Friday: 16,

                // The alarm will kick on Saturdays.
                Saturday: 32,

                // The alarm will kick on Sundays.
                Sunday: 64,

                // The alarm day will be detected from the alarm date.
                AutoDetect: 128,
            },

            /**
             Error ids returned during AlarmApi calls.

               Values:

                 NoError: Successful operation completion

                 InvalidDate: The date specified for the alarm was invalid

                 EarlyDate: The date specified for the alarm is an earlier
                     date than the current one

                 NbDaysOfWeek: The daysOfWeek parameter of the alarm was not specified

                 OneTimeOnMoreDays: The one-time alarm was set to be kicked in several days

                 InvalidEvent: The alarm event is invalid

                 AdaptationError: The error occurred in alarm adaptation layer.
                     Adaptations may define additional behind this value

             @static
             @property AlarmError {Integer}

             @example
                 var date = new Date();
                 <set a valid date in the future>

                 var api = external.getUnityObject('1.0');
                 api.AlarmApi.api.createAndSaveAlarmFor(
                   date,
                   api.AlarmApi.AlarmType.OneTime,
                   api.AlarmApi.AlarmDayOfWeek.AutoDetect,
                   "alarm triggered",
                   function(errorid) {
                     console.log(api.AlarmApi.api.errorToMessage(errorid));
                   });
             */
            AlarmError: {
                // Successful operation completion
                NoError: 0,

                // The date specified for the alarm was invalid
                InvalidDate: 1,

                // The date specified for the alarm is an earlier date than the current one
                EarlyDate: 2,

                // The daysOfWeek parameter of the alarm was not specified
                NoDaysOfWeek: 3,

                // The one-time alarm was set to be kicked in several days
                OneTimeOnMoreDays: 4,

                // The alarm event is invalid
                InvalidEvent: 5,

                // The error occurred in alarm adaptation layer. Adaptations may define additional behind this value
                AdaptationError: 6,
            },

            /**
             * Creates a Alarm object.
             *
             * @method createAlarm
             * @param callback {Function(Alarm)} Function called with the created Alarm.
             */
            createAlarm: function(callback) {
                backendBridge.call('Alarm.createAlarm'
                                   , []
                                   , callback);
            },

            api: {
                /**
                 * Creates and saves a new alarm.
                 *
                 * @method api.createAndSaveAlarmFor
                 * @param date {Date} date at which the alarm is to be triggered.
                 * @param type {AlarmType} type of the alarm.
                 * @param daysOfWeek {AlarmDayOfWeek} days of the week the alarm is scheduled.
                 * @param message {String} Message to be displayed when the alarm is triggered.
                 * @param callback (optional) {Function(AlarmError)} Function to be called when the alarm has been saved.
                 */
                createAndSaveAlarmFor: function(date, type, daysOfWeek, message, callback) {
                    backendBridge.call('Alarm.createAndSaveAlarmFor'
                                       , [date.getTime(), type, daysOfWeek, message, callback]);
                },

                /**
                 * Returns a message adapted to the given error id.
                 *
                 * @method api.errorToMessage
                 * @param error {AlarmError} error id.
                 */
                errorToMessage: function(error) {
                    var messagePerError = [
                        "Successful operation completion",
                        "The date specified for the alarm was invalid",
                        "The date specified for the alarm is an earlier date than the current one",
                        "The daysOfWeek parameter of the alarm was not specified",
                        "The one-time alarm was set to be kicked in several days",
                        "The alarm event is invalid",
                        "The error occurred in alarm adaptation layer"
                      ];
                    return error < messagePerError.length
                            ? messagePerError[error]
                            : "Invalid error id";
                },
            },

            // Internal

            /**
             * @private
             *
             */
            createObjectWrapper: function(objectType, objectId, content) {
                var Constructor = _constructorFromName(objectType);
                return new Constructor(objectId, content);
            },
        };
    };