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 &lt;badef.rh&gt;

    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_d0e139735_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>