Class RAlarmServer

RAlarmServer

Support

Supported from 5.0

Description

Defines the alarm server’s client side API.

Clients can use this API to connect to the alarm server, add, count and delete alarms, retrieve alarm information, orphan session alarms, and set the alarm sound state.

Derivation

RAlarmServer Defines the alarm server's client side API RHandleBase Handle to an object RSessionBase Client-side handle to a session with a server

Defined in RAlarmServer:
AlarmArrayPopulateL(), AlarmCount(), AlarmDelete(), AlarmEnable(), AlarmInfo(), AlarmOwner(), AlarmSoundState(), AlarmState(), AlarmType(), CancelSessionAlarm(), Connect(), DeleteAllOrphanAlarms(), EArrayNext, EArrayOrphan, EArrayReview, EArraySnooze, ECountNext, ECountOrphan, ECountReview, ECountSnooze, ECountUnacknowledged, EInfoById, EInfoClock, EInfoNext, EInfoSession, ESessionTypeDay, ESessionTypeTimed, GetAlarmPlayIntervalsL(), NotifyOnChange(), NotifyOnChangeCancel(), OrphanSessionAlarm(), QuietPeriodCancel(), QuietPeriodSet(), QuietPeriodUntil(), SetAgendaAlarm(), SetAlarmPlayIntervals(), SetAlarmSoundOn(), SetClockAlarm(), SetSessionAlarm(), TArrayCategory, TCountCategory, TInfoCategory, TSessionType, Version()

Inherited from RHandleBase:
Close(), Duplicate(), Handle(), SetHandle()

Inherited from RSessionBase:
Attach(), CreateSession(), EAutoAttach, EExplicitAttach, Send(), SendReceive(), SetRetry(), Share(), TAttachMode

TInt Connect();

Description

Connects a client process to the alarm server.

Note:

• As with any server, the connection should be closed after use. RHandleBase provides the necessary Close() function, which should be called when the server session is no longer required.

Return value

TInt KErrNone if successful, otherwise another of the system-wide error codes.

TVersion Version() const;

Description

Gets the version number of the DLL.

The version number may be incremented in future releases of the alarm server. If extra features are added in such releases, the version number may be used by application programs as a basis for assessing the capabilities of the alarm server. Version-specific functions will be marked as such in the API documentation.

Return value

TVersion The version number.

TInt AlarmCount(TCountCategory aCategory) const;

Description

Gets the number of alarms in a particular category.

Parameters

TCountCategory aCategory The category of alarm being counted.

Return value

TInt KErrNone if successful, otherwise another of the system-wide error codes.

TAlarmSetState AlarmState(TInt aAlarmId) const;

Description

Determines whether a given alarm is set, not set, or disabled.

Parameters

TInt aAlarmId The ID of the alarm for which the state is to be found.

Return value

TAlarmSetState The current state of the alarm.

TInt AlarmInfo(TAlarmInfo& anAlarm,TInfoCategory aCategory,TInt aAlarmId=KNullAlarmID) const;

Description

Gets alarm information from the alarm server.

The information is retrieved by category and alarm ID. The alarms in each category are indexed from 0 — if no ID is specified then the first alarm in the specified category is retrieved (KNullAlarmID).

Parameters

TAlarmInfo& anAlarm On return, contains the alarm information. TInfoCategory aCategory The category of alarm for which information is to be obtained. TInt aAlarmId=KNullAlarmID   The alarm ID, which must be greater than or equal to zero. The ID defaults to the first alarm in the specified category.

Return value

TInt KErrNone if successful, otherwise another of the system-wide error codes.

TAlarmSoundState AlarmSoundState() const;

Description

Gets the alarm sound state. This state, which applies to all alarms, determines whether the sound for active alarms is on, off, or suspended for a predefined period.

Return value

TAlarmSoundState The alarm sound status.

TInt AlarmType(TAlarmType& aType,TInt aAlarmId) const;

Description

Gets the type of the specified alarm.

Parameters

TAlarmType& aType On return, contains the alarm type. TInt aAlarmId The ID of the alarm.

Return value

TInt KErrNone if successful, otherwise another of the system-wide error codes.

TInt AlarmOwner(TFullName& aName,TInt aAlarmId) const;

Description

Gets the owner’s name for an alarm.

Parameters

TFullName& aName On return, contains the owner’s name for the alarm. TInt aAlarmId The ID of the alarm.

Return value

TInt KErrNone if successful, otherwise another of the system-wide error codes.

