EPOC   SDK Home Glossary Indexes Previous Next Up

RAlarmServer class


Contents


RAlarmServer class — Alarm server session

Section Contents


Overview

Derivation

RHandleBase

Abstract: handle to an object

RSessionBase

Abstract: base class for handle to a session

Defined in

t32alm.h

Link against

ealwl.lib

Description

This class 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.


Connecting to the alarm server


Connect() — Connect to the alarm server

TInt Connect();

Description

This function connects a client process to the alarm server.

Return value

TInt

An error code: see System error codes.

Note

Version() — Get version number

TVersion Version() const;

Description

This function returns 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 SDK documentation.

Return value

TVersion

The version number.


Alarm information


AlarmCount() — Count alarms

TInt AlarmCount(TCountCategory aCategory) const;

Description

This function retrieves the number of alarms in a particular category.

Arguments

TCountCategory aCategory

The category of alarm being counted.

Return value

TInt

An error code: see System error codes.


AlarmState() — Get alarm state

TAlarmSetState AlarmState(TInt aAlarmId) const;

Description

This function is used to determine whether a given alarm is set, not set, or disabled.

Arguments

TInt aAlarmId

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

Return value

TAlarmSetState

The current state of the alarm.


AlarmInfo() — Get alarm information

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

Description

This function retrieves 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).

Arguments

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

An error code: see System error codes.


AlarmSoundState() — Get the alarm server sound state

TAlarmSoundState AlarmSoundState() const;

Description

This function returns 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.


AlarmType() — Get alarm type

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

Description

This function retrieves the type of the specified alarm.

Arguments

TAlarmType& aType

On return, contains the alarm type.

TInt aAlarmId

The ID of the alarm.

Return value

TInt

An error code: see System error codes.


AlarmOwner() — Get the owner’s name for the alarm

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

Description

This function returns the owner’s name for an alarm.

Arguments

TFullName& aName

On return, contains the owner’s name for the alarm.

TInt aAlarmId

The ID of the alarm.

Return value

TInt

An error code: see System error codes.


AlarmArrayPopulateL() — Populate alarm array

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

Description

This function 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.

Arguments

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.


Enable/delete alarms


AlarmEnable() — Enable/disable an alarm

TInt AlarmEnable(TBool aShouldEnable,TInt aAlarmId);

Description

This function is used to enable or disable alarms.

Arguments

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

An error code: see System error codes.

Notes:

AlarmDelete() — Delete an alarm

TInt AlarmDelete(TInt aAlarmId);

Description

This function deletes an alarm from the alarm server.

Arguments

TInt aAlarmId

The ID of the alarm to be deleted.

Return value

TInt

An error code: see System error codes.


Setting/Orphaning alarms


SetClockAlarm() — Set clock alarm

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

Description

This function sets a new clock alarm.

Arguments

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.

Note

SetSessionAlarm() — Set session alarm

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

Description

This function sets the session alarm.

Arguments

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.

Notes

CancelSessionAlarm() — Cancel session alarm

void CancelSessionAlarm();

Description

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


OrphanSessionAlarm() — Orphan session alarm

TInt OrphanSessionAlarm();

Description

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

Return value

TInt

An error code: see System error codes.

Note

Notification functions


NotifyOnChange() — Notification of any change in alarm status

void NotifyOnChange(TRequestStatus& aStatus);

Description

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

Arguments

TRequestStatus& aStatus

A flag that indicates the completion status of the request.


NotifyOnChangeCancel() — Cancel notification of any change in alarm status

void NotifyOnChangeCancel();

Description

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


Alarm quiet periods


QuietPeriodSet() — Set alarm quiet period

TInt QuietPeriodSet(TTimeIntervalMinutes aQuietInterval);

Description

This function defers all alarm sounds for a given interval.

Arguments

TTimeIntervalMinutes aQuietInterval

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

Return value

TInt

An error code: see System error codes.


QuietPeriodCancel() — Cancel alarm quiet period

void QuietPeriodCancel();

Description

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


QuietPeriodUntil() — Get period that alarms are quiet

TTime QuietPeriodUntil() const;

Description

This function returns the time at which the alarm quiet period will end.

Return value

TTime

The time at which the alarm is no longer quiet.


SetAlarmSoundOn() — Turn alarm sounds on/off

void SetAlarmSoundOn(TBool aSetSoundOn);

Description

This function turns the sound for all alarms on or off.

Arguments

TBool aSetSoundOn

ETrue = sounds on, EFalse = sounds off.


Enumerations


TSessionType enum — Session type

This enumeration 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 enum — Array category flags

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

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 enum — Categories of alarm for getting information

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

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 enum — Categories of alarm for counting

This enumeration is used by the RAlarmServer::AlarmCount() function to define the category of the alarms which are to be counted.

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.

EPOC       SDK Home Glossary Indexes Previous Next Up