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 concept

    11   PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd">

    12 <concept id="GUID-12A32F8E-0C53-5311-9B2B-8E0EA373ED08" xml:lang="en"><title>Types

    13 of Alarm</title><prolog><metadata><keywords/></metadata></prolog><conbody>

    14 <p>This section explains the various types of alarms that are handled by the

    15 Alarm Server. </p>

    16 <p>Session alarms and Non-Session alarms are handled by the Alarm Server after

    17 creating a session using <xref href="GUID-3598EAEE-0EF4-35A2-89E5-F3B2555B1AB4.dita"><apiname>RASCliSession</apiname></xref> function. </p>

    18 <section><title>Session Alarms </title> <p>The alarms that are removed from

    19 the alarm queue when the session disconnects are referred as Session Alarms.

    20 Session alarms can either be synchronous or asynchronous. </p> <p>The session-based

    21 alarms are defined by setting an alarm’s characteristics flag as <xref href="GUID-20A42BF7-A0F5-3177-9592-E3AE097B4CF2.dita#GUID-20A42BF7-A0F5-3177-9592-E3AE097B4CF2/GUID-EFA80EA7-423D-3B8E-A4CF-CD34325506E6"><apiname>TAlarmCharacteristics::EAlarmCharacteristicsSessionSpecific</apiname></xref>. </p> <p>Session Alarms are handled on behalf of a session with the Alarm Server.

    22 Each session is allowed to set only one Session Alarm. The server informs

    23 the session when to set the next alarm. If the session disconnects, the Session

    24 Alarm is cancelled. </p> <p>The Session Alarm is completed when the alarm

    25 expires, is cancelled, or a timing error occurs. </p> <p> <b>NOTE</b>: If

    26 the client session is closed before the alarm has expired, the Alarm Server

    27 automatically dequeues the alarm. </p> <p><b>Synchronous Session Alarms</b> </p> <p>To

    28 add a session alarm to the queue synchronously, use <xref href="GUID-3598EAEE-0EF4-35A2-89E5-F3B2555B1AB4.dita#GUID-3598EAEE-0EF4-35A2-89E5-F3B2555B1AB4/GUID-45B0A300-B65E-3503-92AF-441DB44CD5CD"><apiname>RASCliSession::AlarmAdd()</apiname></xref>. </p> <p><b>Asynchronous

    29 Session Alarms</b> </p> <p>To add a session alarm to the queue asynchronously,

    30 use <xref href="GUID-3598EAEE-0EF4-35A2-89E5-F3B2555B1AB4.dita#GUID-3598EAEE-0EF4-35A2-89E5-F3B2555B1AB4/GUID-D9A2FDAA-D303-349D-B099-A770021720CC"><apiname>RASCliSession::AlarmAddWithNotification()</apiname></xref>. If a client

    31 decides to cancel a Session Alarm, it must use <xref href="GUID-3598EAEE-0EF4-35A2-89E5-F3B2555B1AB4.dita#GUID-3598EAEE-0EF4-35A2-89E5-F3B2555B1AB4/GUID-C8FAE669-D389-3921-8FBF-2D04F90B6CA6"><apiname>RASCliSession::AlarmNotificationCancelAndDequeue()</apiname></xref>.

    32 This requires that the ID of the alarm object be passed to the Alarm Server,

    33 so that it can correctly identify the Session Alarm to be removed. </p> </section>

    34 <section><title>Non-Session Alarms</title> <p>The alarms that continue to

    35 persist in the alarm queue, even after their session owner which added these

    36 alarms disconnect, are referred as Non-Session alarms. They are independent

    37 of the client that set them. </p> <p>Non-Session alarms are also referred

    38 as Orphaned Session alarms because these alarms are orphaned with no session

    39 owners. </p> </section>

    40 <section><title>Wake-Up Alarms</title> <p>An alarm that wakes-up the device,

    41 if the device is switched OFF when the alarm expires, is referred to as Wake-Up

    42 alarm. If the device is in the normal state, then it works as a clock alarm. </p> <p>It

    43 is set using <xref href="GUID-3598EAEE-0EF4-35A2-89E5-F3B2555B1AB4.dita#GUID-3598EAEE-0EF4-35A2-89E5-F3B2555B1AB4/GUID-92A40392-98CC-3BEA-AD92-0566C88905D9"><apiname>RASCliSession::SetWakeup</apiname></xref>, by passing the unique

    44 identifier of the alarm. </p> <p>A wake-up alarm that has been set and not

    45 started alerting the device user is referred as an active Wake-Up alarm. Alarm

    46 Server sets <codeph>EActiveWakeupAlarmSet</codeph> value if there are active

    47 wake-up alarm(s) else, it sets <codeph>EActiveNoWakeupAlarmsSet</codeph> value. </p> <p> <codeph>KWakeupAlarmPubSubKey</codeph> can

    48 be used to subscribe for wake-up alarm set and unset notifications. It belongs

    49 to the <codeph>KAlarmServerPubSubCategory</codeph> alarm Publish and Subscribe

    50 category. <codeph>EActiveWakeupAlarmUninitialized</codeph> is used to notify

    51 the listeners of <codeph>KWakeupAlarmPubSubKey</codeph> key that the Alarm

    52 Server has started at the device startup, and requires internalizing alarm

    53 queue and checking for the presence of active wake-up alarm. </p> </section>

    54 <section><title>Skipped Calendar Alarms</title> <p>An alarm that does not

    55 expire normally because of an environment change but the alarm’s expiry time

    56 is put in the past, is referred as Skipped Calendar alarms. An environment

    57 change can be due to system time and other local changes (UTC and workday

    58 changes). For more information, refer to <xref href="GUID-ED2B2DCC-D3C1-42FA-9CF3-0E149424C11D.dita">Working

    59 with Skipped Alarms</xref>.</p><p>The Publish and Subscribe framework enables

    60 a client to receive notification from the Alarm Server about the skipped alarm. <codeph>KMissingAlarmPubSubKey</codeph> P&amp;S

    61 key contains data about environmental changes and whether or not they have

    62 resulted in a skipped alarm. <codeph>KSkippedAlarmInstancesPubSubKey</codeph> P&amp;S

    63 key supplies additional information that is required to search the Calendar

    64 store for instances with skipped alarms. </p></section>

    65 </conbody></concept>