void AlarmArrayPopulateL(CAlarmIdArray& aArray,TArrayCategory aCategory,TInt aMaxNumber=64) const;

Description

Populates an array with the alarm IDs of a specified type. The array of IDs can then be used for finding information about each of the alarms.

Parameters

CAlarmIdArray& aArray The array which is to be populated. TArrayCategory aCategory The type of alarms with which to populate the array. TInt aMaxNumber The maximum number of alarms in the array. The default is 64.

TInt AlarmEnable(TBool aShouldEnable,TInt aAlarmId);

Description

Enables or disables alarms.

Notes:

• An enabled alarm is one which will activate at a specified time.

• A disabled alarm is one which exists in the array but is not active. This corresponds to an alarm with a strike-through in the Time application.

Parameters

TBool aShouldEnable ETrue — enable the alarm. EFalse — disable the alarm. TInt aAlarmId The ID of the alarm to be enabled or disabled.

Return value

TInt KErrNone if successful, otherwise another of the system-wide error codes.

TInt AlarmDelete(TInt aAlarmId);

Description

Deletes an alarm from the alarm server.

Parameters

TInt aAlarmId The ID of the alarm to be deleted.

Return value

TInt KErrNone if successful, otherwise another of the system-wide error codes.

TInt DeleteAllOrphanAlarms();

Support

Supported from 5.1

Description

Deletes all orphan alarms from the alarm server.

Return value

TInt KErrNone if successful, otherwise another of the system-wide error codes.

void SetAgendaAlarm(const TTime& aAlarmTime,const TAlarmMessage& aMessage,const TAlarmSoundName& aSound,const TTime& aDueDateTime,TSessionType aType);

Support

Supported from 5.1

Description

Sets an agenda alarm. Agenda alarms are persistent — maintained by the server even when the session that created them has shut down. They supersede, but do not replace session alarms.

Notes:

• Agenda alarms can be set by any application.

• Agenda uses this function as part of its shut-down process to write a number of pending alarms to the alarm server. When Agenda is re-started it again uses this function — to set the next alarm. If this alarm is still outstanding the function call has no effect.

Parameters

const TTime& aAlarmTime The alarm activation time. const TAlarmMessage& aMessage The text message associated with the alarm. const TAlarmSoundName& aSound The name of the sound file to be played when the alarm activates. const TTime& aDueDateTime The alarm due date and time. This is the time that the alarm was/is due. When setting the alarm this should be the same as aAlarmTime. TSessionType aType The type of agenda alarm.

void SetClockAlarm(TInt aClockAlarmIndex,const TTime& aAlarmTime,const TAlarmMessage& aMessage,const TAlarmSoundName& aSound,TAlarmClockRepeat aRepeat);

Description

Sets a new clock alarm.

Note:

• There are 8 clock alarms. To change a clock alarm clients should over-write the alarm’s index with the new information.

Parameters

TInt aClockAlarmIndex The index of the clock alarm — range 0 - 7. const TTime& aAlarmTime The alarm activation time. const TAlarmMessage& aMessage The text message associated with the alarm. const TAlarmSoundName& aSound The name of the sound file to be played when the alarm activates. TAlarmClockRepeat aRepeat The alarm repetition rate.

void SetSessionAlarm(TRequestStatus& aStatus,const TTime& aAlarmTime,const TAlarmMessage& aMessage,const TAlarmSoundName& aSound,const TTime& aDueDateTime,TSessionType aType);

Description

Sets the session alarm.

Notes:

• Each session can only have one session alarm.

• To update the alarm settings, the session alarm must be cancelled and this function re-posted with the new information.

Parameters

TRequestStatus& aStatus A variable that indicates the completion status of the request. const TTime& aAlarmTime The alarm date and time. This is the time that the alarm is next expected to activate. This is initially the same as the due time. const TAlarmMessage& aMessage The alarm message. const TAlarmSoundName& aSound The name of the sound file to play when the alarm activates. const TTime& aDueDateTime The alarm due date and time. This is the time that the alarm was/is due. When setting the alarm this should be the same as aAlarmTime. TSessionType aType The type of session alarm.

void CancelSessionAlarm();

Description

Cancels the outstanding session alarm, placed using the SetSessionAlarm() function.

TInt OrphanSessionAlarm();

Description

Orphans the session alarm. This allows the alarm to be serviced after the session is closed — for example, say, when Agenda is shut down.

Note:

• Each session can only have one session alarm, so it is not necessary to specify an alarm ID.

Return value

TInt KErrNone if successful, otherwise another of the system-wide error codes.

void NotifyOnChange(TRequestStatus& aStatus);

