Alarm server functionality

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 alarm’s 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.