Symbian
Symbian OS Library

SYMBIAN OS V9.3

[Index] [Spacer] [Previous] [Next]



Alarm Server Functionality


Adding an Alarm

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.

[Top]


Asynchronous Session Alarms

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.

[Top]


Enabling and Disabling an Alarm

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

[Top]


Setting an Alarm by Category

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.

[Top]


Notification

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

[Top]


Deleting an Alarm

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.