|
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-A5F65344-BE05-5295-85BB-E8114505FB82" xml:lang="en"><title>Alarm |
|
13 Sound Play Control</title><prolog><metadata><keywords/></metadata></prolog><conbody> |
|
14 <p>This section explains the use of sound, which is one of the several ways |
|
15 that the Alarm Server can notify the user. </p> |
|
16 <section><title>Alarm Play Interval Configuration</title> <p>The alarm sound |
|
17 play definition (<xref href="GUID-0075C5BA-8084-33EB-A246-7EED717E2B88.dita"><apiname>TASCliSoundPlayDefinition</apiname></xref>) is set using |
|
18 the <xref href="GUID-3598EAEE-0EF4-35A2-89E5-F3B2555B1AB4.dita"><apiname>RASCliSession</apiname></xref> class. Alarm sounds are played according |
|
19 to intervals that consist of a duration and an offset. The <xref href="GUID-0075C5BA-8084-33EB-A246-7EED717E2B88.dita"><apiname>TASCliSoundPlayDefinition</apiname></xref> class |
|
20 defines when alarm sounds are to be played, and for how long. </p> <p>The |
|
21 purpose of configuring alarm sound play is to enable the Alarm Server to perform |
|
22 the following operations: </p> <ul> |
|
23 <li id="GUID-954909FC-2690-50A6-A967-AB4E3C97A319"><p>set the alarm sound |
|
24 state to ON or OFF (<xref href="GUID-3598EAEE-0EF4-35A2-89E5-F3B2555B1AB4.dita#GUID-3598EAEE-0EF4-35A2-89E5-F3B2555B1AB4/GUID-EE45EA45-0289-3946-ACB8-25971D32FDC7"><apiname>RASCliSession::SetAlarmSoundState()</apiname></xref>). </p> </li> |
|
25 <li id="GUID-B8D77E1F-0F9C-5AA2-8269-68A04CD73525"><p>silence all alarms until |
|
26 a specific time (<xref href="GUID-3598EAEE-0EF4-35A2-89E5-F3B2555B1AB4.dita#GUID-3598EAEE-0EF4-35A2-89E5-F3B2555B1AB4/GUID-C15F814F-AFB6-3FE4-8674-B961A1EFA6F2"><apiname>RASCliSession::SetAlarmSoundsSilentUntil()</apiname></xref>). |
|
27 No sound is played for any alarm that is notified before this time. </p> </li> |
|
28 <li id="GUID-7359767C-FFC6-5903-B4C1-099C55EB0C3E"><p>silence all alarms for |
|
29 a specified interval (<xref href="GUID-3598EAEE-0EF4-35A2-89E5-F3B2555B1AB4.dita#GUID-3598EAEE-0EF4-35A2-89E5-F3B2555B1AB4/GUID-D86F97E4-3407-32C9-ADBA-0FD44D5A3ED3"><apiname>RASCliSession::SetAlarmSoundsSilentFor()</apiname></xref>). |
|
30 No alarm sound is played for any alarm notified during this period. </p> </li> |
|
31 <li id="GUID-79917BFC-C399-5FCB-A1B3-9E3CA16250F7"><p>cancel the silent period, |
|
32 turning the alarm sounds ON (<xref href="GUID-3598EAEE-0EF4-35A2-89E5-F3B2555B1AB4.dita#GUID-3598EAEE-0EF4-35A2-89E5-F3B2555B1AB4/GUID-92A4C2FD-46B9-36CA-A624-002EEFA9671C"><apiname>RASCliSession::CancelAlarmSilence()</apiname></xref>). </p> </li> |
|
33 <li id="GUID-D701C819-91AC-55F6-8A2B-99A3B95BB22D"><p>configure alarm sound |
|
34 play intervals (<xref href="GUID-3598EAEE-0EF4-35A2-89E5-F3B2555B1AB4.dita#GUID-3598EAEE-0EF4-35A2-89E5-F3B2555B1AB4/GUID-BB9A298E-C3AE-3E98-A677-E7A028F67602"><apiname>RASCliSession::SetAlarmPlayIntervalsL()</apiname></xref>), |
|
35 which specify the duration of the ‘play/silence/play’ when an alarm expires. </p> </li> |
|
36 <li id="GUID-4FCCE100-C356-5F22-8300-C4BFD6A64F0B"><p>determine whether the |
|
37 alarm server has temporarily silenced the sounds (<xref href="GUID-3598EAEE-0EF4-35A2-89E5-F3B2555B1AB4.dita#GUID-3598EAEE-0EF4-35A2-89E5-F3B2555B1AB4/GUID-EB8DC5EB-ABA9-3AB9-9D1B-E37DA612C0BB"><apiname>RASCliSession::AlarmSoundsTemporarilySilenced()</apiname></xref>). |
|
38 This returns <xref href="GUID-781E8158-805B-3784-8FED-D7A191822FC3.dita"><apiname>ETrue</apiname></xref> if alarm sound playing is temporarily |
|
39 silenced, else <xref href="GUID-A759CA2D-8327-348F-9337-4886E619D920.dita"><apiname>EFalse</apiname></xref> is specified. </p> </li> |
|
40 </ul> <p> <b>NOTE</b>: These APIs can be used <i>only</i> if the alarm sound |
|
41 play control is enabled from the Alarm Server side. </p> <p>To perform these |
|
42 operations, the Alarm Server uses a resource file, which defines the sound |
|
43 play intervals and durations. </p> <p><b>Resource File</b> </p> <p>The alarm |
|
44 play intervals are defined in <codeph>AlarmServer.rss</codeph> resource file. |
|
45 The compiled resource file (configuration file) must be named as <codeph>alarmserver.rsc</codeph> and |
|
46 be placed in the Alarm Server’s private directory (<codeph>C:\private\101F5027</codeph> on |
|
47 emulator, or <codeph>Z:\private\101F5027</codeph> on target platforms). </p> <p>The |
|
48 resource file must start with the necessary include directives, resource name, |
|
49 and standard signature entry as illustrated in the following code fragment: </p> <codeblock id="GUID-A6885AA2-38C0-54BA-8765-9B10A20B0478" xml:space="preserve">#include <badef.rh> |
|
50 #include <alarmserver.rh> |
|
51 |
|
52 NAME ASRV |
|
53 RESOURCE BA_RSS_SIGNATURE |
|
54 { |
|
55 signature = 1; |
|
56 }</codeblock> <p>The resource file specifies only the Offset (in minutes) |
|
57 and Duration (in seconds) of the Alarm play intervals. It is used only for |
|
58 initial configuration. </p> <p>At runtime, Alarm Server configurations are |
|
59 backed up to a file called as <filepath>AlarmServer.ini</filepath>, on the |
|
60 PC side. The backup operation performed can be one of the following types: </p> <ul> |
|
61 <li id="GUID-46E046BC-44CB-5B8C-90DD-4E022F258145"><p> <b>Secure Backup</b> - |
|
62 In this method, <codeph>backuprestorenotification.lib</codeph> (provides a |
|
63 notification mechanism) is used for backing and restoring operation to and |
|
64 from <codeph>C:\private\101F5027\AlarmServer.ini</codeph>. </p> </li> |
|
65 <li id="GUID-B17FCD6F-500A-5D49-9FC2-389B7F41E810"><p> <b>Passive Backup</b> - |
|
66 In this method, the required backup behavior is mentioned in a backup registration |
|
67 file called <filepath>backup_registration.xml</filepath>, placed in its private |
|
68 directory. The list of private directories and files that must be backed up |
|
69 are mentioned in this backup registration file. </p> </li> |
|
70 </ul> <p> <b>NOTE</b>: The backup file takes precedence over the resource |
|
71 file the next time the Alarm Server is started. Therefore, if changes are |
|
72 made to the resource file, <filepath>AlarmServer.ini</filepath> must be deleted |
|
73 manually before restarting the Alarm Server. </p> <p><b>Alarm Sound Play Intervals |
|
74 and Durations</b> </p> <p>The following diagram illustrates the alarm sound |
|
75 play intervals: </p> <fig id="GUID-477088D0-57BD-58BF-91BC-BF05E3EF2162"> |
|
76 <title> ALARM SOUND PLAY INTERVALS </title> |
|
77 <image href="GUID-3E23788D-4D67-5E9B-961F-B67D7471BB71_d0e118282_href.png" placement="inline"/> |
|
78 </fig> <p>Alarm play intervals define the toggling of alarm sound playing/stopping |
|
79 and alarm dialog show/hide when an alarm expires. It consists of a duration |
|
80 and an offset. The offset is the time, in minutes, from the beginning alarm |
|
81 time or the end of the last snooze. The duration is the time period, in seconds, |
|
82 during which the alarm sound is played. </p> <p>At each offset, the Alarm |
|
83 Server makes a request to the Alarm Alert server to display the alarm dialog |
|
84 and play the alarm sound. At the end of each duration period, the Alarm Server |
|
85 makes a request to the Alarm Alert server to hide the alarm and stop playing |
|
86 the alarm sound. </p> <p>The following is an example code fragment that plays |
|
87 the sound for 30 seconds, then pauses for 30 seconds, and repeats the pattern |
|
88 two more times: </p> <codeblock id="GUID-7ECBB50D-0C81-5059-A334-81BC979A04B2" xml:space="preserve">RESOURCE sound_controller |
|
89 { |
|
90 intervals = |
|
91 { |
|
92 SOUND_INTERVAL { offset = 0; duration = 30; }, |
|
93 SOUND_INTERVAL { offset = 1; duration = 30; }, |
|
94 SOUND_INTERVAL { offset = 2; duration = 30; }; |
|
95 }; |
|
96 }</codeblock> <p>An interval must have an offset of zero if more than |
|
97 one offset is specified. </p> <p> <b>NOTE</b>: The <xref href="GUID-0075C5BA-8084-33EB-A246-7EED717E2B88.dita"><apiname>TASCliSoundPlayDefinition</apiname></xref> class |
|
98 is the runtime equivalent of the sound intervals array. It defines <xref href="GUID-0075C5BA-8084-33EB-A246-7EED717E2B88.dita#GUID-0075C5BA-8084-33EB-A246-7EED717E2B88/GUID-79792213-24E6-3862-BEF5-832F8C34BF5A"><apiname>TASCliSoundPlayDefinition::Offset()</apiname></xref> length |
|
99 in minutes and defines <xref href="GUID-0075C5BA-8084-33EB-A246-7EED717E2B88.dita#GUID-0075C5BA-8084-33EB-A246-7EED717E2B88/GUID-1900BA63-48B2-32A6-93DB-F77CC7AA3E39"><apiname>TASCliSoundPlayDefinition::Duration()</apiname></xref> length |
|
100 in seconds. The API to set a <xref href="GUID-0075C5BA-8084-33EB-A246-7EED717E2B88.dita"><apiname>TASCliSoundPlayDefinition</apiname></xref> array |
|
101 is <xref href="GUID-0075C5BA-8084-33EB-A246-7EED717E2B88.dita#GUID-0075C5BA-8084-33EB-A246-7EED717E2B88/GUID-AB1E72B5-D9CE-3BAD-860D-6C1F443442E8"><apiname>TASCliSoundPlayDefinition::SetAlarmPlayIntervalsL()</apiname></xref>. </p> </section> |
|
102 <section><title>Alarm Play Sequence Repeat Option</title> <p>The resource |
|
103 file provides an option to repeat the sequence when the end of the alarm play |
|
104 sequence is reached. </p> <p>For backward compatibility, the default behavior |
|
105 is to restart the sequence when the end of the alarm play sequence is reached |
|
106 (see <xref href="GUID-0056DE57-61FD-3452-B65B-EFADC0069B8F.dita"><apiname>EAlarmSoundRepeatSettingStop</apiname></xref>). This occurs if there |
|
107 is no resource file, or if the resource file does not specify an option. There |
|
108 are two more end-of-sequence options: </p> <ul> |
|
109 <li id="GUID-73A1D734-2938-5477-81F7-B17F5237C374"><p> <xref href="GUID-41015640-AD70-3D56-9D89-AFAF67E15BCA.dita"><apiname>EAlarmSoundRepeatSettingLoop</apiname></xref> - |
|
110 stop when the end of sequence reached. </p> </li> |
|
111 <li id="GUID-F531E88D-AAD6-5F8D-9CDE-B153467D4DB1"><p> <xref href="GUID-98CE95CB-96F7-37A5-8C49-0B11D7CAEE6B.dita"><apiname>EAlarmSoundRepeatSettingRepeatLast</apiname></xref> - |
|
112 repeat last interval indefinitely. This is an optional entry in the resource |
|
113 file. </p> </li> |
|
114 </ul> <p>The following is a resource file example illustrating the use of |
|
115 an option to repeat the alarm play sequence: </p> <codeblock id="GUID-07ADF881-C2CE-558A-9237-2BF0E4E28064" xml:space="preserve">RESOURCE sound_controller |
|
116 { |
|
117 option = EAlarmSoundRepeatSettingRepeatLast; |
|
118 intervals = |
|
119 { |
|
120 ... |
|
121 } |
|
122 }</codeblock> </section> |
|
123 <section><title>See also</title> <p><xref href="GUID-59D2B677-63D7-5FE7-98F4-549D9C235E56.dita">Playing |
|
124 Alarm Sound Continuously</xref> </p> </section> |
|
125 </conbody></concept> |