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-5C4922C8-3AE3-424A-A2E7-5C6DA323FFA6" xml:lang="en"><title>Alarm

    13 Server Overview</title><prolog><metadata><keywords/></metadata></prolog><conbody>

    14 <p>Alarm Server is a system server, which starts during device start-up. It

    15 is responsible for maintaining a queue of all system-wide alarms. </p>

    16 <p>It allows clients to query the status of alarms, set alarms, remove alarms

    17 and perform other utility functions. The Alarm client API allows other components

    18 to interact with the Alarm Server. The Alarm Server sends notification of

    19 alarm expiry to the Alert Server, which then notifies the Alarm UI to display

    20 dialogs and play sound. </p>

    21 <p>The typical clients of Alarm Server include Clock and Calendar applications. </p>

    22 <section><title>Purpose</title> <p>The Alarm Server manages the alarms in

    23 the system and provides the following functionality: </p> <ul>

    24 <li id="GUID-56175798-4930-55A3-ACD8-848192C07A63"><p>adding, updating and

    25 deleting alarms. </p> </li>

    26 <li id="GUID-FCF13562-7E88-5A5B-84B9-05B7934E7277"><p>getting and setting

    27 client-specific data associated with the alarm. </p> </li>

    28 <li id="GUID-44A49D6B-A12E-5C05-A7D7-9BDE3E430521"><p>performing alarm category-based

    29 operations such as retrieval and deletion. Retrieving alarm information includes

    30 alarm count, unique identifiers based on alarm states. </p> </li>

    31 <li id="GUID-57B8169F-1166-5534-9236-D1C367AB2413"><p>getting and setting

    32 Alarm Server’s global sound state and play intervals. </p> </li>

    33 <li id="GUID-7BB3AD26-5650-5B6A-B656-76A24EF9086A"><p>notifying the client

    34 when alarm settings change and when the alarm expires. </p> </li>

    35 </ul> </section>

    36 <section><title>Key concepts and terms</title> <dl>

    37 <dlentry>

    38 <dt>Duration</dt>

    39 <dd><p>It is the time period, in seconds, for which the alarm sound is played. </p> </dd>

    40 </dlentry>

    41 <dlentry>

    42 <dt>Offset</dt>

    43 <dd><p>It is the time (in minutes) duration of alarm sound played after the

    44 alarm expiry. </p> </dd>

    45 </dlentry>

    46 <dlentry>

    47 <dt>Alarm play interval</dt>

    48 <dd><p>Alarm play interval consists of duration and an offset. At each offset,

    49 the Alarm Server makes a request to the Alarm Alert Server to display the

    50 alarm dialog and play the alarm sound. </p> </dd>

    51 </dlentry>

    52 <dlentry>

    53 <dt>Universal Time Coordinated (UTC)</dt>

    54 <dd><p>It is the international time standard. It is the current term for what

    55 was commonly referred as Greenwich Meridian Time (GMT) . Zero hours UTC is

    56 midnight in Greenwich England, which lies on the zero longitudinal meridian.

    57 Universal time is based on a 24-hour clock. Therefore, afternoon hours such

    58 as 4 PM are expressed as 16:00 UTC. </p> </dd>

    59 </dlentry>

    60 <dlentry>

    61 <dt>Daylight Saving Time (DST)</dt>

    62 <dd><p>Daylight Saving Time or Summer Time, is a way of utilizing more daylight

    63 by advancing the local time by one hour during the summer. </p> </dd>

    64 </dlentry>

    65 <dlentry>

    66 <dt>Session alarms</dt>

    67 <dd><p>The alarms that are removed from the alarm queue when their session

    68 owners disconnect are referred as Session Alarms. </p> </dd>

    69 </dlentry>

    70 <dlentry>

    71 <dt>Non-Session alarms</dt>

    72 <dd><p>The alarms that continue to persist in the alarm queue, even after

    73 their session owners which added these alarms disconnect, are referred as

    74 Non-Session alarms. These alarms are also referred to as Orphaned Session

    75 alarms. </p> </dd>

    76 </dlentry>

    77 <dlentry>

    78 <dt>Wake-Up alarms</dt>

    79 <dd><p>An alarm that wakes-up the device if the device is switched OFF when

    80 the alarm occurs, is referred to as Wake-Up alarm. </p> </dd>

    81 </dlentry>

    82 </dl> </section>

    83 <section><title>Architecture</title> <p>Alarm Server is implemented using

    84 the Symbian platform IPC client-server architecture. It has an interface to

    85 the Alarm Alert server, which is delivered as part of the Application Framework

    86 (UIKON component). Alarm Alert Server is responsible for displaying the alarm

    87 dialog when an alarm expires. The Alarm Server implements the Alarm Alert

    88 server’s client side DLL to send and receive notifications to and from the

    89 Alarm UI. Alarm Alert Server is a part of the UIKON server (<codeph>Eiksrv.exe</codeph>).

    90 The Alarm Server itself implements the client-side APIs since it is the only

    91 client for the Alarm Alert server. The following diagram illustrates the Alarm

    92 Server architecture: </p> <fig id="GUID-D6309F3E-4835-5703-8929-8A108CC5D376">

    93 <title>              Alarm Server Architecture            </title>

    94 <image href="GUID-575CDD9C-ED6E-510E-AE11-46CA7EB7B74C_d0e139155_href.png" placement="inline"/>

    95 </fig> <p><b>Alarm Client and Alarm Shared</b> </p> <p>They are the static

    96 interface DLLs. Alarm client is the client side of the Alarm Server, which

    97 allows other components to interact with the Alarm Server. </p> <p>The Alarm

    98 Shared facilitates a common format shared across server and its clients for

    99 providing definition for an alarm. It consists of shared objects such as alarm

   100 class, IPC messages, repeat definitions, alarm states. </p> <p><b>Alarm Server</b> </p> <p>Alarm

   101 Server manages all alarms on the device and enables client UI applications

   102 to use the services provided by the Alarm Server. It relies on the Alarm UI

   103 to notify, which includes displaying and playing sounds. </p> <p>It uses a

   104 resource file to configure the sound intervals required for the alarm to repeat.

   105 The compiled resource file resides in the private directory of the Alarm Server.

   106 The resource file is used only for initial configuration. </p> <p>Alarm Server

   107 configurations are stored in <codeph>AlarmServer.ini</codeph> file and <codeph>Backup_Registration.xml</codeph> file

   108 performs a passive backup of this <codeph>.ini</codeph> file to the PC-side

   109 at runtime. For secure backup of this <codeph>.ini</codeph> file, <codeph>backuprestorenotification.lib</codeph> is

   110 used. For more information on the resource file and backup, refer to the <xref href="GUID-A5F65344-BE05-5295-85BB-E8114505FB82.dita">Alarm Sound Play Control</xref>. </p> <p>It

   111 listens to the following events: </p> <ul>

   112 <li id="GUID-F759197E-A22E-5C4F-89B7-247BF64134E1"><p>System state changes

   113 - Using <xref href="GUID-788BD091-186A-5E25-B058-952C7629A8D4.dita">System State

   114 Manager</xref> (SSM), Alarm Server listens to the system state changes (normal

   115 and shutdown states) to synchronize the backup of the alarm server queue to

   116 the <codeph>AlarmServer.ini</codeph> backup file. </p> </li>

   117 <li id="GUID-42C04AB7-8BCC-57D6-A716-4F6B12F5AC30"><p>Environment change -

   118 Using <xref href="GUID-7C6D3479-2159-5A9B-9970-0B3E625442A6.dita">Environment Change

   119 Notifier</xref> (<codeph>bafl.dll</codeph>), Alarm Server listens to the changes

   120 in the environment, such as system time/date change, workdays change or UTC

   121 offset change. </p> </li>

   122 </ul> <p><b>UIKON Server</b> </p> <p>UIKON server is responsible for starting

   123 the Alarm Server at the device boot-up. </p> <p>It is also responsible for

   124 playing sounds, flashing lights and displaying the message. Through the UIKON

   125 server, alarms can be cleared, snoozed or silenced. Alarm server implements

   126 and uses the client side interface. Alarm UI implements the server side of

   127 the UIKON server. </p> </section>

   128 <section><title>APIs</title> <p>The Alarm Server provides the following client

   129 API: </p> <table id="GUID-60D7DF2B-BA9C-5CEC-9048-6B8536D04CFE">

   130 <tgroup cols="2"><colspec colname="col0"/><colspec colname="col1"/>

   131 <thead>

   132 <row>

   133 <entry>API</entry>

   134 <entry>Description</entry>

   135 </row>

   136 </thead>

   137 <tbody>

   138 <row>

   139 <entry><p> <xref href="GUID-3598EAEE-0EF4-35A2-89E5-F3B2555B1AB4.dita"><apiname>RASCliSession</apiname></xref>  </p> </entry>

   140 <entry><p>Client interface to Alarm session on Symbian Platform. </p></entry>

   141 </row>

   142 </tbody>

   143 </tgroup>

   144 </table> </section>

   145 <section><title>Typical uses</title> <p>The following are the typical use

   146 cases of Alarm Server: </p> <ul>

   147 <li id="GUID-854E8EA9-3194-5D0E-8BB5-3006B04BB6D3"><p>Using Alarm Server to

   148 add, update and delete alarms, set alarm status and so on. </p> </li>

   149 <li id="GUID-9A999DC2-6D48-58B8-B251-F22A88A1978C"><p>Playing an alarm continuously. </p> </li>

   150 <li id="GUID-2D7D1AF6-2728-59CF-BD92-32D97FD6C6B6"><p>Activating an alarm

   151 on specified days. </p> </li>

   152 </ul> </section>

   153 </conbody></concept>