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.