Alarm Server Functionality

There are two methods to add or 'queue' an alarm to the Alarm Server. The first method simply allocates a unique identifier (a TAlarmId object) for the alarm, adds the alarm to the queue, and returns. See RASCliSession::AlarmAdd().

In the second method the server allocates an ID to the alarm, then makes an asynchronous request to add it to the queue. When the alarm expires, or is cancelled, the Alarm Server notifies the client by completing the outstanding request, the TRequestStatus object. See RASCliSession::AlarmAddWithNotification().

When adding a new alarm to the Alarm Server some validation is required to ensure the integrity of the Alarm Server. Therefore, no alarm which is to be added may be session-specific and have a repeat definition. The exception is alarms that expire after a single repeat.

Additionally, if an alarm has a repeat definition of TAlarmRepeatDefinition::EAlarmRepeatDefintionRepeatWorkday, the system-wide (TLocale-based) work days must first be defined.

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.

When a Session Alarm has been queued with the Alarm Server (see RASCliSession::AlarmAddWithNotification()) the alarm is allocated an ID. The information is then written back to the client-side representation of the alarm. This prompts clients to ensure that the TASShdAlarm object has an established lifetime. Such is the case for a TASShdAlarm object declared as a data member within the scope of a class that has been allocated on the heap.

Once added to the Alarm Server, a Session Alarm can be cancelled using the RASCliSession::AlarmNotificationCancelAndDequeue() method. This requires that the ID of the alarm object be passed to the Alarm Server so that it can correctly identify the Session Alarm to be destroyed. The only restriction on the number of alarms is available memory.

RASCliSession::SetAlarmStatus() changes the status of the specified alarm to ‘enabled’ or ‘disabled’.

Alarms can by grouped by category and given a UID, using TAlarmCategory. The Alarm Server ignores categories but an application can use them to identify which alarms it has set.

RASCliSession::NotifyChange() enables client notification when alarm settings change, and when the next alarm time is calculated. The method accepts two parameters:

• TRequestStatus is the object that is to be signalled. When returned the object contains a TAlarmChangeEvent enumeration value that holds information such as an alarm’s expiry, sound or deletion states.

• TAlarmId is an alarm identifier relating to the type of event that took place. If the type of event that occurred relates to a particular alarm, this object is populated with that alarm's identifier.

The API RASCliSession::AlarmDelete() deletes an alarm from the Alarm Server and returns KErrNone if successful.

To explicitly delete all orphaned alarms these must first be identified (as shown earlier) then deleted manually.