1 <?xml version="1.0" encoding="utf-8"?>

     2 <!-- Copyright (c) 2007-2010 Nokia Corporation and/or its subsidiary(-ies) All rights reserved. -->

     3 <!-- This component and the accompanying materials are made available under the terms of the License 

     4 "Eclipse Public License v1.0" which accompanies this distribution, 

     5 and is available at the URL "http://www.eclipse.org/legal/epl-v10.html". -->

     6 <!-- Initial Contributors:

     7     Nokia Corporation - initial contribution.

     8 Contributors: 

     9 -->

    10 <!DOCTYPE task

    11   PUBLIC "-//OASIS//DTD DITA Task//EN" "task.dtd">

    12 <task id="GUID-70CD9D74-8592-45F2-A91F-AD34ED93CB3D" xml:lang="en"><title>Adding

    13 an Alarm</title><prolog><metadata><keywords/></metadata></prolog><taskbody>

    14 <context>       <p>You can add or queue an alarm to the Alarm Server either

    15 by Synchronous or Asynchronous method:</p><ul>

    16 <li><p><b>Synchronous method</b> (<codeph>RASCliSession::AlarmAdd</codeph>)

    17 - This method allocates a unique identifier (a <codeph>TAlarmId</codeph> object)

    18 for the alarm, adds the alarm to the queue, and returns. Follow the steps

    19 given below to add alarm synchronously:  </p><ol>

    20 <li id="GUID-0FA7FE18-3C1D-42D9-A24A-F0EFA22A916D"><p>Create an alarm object.</p><codeblock xml:space="preserve">TASShdAlarm alarm;</codeblock></li>

    21 <li id="GUID-BBCA5506-2C84-44BE-AE4E-D6595E01F937"><p>Set the alarm properties such as Category, Repeat Definition, Message,

    22 Next Due Time and Sound Name. For more information on the alarm properties,

    23 refer to <xref href="GUID-7BCA8B7A-E250-5452-9837-26C60F71F14F.dita">Alarm Properties</xref>.</p><codeblock xml:space="preserve">alarm.Category() = KASCliCategoryClock;

    24 alarm.RepeatDefinition() = EAlarmRepeatDefintionRepeatDaily;

    25 _LIT( KAlarmTestInit, "This is an alarm message - alarm 1" );

    26 alarm.Message() = KAlarmTestInit;alarm.NextDueTime().HomeTime();

    27 alarm.NextDueTime() += TTimeIntervalMinutes( 1 );

    28 _LIT( KAlarmTestSoundName, "Arf Arf Woop" );

    29 alarm.SoundName() = KAlarmTestSoundName;</codeblock></li>

    30 <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>

    31 <li id="GUID-84B488F6-6752-40F2-8E1C-D1940A1457A1"><p>Retrieve the alarm ID.</p><codeblock xml:space="preserve">TAlarmId alarmId = alarm.Id();</codeblock></li>

    32 </ol></li>

    33 <li><p><b>Asynchronous method</b> (<codeph>RASCliSession::AlarmAddWithNotification</codeph>)

    34 - The steps are similar to the Synchronous method, except, when either the

    35 alarm expires or is cancelled, the Alarm Server notifies the client by completing

    36 the outstanding request, the <codeph>TRequestStatus</codeph> object.</p></li>

    37 </ul><p>When adding a new alarm to the Alarm Server, some validation is required

    38 to ensure the integrity of the Alarm Server. Therefore, no alarm that is to

    39 be added must be session-specific and have a repeat definition other than <codeph>TAlarmRepeatDefinition::AlarmRepeatDefintionRepeatOnce</codeph>.

    40  </p><note> If an alarm is set having a repeat definition of <codeph>TAlarmRepeatDefinition::EAlarmRepeatDefintionRepeatWorkday</codeph>,

    41 the system-wide (<codeph>TLocale</codeph>-based) work days must be defined

    42 first. If the system-wide workdays are not defined, the alarm is added to

    43 the Alarm Server queue with status as <codeph>TAlarmStatus::EAlarmStatusDisabled</codeph>.

    44 When a change in the workday is detected (caused by a change in locale), the

    45 alarm will be enabled.</note><p>The alarm time can be set with the accuracy

    46 of a minute. If an alarm is set in the past, the user is notified immediately.</p></context>

    47 </taskbody></task>