Adding an Alarm

You can add or queue an alarm to the Alarm Server either by Synchronous or Asynchronous method:

Synchronous method (RASCliSession::AlarmAdd) - This method allocates a unique identifier (a TAlarmId object) for the alarm, adds the alarm to the queue, and returns. Follow the steps given below to add alarm synchronously:
1. Create an alarm object.
```
TASShdAlarm alarm;
```
2. Set the alarm properties such as Category, Repeat Definition, Message, Next Due Time and Sound Name. For more information on the alarm properties, refer to Alarm Properties.
```
alarm.Category() = KASCliCategoryClock;
alarm.RepeatDefinition() = EAlarmRepeatDefintionRepeatDaily;
_LIT( KAlarmTestInit, "This is an alarm message - alarm 1" );
alarm.Message() = KAlarmTestInit;alarm.NextDueTime().HomeTime();
alarm.NextDueTime() += TTimeIntervalMinutes( 1 );
_LIT( KAlarmTestSoundName, "Arf Arf Woop" );
alarm.SoundName() = KAlarmTestSoundName;
```
3. Add the alarm object to Alarm Server.
```
TInt ret = TheAlarmServerSession.AlarmAdd( alarm );
```
4. Retrieve the alarm ID.
```
TAlarmId alarmId = alarm.Id();
```
Asynchronous method (RASCliSession::AlarmAddWithNotification) - The steps are similar to the Synchronous method, except, when either the alarm expires or is cancelled, the Alarm Server notifies the client by completing the outstanding request, the TRequestStatus object.

When adding a new alarm to the Alarm Server, some validation is required to ensure the integrity of the Alarm Server. Therefore, no alarm that is to be added must be session-specific and have a repeat definition other than TAlarmRepeatDefinition::AlarmRepeatDefintionRepeatOnce.

Note: If an alarm is set having a repeat definition of TAlarmRepeatDefinition::EAlarmRepeatDefintionRepeatWorkday, the system-wide (TLocale-based) work days must be defined first. If the system-wide workdays are not defined, the alarm is added to the Alarm Server queue with status as TAlarmStatus::EAlarmStatusDisabled. When a change in the workday is detected (caused by a change in locale), the alarm will be enabled.

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.

Parent topic: Using Alarm Server