|
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-114D4F3F-9358-5B50-94DC-45CCBA783DF4" 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 owner which added these alarms disconnect, are referred as Non-Session |
|
74 alarms. These alarms are also referred to as Orphaned Session alarms. </p> </dd> |
|
75 </dlentry> |
|
76 <dlentry> |
|
77 <dt>Wake-Up alarms</dt> |
|
78 <dd><p>An alarm that wakes-up the device if the device is switched OFF when |
|
79 the alarm occurs, is referred to as Wake-Up alarm. </p> </dd> |
|
80 </dlentry> |
|
81 <dlentry> |
|
82 <dt>Skipped/Missed Calendar alarms</dt> |
|
83 <dd><p>An alarm which does not expire normally because of an environment change |
|
84 but the alarm’s expiry time is put in the past, is referred as Skipped Calendar |
|
85 alarms. </p> </dd> |
|
86 </dlentry> |
|
87 </dl> </section> |
|
88 <section><title>Architecture</title> <p>Alarm Server is implemented using |
|
89 the Symbian platform IPC client-server architecture. It has an interface to |
|
90 the Alarm Alert server, which is delivered as part of the Application Framework |
|
91 (UIKON component). Alarm Alert Server is responsible for displaying the alarm |
|
92 dialog when an alarm expires. The Alarm Server implements the Alarm Alert |
|
93 server’s client side DLL to send and receive notifications to and from the |
|
94 Alarm UI. Alarm Alert Server is a part of the UIKON server (<codeph>Eiksrv.exe</codeph>). |
|
95 The Alarm Server itself implements the client-side APIs since it is the only |
|
96 client for the Alarm Alert server. The following diagram illustrates the Alarm |
|
97 Server architecture: </p> <fig id="GUID-D6309F3E-4835-5703-8929-8A108CC5D376"> |
|
98 <title> Alarm Server Architecture </title> |
|
99 <image href="GUID-7CD8F0E3-68C3-5939-A96D-547740D796E5_d0e152190_href.png" placement="inline"/> |
|
100 </fig> <p><b>Alarm Client and Alarm Shared</b> </p> <p>They are the static |
|
101 interface DLLs. Alarm client is the client side of the Alarm Server, which |
|
102 allows other components to interact with the Alarm Server. </p> <p>The Alarm |
|
103 Shared facilitates a common format shared across server and its clients for |
|
104 providing definition for an alarm. It consists of shared objects such as alarm |
|
105 class, IPC messages, repeat definitions, alarm states. </p> <p><b>Alarm Server</b> </p> <p>Alarm |
|
106 Server manages all alarms on the device and enables client UI applications |
|
107 to use the services provided by the Alarm Server. It relies on the Alarm UI |
|
108 to notify, which includes displaying and playing sounds. </p> <p>It uses a |
|
109 resource file to configure the sound intervals required for the alarm to repeat. |
|
110 The compiled resource file resides in the private directory of the Alarm Server. |
|
111 The resource file is used only for initial configuration. </p> <p>Alarm Server |
|
112 configurations are stored in <codeph>AlarmServer.ini</codeph> file and <codeph>Backup_Registration.xml</codeph> file |
|
113 performs a passive backup of this <codeph>.ini</codeph> file to the PC-side |
|
114 at runtime. For secure backup of this <codeph>.ini</codeph> file, <codeph>backuprestorenotification.lib</codeph> is |
|
115 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 |
|
116 provides Publish and Subscribe keys to enable the client to receive notifications |
|
117 of the changes to the Alarm Server. The P&S key are: </p> <ul> |
|
118 <li id="GUID-BDB9B185-B20A-5598-AD66-29EE0DC25224"><p> <codeph>KMissingAlarmPubSubKey</codeph> - |
|
119 provides information about missed calendar alarms, which were missed due to |
|
120 the device being in the shutdown state. </p> </li> |
|
121 <li id="GUID-D0ABBB1C-0796-5E5B-A7E0-216ECAD537F5"><p> <codeph>KSkippedAlarmInstancesPubSubKey</codeph> - |
|
122 provides information about skipped calendar alarms instances which can used |
|
123 for searching the required data in the calendar store. </p> </li> |
|
124 <li id="GUID-2FCE4A66-7199-5B74-AE68-DCD702672FD3"><p> <codeph>KWakeupAlarmPubSubKey</codeph> - |
|
125 provides information about an active wake-up alarm which is set or unset. </p> </li> |
|
126 </ul> <p>For more information on Skipped Calendar Alarms and Wake-up Alarms, |
|
127 refer to <xref href="GUID-12A32F8E-0C53-5311-9B2B-8E0EA373ED08.dita">Types of Alarm</xref> section. </p> <p>It |
|
128 listens to the following events: </p> <ul> |
|
129 <li id="GUID-266EBC9B-E834-5DCD-9B5F-F9E4A13EFF4E"><p>DST rollover - Using <codeph>KDSTChangePropertyKey</codeph> P&S |
|
130 key, Alarm Server listens to DST rollover information from <xref href="GUID-3CD0CEB1-CE8B-5108-A7F7-5E1414020C37.dita">Time |
|
131 Zone Server</xref> resulting in the change of wall clock/local time clock. </p> </li> |
|
132 <li id="GUID-F759197E-A22E-5C4F-89B7-247BF64134E1"><p>System state changes |
|
133 - Using <xref href="GUID-788BD091-186A-5E25-B058-952C7629A8D4.dita">System State |
|
134 Manager</xref> (SSM), Alarm Server listens to the system state changes (normal |
|
135 and shutdown states) to synchronize the backup of the alarm server queue to |
|
136 the <codeph>AlarmServer.ini</codeph> backup file. </p> </li> |
|
137 <li id="GUID-42C04AB7-8BCC-57D6-A716-4F6B12F5AC30"><p>Environment change - |
|
138 Using <xref href="GUID-7C6D3479-2159-5A9B-9970-0B3E625442A6.dita">Environment Change |
|
139 Notifier</xref> (<codeph>bafl.dll</codeph>), Alarm Server listens to the changes |
|
140 in the environment, such as system time/date change, workdays change or UTC |
|
141 offset change. </p> </li> |
|
142 </ul> <p><b>UIKON Server</b> </p> <p>UIKON server is responsible for starting |
|
143 the Alarm Server at the device boot-up, by loading the polymorphic DLL, EIKSRVUI |
|
144 provided by the device creator. </p> <p>It is also responsible for playing |
|
145 sounds, flashing lights and displaying the message. Through the UIKON server, |
|
146 alarms can be cleared, snoozed or silenced. Alarm server implements and uses |
|
147 the client side interface. Alarm UI implements the server side of the UIKON |
|
148 server. </p> </section> |
|
149 <section><title>APIs</title> <p>The Alarm Server provides the following client |
|
150 API: </p> <table id="GUID-60D7DF2B-BA9C-5CEC-9048-6B8536D04CFE"> |
|
151 <tgroup cols="2"><colspec colname="col0"/><colspec colname="col1"/> |
|
152 <thead> |
|
153 <row> |
|
154 <entry>API</entry> |
|
155 <entry>Description</entry> |
|
156 </row> |
|
157 </thead> |
|
158 <tbody> |
|
159 <row> |
|
160 <entry><p> <xref href="GUID-3598EAEE-0EF4-35A2-89E5-F3B2555B1AB4.dita"><apiname>RASCliSession</apiname></xref> </p> </entry> |
|
161 <entry><p>Client interface to Alarm session on Symbian Platform. </p></entry> |
|
162 </row> |
|
163 </tbody> |
|
164 </tgroup> |
|
165 </table> </section> |
|
166 <section><title>Typical uses</title> <p>The following are the typical use |
|
167 cases of Alarm Server: </p> <ul> |
|
168 <li id="GUID-854E8EA9-3194-5D0E-8BB5-3006B04BB6D3"><p>Using Alarm Server to |
|
169 add, update and delete alarms, set alarm status and so on. </p> </li> |
|
170 <li id="GUID-9A999DC2-6D48-58B8-B251-F22A88A1978C"><p>Playing an alarm continuously. </p> </li> |
|
171 <li id="GUID-2D7D1AF6-2728-59CF-BD92-32D97FD6C6B6"><p>Activating an alarm |
|
172 on specified days. </p> </li> |
|
173 </ul> </section> |
|
174 </conbody><related-links> |
|
175 <link href="GUID-E6788741-EF34-57B7-B4D4-8AAC21B25774.dita"><linktext>Alarm Server |
|
176 Concepts</linktext></link> |
|
177 <link href="GUID-63730EBD-E5C1-5BA9-AB71-8FF668ECEF00.dita"><linktext>Alarm Server |
|
178 Tutorials</linktext></link> |
|
179 <link href="GUID-7BCA8B7A-E250-5452-9837-26C60F71F14F.dita"><linktext>Alarm Server |
|
180 Reference</linktext></link> |
|
181 <link href="GUID-74153585-D483-5761-85B6-2CF2D2615C00.dita"><linktext>Alarm Server |
|
182 Example</linktext></link> |
|
183 </related-links></concept> |