Symbian3/SDK/Source/GUID-5C4922C8-3AE3-424A-A2E7-5C6DA323FFA6.dita
changeset 0 89d6a7a84779
equal deleted inserted replaced
-1:000000000000 0:89d6a7a84779
       
     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_d0e117702_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>