Additional System Services

Using Additional System Services

The following code example adds an alarm set to execute in five minutes:

AddAlarm("Alarm1:MyApp:MySig", Time()+5,

["Title String","Message String"], nil, nil);

The first argument is the alarm key (which this function call returns). The second is
when the alarm is to execute. The third is an array of strings to use as arguments to
the

AlarmUser

function that displays the alarm slip. If a three-element array is

passed in as

AddAlarm

's third argument, these array elements are used as

arguments to the

Notify

function that is used to display the slip. The fourth and

fifth arguments are a callback function, and its arguments, which is executed when
the alarm executes.

If an installed alarm has the key specified in the call to

AddAlarm

, the installed

alarm is removed, and the new alarm is installed.

After an alarm executes, it is made available for garbage collection; thus, alarms
that have already executed may no longer exist. For this reason, it is unwise to store
references to alarms or try to manipulate them by any means other than the
interface the system provides.

Obtaining Information about Alarms

17

The

GetAlarm

function returns a frame with information about an alarm. The

alarm is identified by its key. The frame returned has the following slots:

key

The alarm key.

time

The time at which the alarm is to execute.

notifyArgs

The array of arguments to pass to

Notify

or

AlarmUser

.

callBackFunc

The function object to execute, or

nil

.

callBackParams

Array of arguments to

callBackFunc

, or

nil

.

This frame may contain other slots; do not rely on the values (or future existence)
of these slots. You must also not modify this frame in any way.

Retrieving Alarm Keys

17

The

GetAppAlarmKeys

function returns an array containing the alarm keys of all

alarms installed by an application. These keys can be used to pass to the

AddAlarm

,

GetAlarm

, and

RemoveAlarm

functions.

This function relies on all of your application's alarms ending with the same suffix.
For this reason it is important for all alarms created by a particular application to
use alarm keys ending with the same suffix.