Adding an Alarm

Context

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.

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.