--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/Symbian3/PDK/Source/GUID-12A32F8E-0C53-5311-9B2B-8E0EA373ED08.dita Fri Jan 22 18:26:19 2010 +0000
@@ -0,0 +1,65 @@
+<?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 concept
+ PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd">
+<concept id="GUID-12A32F8E-0C53-5311-9B2B-8E0EA373ED08" xml:lang="en"><title>Types
+of Alarm</title><prolog><metadata><keywords/></metadata></prolog><conbody>
+<p>This section explains the various types of alarms that are handled by the
+Alarm Server. </p>
+<p>Session alarms and Non-Session alarms are handled by the Alarm Server after
+creating a session using <xref href="GUID-3598EAEE-0EF4-35A2-89E5-F3B2555B1AB4.dita"><apiname>RASCliSession</apiname></xref> function. </p>
+<section><title>Session Alarms </title> <p>The alarms that are removed from
+the alarm queue when the session disconnects are referred as Session Alarms.
+Session alarms can either be synchronous or asynchronous. </p> <p>The session-based
+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.
+Each session is allowed to set only one Session Alarm. The server informs
+the session when to set the next alarm. If the session disconnects, the Session
+Alarm is cancelled. </p> <p>The Session Alarm is completed when the alarm
+expires, is cancelled, or a timing error occurs. </p> <p> <b>NOTE</b>: If
+the client session is closed before the alarm has expired, the Alarm Server
+automatically dequeues the alarm. </p> <p><b>Synchronous Session Alarms</b> </p> <p>To
+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
+Session Alarms</b> </p> <p>To add a session alarm to the queue asynchronously,
+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
+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>.
+This requires that the ID of the alarm object be passed to the Alarm Server,
+so that it can correctly identify the Session Alarm to be removed. </p> </section>
+<section><title>Non-Session Alarms</title> <p>The alarms that continue to
+persist in the alarm queue, even after their session owner which added these
+alarms disconnect, are referred as Non-Session alarms. They are independent
+of the client that set them. </p> <p>Non-Session alarms are also referred
+as Orphaned Session alarms because these alarms are orphaned with no session
+owners. </p> </section>
+<section><title>Wake-Up Alarms</title> <p>An alarm that wakes-up the device,
+if the device is switched OFF when the alarm expires, is referred to as Wake-Up
+alarm. If the device is in the normal state, then it works as a clock alarm. </p> <p>It
+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
+identifier of the alarm. </p> <p>A wake-up alarm that has been set and not
+started alerting the device user is referred as an active Wake-Up alarm. Alarm
+Server sets <codeph>EActiveWakeupAlarmSet</codeph> value if there are active
+wake-up alarm(s) else, it sets <codeph>EActiveNoWakeupAlarmsSet</codeph> value. </p> <p> <codeph>KWakeupAlarmPubSubKey</codeph> can
+be used to subscribe for wake-up alarm set and unset notifications. It belongs
+to the <codeph>KAlarmServerPubSubCategory</codeph> alarm Publish and Subscribe
+category. <codeph>EActiveWakeupAlarmUninitialized</codeph> is used to notify
+the listeners of <codeph>KWakeupAlarmPubSubKey</codeph> key that the Alarm
+Server has started at the device startup, and requires internalizing alarm
+queue and checking for the presence of active wake-up alarm. </p> </section>
+<section><title>Skipped Calendar Alarms</title> <p>An alarm that does not
+expire normally because of an environment change but the alarm’s expiry time
+is put in the past, is referred as Skipped Calendar alarms. An environment
+change can be due to system time and other local changes (UTC and workday
+changes). For more information, refer to <xref href="GUID-ED2B2DCC-D3C1-42FA-9CF3-0E149424C11D.dita">Working
+with Skipped Alarms</xref>.</p><p>The Publish and Subscribe framework enables
+a client to receive notification from the Alarm Server about the skipped alarm. <codeph>KMissingAlarmPubSubKey</codeph> P&S
+key contains data about environmental changes and whether or not they have
+resulted in a skipped alarm. <codeph>KSkippedAlarmInstancesPubSubKey</codeph> P&S
+key supplies additional information that is required to search the Calendar
+store for instances with skipped alarms. </p></section>
+</conbody></concept>
\ No newline at end of file