How to Set Play Definitions

This document is a guide to assist licensees in customising Alarm Server behaviour using the AlarmServer.rsc resource file.

Note: This document is primarily about AlarmServer.exe (/common/generic/app-services/alarmserver/), not the Uikon Alarm Alert Server. The Uikon component shall be referred to as the “Alert Server” in this document.

A new optional configuration resource file can customise the playing of alarm sounds. This makes it possible to customise or disable the UI application’s control of alarm sound intervals and durations. If the resource file does not exist, or contains invalid entries, the default behaviour persists.

The configuration file must be called alarmserver.rsc and must be in the Alarm Server’s private directory (C:\private\101F5027 on emulator, or Z:\private\101F5027 on target platforms.) It should start with the necessary include directives, resource name, and standard signature entry:

#include <badef.rh>
#include <alarmserver.rh>

NAME ASRV
RESOURCE BA_RSS_SIGNATURE
    {
      signature = 1;
      }

The resource file is only used for initial configuration. Alarm Server configuration is backed up to a file called AlarmServer.ini at runtime. That 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 should be deleted manually before restarting the Alarm Server.

Each entry in the sequence is a pair comprised of an offset and a duration. The offset is the time, in minutes, from the initial alarm time or the end of the last snooze. The duration refers to how long, in seconds, to play the alarm sound.

Here is an example 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 one or more is specified.

The TASCliSoundPlayDefinition class is the runtime equivalent of the 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().

This is a special case of “Alarm Play Interval Configuration” which is described in the previous section. An empty interval list is all that is required:

RESOURCE sound_controller
    {
    // disable alarm server control of alarm intervals
    intervals = {};
    }

This configuration cannot be overridden at runtime. RASCliSession::SetAlarmPlayIntervalsL() may not be used to change this option. It cannot turn off alarm sound control by specifying an empty sequence. It cannot turn on alarm sound control by overriding an empty sequence in the resource file.

Durations that extend into the next interval cause the whole sequence to revert to the default hard-coded values (see sound settings source code).

When the end of the alarm play sequence is reached, the previous behaviour was to restart the sequence. So after a few hours alarm play would be reduced to once per hour, then return to playing every minute.

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

• EAlarmSoundRepeatSettingLoop - stop when end of sequence reached

• EAlarmSoundRepeatSettingRepeatLast - repeat last interval indefinitely

The second option is an optional entry in the resource file. The syntax is as follows:

RESOURCE sound_controller
    {
    option = EAlarmSoundRepeatSettingRepeatLast;
    intervals = …
            }

This option cannot be overridden at runtime.