Alarm -Sound Play Control

This section explains the use of sound, which is one of the several ways -that the Alarm Server can notify the user.

Alarm Play Interval Configuration

The alarm sound -play definition (TASCliSoundPlayDefinition) is set using -the RASCliSession class. Alarm sounds are played according -to intervals that consist of a duration and an offset. The TASCliSoundPlayDefinition class -defines when alarm sounds are to be played, and for how long.

The -purpose of configuring alarm sound play is to enable the Alarm Server to perform -the following operations:

set the alarm sound -state to ON or OFF (RASCliSession::SetAlarmSoundState()).
silence all alarms until -a specific time (RASCliSession::SetAlarmSoundsSilentUntil()). -No sound is played for any alarm that is notified before this time.
silence all alarms for -a specified interval (RASCliSession::SetAlarmSoundsSilentFor()). -No alarm sound is played for any alarm notified during this period.
cancel the silent period, -turning the alarm sounds ON (RASCliSession::CancelAlarmSilence()).
configure alarm sound -play intervals (RASCliSession::SetAlarmPlayIntervalsL()), -which specify the duration of the ‘play/silence/play’ when an alarm expires.
determine whether the -alarm server has temporarily silenced the sounds (RASCliSession::AlarmSoundsTemporarilySilenced()). -This returns ETrue if alarm sound playing is temporarily -silenced, else EFalse is specified.

NOTE: These APIs can be used only if the alarm sound -play control is enabled from the Alarm Server side.

To perform these -operations, the Alarm Server uses a resource file, which defines the sound -play intervals and durations.

Resource File

The alarm -play intervals are defined in AlarmServer.rss resource file. -The compiled resource file (configuration file) must be named as alarmserver.rsc and -be placed in the Alarm Server’s private directory (C:\private\101F5027 on -emulator, or Z:\private\101F5027 on target platforms).

The -resource file must start with the necessary include directives, resource name, -and standard signature entry as illustrated in the following code fragment:

#include <badef.rh> -#include <alarmserver.rh> - -NAME ASRV -RESOURCE BA_RSS_SIGNATURE - { - signature = 1; - }

The resource file specifies only the Offset (in minutes) -and Duration (in seconds) of the Alarm play intervals. It is used only for -initial configuration.

At runtime, Alarm Server configurations are -backed up to a file called as AlarmServer.ini, on the -PC side. The backup operation performed can be one of the following types:

Secure Backup - -In this method, backuprestorenotification.lib (provides a -notification mechanism) is used for backing and restoring operation to and -from C:\private\101F5027\AlarmServer.ini.
Passive Backup - -In this method, the required backup behavior is mentioned in a backup registration -file called backup_registration.xml, placed in its private -directory. The list of private directories and files that must be backed up -are mentioned in this backup registration file.

NOTE: The backup file takes precedence over the resource -file the next time the Alarm Server is started. Therefore, if changes are -made to the resource file, AlarmServer.ini must be deleted -manually before restarting the Alarm Server.

Alarm Sound Play Intervals -and Durations

The following diagram illustrates the alarm sound -play intervals:

- ALARM SOUND PLAY INTERVALS - -

Alarm play intervals define the toggling of alarm sound playing/stopping -and alarm dialog show/hide when an alarm expires. It consists of a duration -and an offset. The offset is the time, in minutes, from the beginning alarm -time or the end of the last snooze. The duration is the time period, in seconds, -during which the alarm sound is played.

At each offset, the Alarm -Server makes a request to the Alarm Alert server to display the alarm dialog -and play the alarm sound. At the end of each duration period, the Alarm Server -makes a request to the Alarm Alert server to hide the alarm and stop playing -the alarm sound.

The following is an example code fragment that plays -the sound for 30 seconds, then pauses for 30 seconds, and repeats the pattern -two more times:

RESOURCE sound_controller - { - intervals = - { - SOUND_INTERVAL { offset = 0; duration = 30; }, - SOUND_INTERVAL { offset = 1; duration = 30; }, - SOUND_INTERVAL { offset = 2; duration = 30; }; - }; - }

An interval must have an offset of zero if more than -one offset is specified.

NOTE: The TASCliSoundPlayDefinition class -is the runtime equivalent of the sound intervals array. It defines TASCliSoundPlayDefinition::Offset() length -in minutes and defines TASCliSoundPlayDefinition::Duration() length -in seconds. The API to set a TASCliSoundPlayDefinition array -is TASCliSoundPlayDefinition::SetAlarmPlayIntervalsL().

Alarm Play Sequence Repeat Option

The resource -file provides an option to repeat the sequence when the end of the alarm play -sequence is reached.

For backward compatibility, the default behavior -is to restart the sequence when the end of the alarm play sequence is reached -(see EAlarmSoundRepeatSettingStop). This occurs if there -is no resource file, or if the resource file does not specify an option. There -are two more end-of-sequence options:

EAlarmSoundRepeatSettingLoop - -stop when the end of sequence reached.
EAlarmSoundRepeatSettingRepeatLast - -repeat last interval indefinitely. This is an optional entry in the resource -file.

The following is a resource file example illustrating the use of -an option to repeat the alarm play sequence:

RESOURCE sound_controller - { - option = EAlarmSoundRepeatSettingRepeatLast; - intervals = - { - ... - } - }