![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
The alarm server client side API provides access to alarm services for applications like Time and Agenda.
The following sections provide an overview of the different types of alarms, a description of the possible alarm states, an overview of the API functionality, and a list of miscellaneous alarm server issues.
Section Contents
The alarm server supports three main types of alarms; clock alarms, session alarms and orphaned alarms. There are several other categories of alarms, but these are sub-categories of the main types.
Each of the alarm types is discussed in detail in the following sections.
The alarm server can store up to 8 clock alarms which, once set, are independent of the client that set them. Because they are managed solely by the server, they are serviced even if the application that entered them is not running.
Any client can set any of the clock alarms. In ER5 these are accessible to the end user through the Time application.
Session alarms are handled on behalf of a session with the alarm server, and fulfil the requirements of PIM applications. Each session is able to set only one session alarm; the server notifies the session when it should set its next alarm.
When a session disconnects from the server, its session alarm is cancelled. The session must specifically orphan its alarm to keep it in the pending alarm queue after disconnection see topic below for discussion of orphan alarms.
There are two types of session alarms:
Timed session alarms are those which belong to timed events events in a PIM application with a defined start and finish time. The alarm notification time is specified as an offset from the event start time, so that when the event time changes, so to does the alarm time.
Untimed session alarms, or day alarms, are those which belong to untimed events events which dont have a specified start/finish time. This type of alarm stores an actual activation time rather than an offset to an event time.
A session can orphan its session alarm, and thereby relinquish control of it to the alarm server. The alarm is then stored in the servers orphaned alarm array. It has no session owner, and no session is notified when the alarm is due.
When a session closes its connection to the alarm server, it may choose to orphan its session alarm thereby allowing the alarm to be serviced after the session closes. An application can regain control of an orphaned alarm by setting an alarm with the same parameters, e.g. time, date, etc.
After orphaning an alarm, a session is allocated enough memory for another session alarm which it can also orphan. Sessions can orphan as many alarms as memory allows. The server removes all orphaned alarms when the system time is changed or the alarm server is re-started.
Snoozed alarms are those which have been deferred after activation. When any alarm is snoozed, it is also orphaned.
Other alarm categories that are mentioned in this documentation are:
Next/pending alarms are those which are to activate in the future irrespective of type.
Awaiting acknowledgement alarms are those for which the alarm time has been reached, or which were initially set at some time in the past. Silenced alarms are alarms awaiting acknowledgement in which the sound notification has been cancelled.
Acknowledged/review alarms are those which have been acknowledged the server maintains these in a review list until it is cleared, or until they are pushed out of the list by new acknowledged alarms. The server clears the review list when the system time is changed or the alarm server is re-started.
The diagram below shows an alarm state diagram.
Session, clock and orphaned alarms that are set in the future are said to be pending. Alarms in this state can be cancelled. If they are orphaned or session alarms then they are also removed by the server if the system time changes. When the alarm time is reached, the alarm moves to another state, where it awaits acknowledgement.
If an alarm is set in the past, or if its alarm time is due, its state is moved to awaiting acknowledgement. In this state the user has been notified that an alarm is due, and the alarm is in the server awaiting acknowledgement list. This list can contain 8 unacknowledged alarms; if more alarms arrive then the oldest alarms in the list are removed.
Alarms may be snoozed, in which case they return to the pending state. If an alarm is acknowledged, then it moves to the review state.
Alarms which have been acknowledged are placed in the server review list. The list will automatically drop older review alarms as new ones are entered. It is also cleared if the system time is changed.
Section Contents
If a session is able to connect to the alarm server, the client can set any of the clock alarms and a single session alarm, and be guaranteed that the alarm will not fail due to lack of memory.
If an alarm is set with identical parameters to an orphaned alarm, the session takes over as that alarms owner. This allows applications like Agenda to regain control over their orphaned alarms when they are re-started.
The alarm time can be set with the accuracy of a minute. If an alarm is set in the past, the user is notified immediately.
A session alarm must be cancelled and set again in order to change any of its parameters cancelling removes the alarm from the pending alarm queue.
Session alarms can also be orphaned, thereby transferring responsibility for the alarm from the client to the alarm server. Orphaned alarms can be deleted by any application, and are removed from the server if the system time is changed.
Clock alarms are changed by over-writing previous information. To delete or disable a clock alarm, the clock alarm array is obtained from the server and the desired operation is performed on the array entries.
Clients can obtain alarm information from the server using several methods. Firstly, they can query the server for alarm information by ID for a specific alarm (irrespective of type), for a clock alarm, for a pending alarm, or for a session alarm. If no ID is specified, then this method returns the first alarm in the specified category the alarm with the alarm time closest to the current time.
Clients can also populate an array with alarms of a specified type from the alarm server. Using this method allows clients to obtain arrays of pending alarms, review alarms, orphan alarms or snoozed alarms.
Alarm server sessions are notified through an asynchronous notify on change function. The server notifies its sessions if the alarm settings change and when the client must calculate the next alarm time.
The API allows clients to turn the sound system on or off, and to turn it off for a set period, and then to automatically turn it back on again. This quiet period applies to all alarm server alarms, regardless of the setting application.
Section Contents
All session alarm settings are lost when the system time is changed. The sessions are notified to calculate the time of their next alarm, and it is up to the client to do this. The client may keep the alarms at the same time with respect to the system time, it may change the alarm times to occur at the time it would have if the system time had not been changed, or it may change the alarm time to suit some other requirement.
If an alarm is queued in the past, it is sent for immediate notification. This allows the client to immediately set another alarm. The list of review alarms is also cleared to prevent the same alarm appearing twice in the review list when the time is changed backwards.
The way in which the alarm server responds to daylight saving time (DST) changes depends on the method used to change the time.
If the DST is changed through the daylight savings time zone, e.g. the Summer times dialog in the Time application, then the alarm server will clear its pending alarm queues and get its sessions to send their next alarm. If time is changed forward, alarms set for the intervening period will not be set. If time is changed back, the same alarm will be repeated.
If the time is manually changed to reflect the changeover to/from DST, this is an ordinary change in system time. The alarm server does not clear its pending alarm queues. If time is changed forward, any alarm set for the intervening period will be sent for user acknowledgement immediately. If time is changed back, there is a period (until time "catches up") when no alarms are due.
There is a limit to the number of alarms kept in the awaiting acknowledgement list which prevents a build up of alarms when the user is not present to acknowledge them. This list can contain 8 alarm entries.
The server has been designed to reduce the chance of alarm notifications failing due to an out of memory error. Memory for an alarm setting is allocated when a client connects to the server. This guarantees that the server can set the alarm, so long as the client is connected the memory is de-allocated when the client disconnects.
Any session can set any number of orphaned alarms. When an alarm is orphaned, memory is allocated for another session alarm. The process of orphaning an alarm can therefore fail due to lack of memory.
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |