Alarm Sound Play Control

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 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 = 
        {
         ...
        }
    }

See also

Playing Alarm Sound Continuously