<?xml version="1.0" encoding="utf-8"?>
<!-- Copyright (c) 2007-2010 Nokia Corporation and/or its subsidiary(-ies) All rights reserved. -->
<!-- This component and the accompanying materials are made available under the terms of the License 
"Eclipse Public License v1.0" which accompanies this distribution, 
and is available at the URL "http://www.eclipse.org/legal/epl-v10.html". -->
<!-- Initial Contributors:
    Nokia Corporation - initial contribution.
Contributors: 
-->
<!DOCTYPE task
  PUBLIC "-//OASIS//DTD DITA Task//EN" "task.dtd">
<task id="GUID-70CD9D74-8592-45F2-A91F-AD34ED93CB3D" xml:lang="en"><title>Adding
an Alarm</title><prolog><metadata><keywords/></metadata></prolog><taskbody>
<context>       <p>You can add or queue an alarm to the Alarm Server either
by Synchronous or Asynchronous method:</p><ul>
<li><p><b>Synchronous method</b> (<codeph>RASCliSession::AlarmAdd</codeph>)
- This method allocates a unique identifier (a <codeph>TAlarmId</codeph> object)
for the alarm, adds the alarm to the queue, and returns. Follow the steps
given below to add alarm synchronously:  </p><ol>
<li id="GUID-0FA7FE18-3C1D-42D9-A24A-F0EFA22A916D"><p>Create an alarm object.</p><codeblock xml:space="preserve">TASShdAlarm alarm;</codeblock></li>
<li id="GUID-BBCA5506-2C84-44BE-AE4E-D6595E01F937"><p>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 <xref href="GUID-7BCA8B7A-E250-5452-9837-26C60F71F14F.dita">Alarm Properties</xref>.</p><codeblock xml:space="preserve">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;</codeblock></li>
<li id="GUID-6084D3F8-4AAE-4183-A8AF-8A8248906B58"><p>Add the alarm object to Alarm Server.</p><codeblock xml:space="preserve">TInt ret = TheAlarmServerSession.AlarmAdd( alarm );</codeblock></li>
<li id="GUID-84B488F6-6752-40F2-8E1C-D1940A1457A1"><p>Retrieve the alarm ID.</p><codeblock xml:space="preserve">TAlarmId alarmId = alarm.Id();</codeblock></li>
</ol></li>
<li><p><b>Asynchronous method</b> (<codeph>RASCliSession::AlarmAddWithNotification</codeph>)
- 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 <codeph>TRequestStatus</codeph> object.</p></li>
</ul><p>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 <codeph>TAlarmRepeatDefinition::AlarmRepeatDefintionRepeatOnce</codeph>.
 </p><note> If an alarm is set having a repeat definition of <codeph>TAlarmRepeatDefinition::EAlarmRepeatDefintionRepeatWorkday</codeph>,
the system-wide (<codeph>TLocale</codeph>-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 <codeph>TAlarmStatus::EAlarmStatusDisabled</codeph>.
When a change in the workday is detected (caused by a change in locale), the
alarm will be enabled.</note><p>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.</p></context>
</taskbody></task>