Description

Provides sessions with notification when the alarm settings change, and when the next alarm time should be calculated.

Parameters

TRequestStatus& aStatus A flag that indicates the completion status of the request.

void NotifyOnChangeCancel();

Description

Cancels an "Any change" notification request, placed using the NotifyOnChange() function.

TInt QuietPeriodSet(TTimeIntervalMinutes aQuietInterval);

Description

Defers all alarm sounds for a given interval.

Parameters

TTimeIntervalMinutes aQuietInterval The time interval for which all alarm sounds are to be deferred.

Return value

TInt KErrNone if successful, otherwise another of the system-wide error codes.

void QuietPeriodCancel();

Description

Cancels the alarm quiet period, set using the QuietPeriodSet() function.

TTime QuietPeriodUntil() const;

Description

Gets the time at which the alarm quiet period will end.

Return value

TTime The time at which the alarm is no longer quiet.

void SetAlarmSoundOn(TBool aSetSoundOn);

Description

Turns the sound for all alarms on or off.

Parameters

TBool aSetSoundOn ETrue = sounds on, EFalse = sounds off.

TInt SetAlarmPlayIntervals(const CArrayFix<TAlmSoundPlay>& aIntervals);

Description

Sets the list of alarm intervals.

Alarm intervals consist of a duration and an offset. The duration is the number of seconds the alarm sound plays. The offset is the number of minutes between the alarm being activated and the alarm sound beginning to play. The offset of the first interval must be zero, so that the alarm sound will play as soon as the alarm activates. The alarm server sorts the list of intervals in ascending order of offset. So, there must be one item in the list whose offset value is zero, but this does not have to be the first item in the list.

For example, if the sound array contains intervals of {0, 1, 2, 4, 10, 20} and durations of {30, 30, 30, 30, 30, 30}, then assuming the alarm expires at 9:00, then the sound will play at the following times:

• 9:00.00 -> 9:00.30

• 9:01.00 -> 9:01.30

• 9:02.00 -> 9:02.30

• 9:04.00 -> 9:04.30

• 9:10.00 -> 9:10.30

• 9:20.00 -> 9:20.30

Parameters

const CArrayFix<TAlmSoundPlay>& aIntervals An array that contains one or more alarm intervals. There must be one interval in the array with an offset of zero.

Return value

TInt An error code. KErrNone if successful, otherwise one of the standard error codes. KErrArgument is returned if aIntervals is empty, or if it does not contain an element with an offset of zero.

Notes:

• The alarm server defines a default alarm play interval list, so that this function only needs to be called in order to change the default behaviour.

TInt GetAlarmPlayIntervalsL(CArrayFix<TAlmSoundPlay>& aIntervals);

Description

Gets the list of alarm intervals.

The list of alarm intervals is managed by the alarm server. They are stored in ascending order of offset.

Parameters

CArrayFix<TAlmSoundPlay>& aIntervals On return, contains the list of alarm intervals.

Return value

TInt KErrNone if successful, otherwise one of the standard error codes.

TSessionType

Description

Specifies whether a session alarm is for a timed or an untimed event. The alarm type is set using the RAlarmServer::SetSessionAlarm() function.

ESessionTypeDay The alarm is an untimed event. In Agenda, this corresponds to an untimed day entry. ESessionTypeTimed The alarm is a timed event. In Agenda, this is associated with a timed entry, and remains linked to it.

TArrayCategory

Description

Defines the type of alarms to be put into an array. This enumeration is used by the AlarmArrayPopulateL() function.

EArrayNext The array is to contain pending alarms, including clock alarms, session alarms, orphaned alarms and snoozed alarms. EArrayReview The array is to contain review alarms. EArrayOrphan The array is to contain orphaned alarms. This will also include all snoozed alarms. EArraySnooze The array is to contain snoozed alarms.

TInfoCategory

Description

Defines the category of alarms for which information is required. This enumeration is used by the RAlarmServer::AlarmInfo() function.

EInfoById Get information for the alarm with the specified ID — irrespective of type. EInfoClock Get information for one of the 8 clock alarms. EInfoNext Get information for the next alarm which is due — irrespective of type. EInfoSession Get information for a session alarm.

TCountCategory

Description

Defines the category of the alarms to be counted using the RAlarmServer::AlarmCount() function.

ECountNext Count the number of pending alarms. ECountReview Count the number of review alarms. ECountOrphan Count the number of orphaned alarms. ECountSnooze Count the number of snoozed alarms. ECountUnacknowledged Count the number of unacknowledged alarms.