<?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 reference

  PUBLIC "-//OASIS//DTD DITA Reference//EN" "reference.dtd">

<reference id="GUID-7BCA8B7A-E250-5452-9837-26C60F71F14F" xml:lang="en"><title>Alarm

Properties Reference</title><prolog><metadata><keywords/></metadata></prolog><refbody>

<section><p>This section provides a summary of mandatory and optional Alarm

properties that must be set before adding an alarm to the Alarm Server. </p> <p>The

following Alarm property is <i>mandatory</i>: </p> </section>

<table id="GUID-A097D4DD-A8FE-5E79-B90B-770D17104932">

<tgroup cols="2"><colspec colname="col0" colwidth="0.43*"/><colspec colname="col1" colwidth="1.57*"/>

<thead>

<row>

<entry><p><b>Property</b></p></entry>

<entry><p><b>Description</b></p></entry>

</row>

</thead>

<tbody>

<row>

<entry><p> <b>NextDueTime</b>  </p> </entry>

<entry><p>Indicates the time that the alarm will expire. </p><p>The <codeph>KErrArgument</codeph> error

is returned when an alarm is added without the next due time being set. </p></entry>

</row>

</tbody>

</tgroup>

</table>

<section><p> </p> <p>The following Alarm properties are <i>optional</i>: </p> </section>

<table id="GUID-E40B0108-874F-5CC6-9406-D3A9EB487FC1">

<tgroup cols="2"><colspec colname="col0" colwidth="0.58*"/><colspec colname="col1" colwidth="1.42*"/>

<thead>

<row>

<entry><p><b>Property</b></p></entry>

<entry><p><b>Description</b></p></entry>

</row>

</thead>

<tbody>

<row>

<entry><p> <b>RepeatDefinition</b>  </p> </entry>

<entry><p>Indicates the alarm repeat definition. </p><ul>

<li id="GUID-D64B190D-D97A-58CD-91B3-44FE3637FA71"><p> <b>RepeatOnce</b> –

The alarm expires once and then deleted from the Alarm Server. This is the

default value. </p> </li>

<li id="GUID-32C0FAF5-96F9-5DC9-AFDD-29FB67F51417"><p> <b>Next24hours</b> –

The alarm is scheduled to notify at the given time, within the next 24 hours.

The alarm is then deleted from the Alarm Server. </p> </li>

<li id="GUID-13FCA81D-FABF-5585-B093-2D9FC405721B"><p> <b>Daily</b> – The

alarm repeats every day at the same time. </p> </li>

<li id="GUID-C0FF139B-03C5-5756-B0A3-ED0C496E8A81"><p> <b>WorkDay</b> – The

alarm repeats on workdays at the same time. </p> </li>

<li id="GUID-33AC43FC-412E-557C-A9FB-B2063FDEF9EC"><p> <b>Weekly</b> – The

alarm repeats at the same time, on the same day, every week. </p> </li>

<li id="GUID-92BD2CFB-033C-5B3D-B1F5-D60987804814"><p> <b>DailyOnGivenDays</b> –

The alarm repeats at the same time on the specified days of the week. </p> </li>

</ul></entry>

</row>

<row>

<entry><p> <b>Message</b>  </p> </entry>

<entry><p>Indicates the message displayed by the UI when the alarm expires.

The maximum allowable length of the message is defined by <codeph>KMaxAlarmMessageLength</codeph>.

The <codeph>KErrArgument</codeph> error is returned when an alarm is added

to the server with a message exceeding this length. </p></entry>

</row>

<row>

<entry><p> <b>SoundName </b>  </p> </entry>

<entry><p>Indicates the name of the sound file that must be played when the

alarm expires. The maximum allowable length of the sound name is defined by <codeph>KMaxAlarmSoundNameLength</codeph>.

The <codeph>KErrArgument</codeph> error is returned when an alarm is added

with a sound name exceeding this length. The Alarm Server does not check the

validity of the sound name. The UI must handle the scenarios where neither

sound name is provided nor valid. </p></entry>

</row>

<row>

<entry><p> <b>Category</b>  </p> </entry>

<entry><p>It is an UID provided by a client to group the alarms registered

with the Alarm Server. This allows the Alarm Server to perform specific operations

on particular group of alarms, on behalf of the client. </p></entry>

</row>

<row>

<entry><p> <b>Characteristics</b>  </p> </entry>

<entry><p>A flag that indicates whether: </p><ul>

<li id="GUID-BD57C6CE-B347-5942-90A9-3BE3C04D2ABB"><p>the caller is notified

when the alarm expires and </p> </li>

<li id="GUID-6ABFC447-6C24-51E6-973A-4994297D5C16"><p>the UI is asked to display

an alarm dialog when the alarm notifies. </p> </li>

</ul><p>By default, the caller is not notified when an alarm expires and the

UI is requested to display an alarm dialog when the alarm expires. </p></entry>

</row>

<row>

<entry><p> <b> DayOrTimed</b>  </p> </entry>

<entry><p>A flag that indicates whether the alarm is associated with a day

or timed appointment. The default is Timed. This flag is for the client’s

use only, and is not used by the Alarm Server. </p></entry>

</row>

<row>

<entry><p> <b>WakeUp</b>  </p> </entry>

<entry><p>A flag that indicates whether the device must be made activate at

the next due time of this alarm. By default, alarms do not cause a device

wakeup. </p></entry>

</row>

<row>

<entry><p> <b>Continuous</b>  </p> </entry>

<entry><p>A flag that indicates whether or not the alarm must play continuously

when it expires. If this flag is set, it overrides the alarm play intervals. </p></entry>

</row>

</tbody>

</tgroup>