Class RASCliSession

class RASCliSession : public RSessionBase;

Description

The client-side interface to the Symbian OS alarm server.

Derivation

• RHandleBase - A handle to an object

• RSessionBase - Client-side handle to a session with a server

• RASCliSession - The client-side interface to the Symbian OS alarm server

Members

Defined in RASCliSession:
AlarmAdd(), AlarmAdd(), AlarmAddWithNotification(), AlarmAddWithNotification(), AlarmCountByState(), AlarmDataAttachL(), AlarmDataDetach(), AlarmDataDetatch(), AlarmDataSize(), AlarmDelete(), AlarmDeleteAllByCategory(), AlarmDeleteByCategory(), AlarmNotificationCancelAndDequeue(), AlarmSoundsTemporarilySilenced(), CancelAlarmSilence(), Connect(), GetAlarmCategory(), GetAlarmCharacteristics(), GetAlarmCountForCategory(), GetAlarmData(), GetAlarmData(), GetAlarmDayOrTimed(), GetAlarmDetails(), GetAlarmIdListByStateL(), GetAlarmIdListForCategoryL(), GetAlarmIdListL(), GetAlarmOwner(), GetAlarmPlayIntervalsL(), GetAlarmSoundState(), GetAlarmSoundsSilentUntil(), GetAlarmStatus(), GetAvailableCategoryListL(), GetNextDueAlarmId(), NotifyChange(), NotifyChangeCancel(), NumberOfAlarmsActiveInQueue(), RASCliSession(), SetAlarmCharacteristics(), SetAlarmDayOrTimed(), SetAlarmPlayIntervalsL(), SetAlarmSoundState(), SetAlarmSoundsSilentFor(), SetAlarmSoundsSilentUntil(), SetAlarmStatus(), SetAlarmStatusByCategory(), SetClientData(), Version()

Inherited from RHandleBase:
Attributes(), Close(), Duplicate(), FullName(), Handle(), HandleInfo(), Name(), SetHandle(), SetHandleNC(), iHandle

Inherited from RSessionBase:
CreateSession(), EAutoAttach, EExplicitAttach, Open(), Send(), SendReceive(), SetReturnedHandle(), ShareAuto(), ShareProtected(), TAttachMode

IMPORT_C RASCliSession();

Description

Default constructor.

Creates an instance of the RASCliSession class, setting its pointers to null.

Capability:

Illegal

IMPORT_C TInt Connect();

Description

Connects the client process to the alarm server, starting the server if it is not already running.

Return value

TInt KErrNone if successful, otherwise one of the system-wide errors.

Capability:

Illegal

IMPORT_C TVersion Version() const;

Description

Provides the version number of the alarm server.

Return value

TVersion The version number.

Capability:

WriteUserData

IMPORT_C TInt AlarmAdd(TASShdAlarm &aAlarm) const;

Description

Validates an alarm object, allocates an unique identifier to it, and adds the object synchronously to the alarm server's queue.

Parameters

TASShdAlarm &aAlarm The alarm object to add. On return, contains a unique identifier that the client can use to identify the alarm.

Return value

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

Capability:

WriteUserData

IMPORT_C TInt AlarmAdd(TASShdAlarm &aAlarm, const TDesC8 &aData) const;

Description

Validates an alarm object, allocates an unique identifier to it, and adds the object with data synchronously to the alarm server's queue.

Parameters

TASShdAlarm &aAlarm The alarm object to add. On return, contains a unique identifier that the client can use to identify the alarm. const TDesC8 &aData Client-specific data to associate with the alarm.

Return value

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

Capability:

WriteUserData

IMPORT_C void AlarmAddWithNotification(TRequestStatus &aStatus, TASShdAlarm &aAlarm);

Description

Makes an asynchronous request to add an alarm object to the alarm server's queue.

It also allocates a unique identifier of type TAlarmId to the alarm object and adds the alarm object to the alarm server's queue.

When the alarm expires, or is cancelled, the alarm server notifies the client by completing the outstanding request.

Parameters

TRequestStatus &aStatus On completion of the request, this object holds the completion code. TASShdAlarm &aAlarm The alarm to add. On return, contains the unique identifier. KNullAlarmId indicates failure.

Capability:

WriteUserData

IMPORT_C void AlarmAddWithNotification(TRequestStatus &aStatus, TASShdAlarm &aAlarm, const TDesC8 &aData);

Description

Makes an asynchronous request to add an alarm object with the agenda entry information attached to the alarm server's queue.

It also allocates a unique identifier of type TAlarmId to the alarm object and adds the alarm object to the alarm server's queue.

When the alarm expires, or is cancelled, the alarm server notifies the client by completing the outstanding request.

Parameters

TRequestStatus &aStatus On completion of the request, this object holds the completion code. TASShdAlarm &aAlarm The alarm to add. On return, contains the unique identifier. KNullAlarmId indicates failure. const TDesC8 &aData Client-specific data to associate with the alarm.

Capability:

Security policy note:

If the user does not have WriteDeviceData capability then we need to check that the alarm belongs to the user SID (The SID is stored as part of the alarm)

IMPORT_C void AlarmNotificationCancelAndDequeue(TAlarmId aAlarmId) const;

Description

Cancels an outstanding notification for an alarm and removes it from the queue.

Parameters

TAlarmId aAlarmId The unique identifier of the alarm to be cancelled.

Capability:

Security policy note:

If the user does not have ReadUserData capability then we need to check that the alarm belongs to the user SID (The SID is stored as part of the alarm)

IMPORT_C TInt GetAlarmDetails(TAlarmId aAlarmId, TASShdAlarm &aAlarm) const;

Description

Retrieves information about a specified alarm.

Parameters

TAlarmId aAlarmId The unique identifier of the alarm under query. TASShdAlarm &aAlarm On return, contains details of the alarm sought.

Return value

TInt KErrNone if successful, KErrCouldNotConnect if the time zone server is not available, otherwise one of the other system-wide error codes.

Capability:

Security policy note:

If the user does not have WriteDeviceData capability then we need to check that the alarm belongs to the user SID (The SID is stored as part of the alarm)

IMPORT_C TInt AlarmDelete(TAlarmId aAlarmId) const;

Description

Deletes an alarm from the alarm server.

Parameters

TAlarmId aAlarmId The unique identifier of the alarm to be deleted.

Return value

TInt KErrNone if successful, KErrNotFound if the specified alarm does not exist, KErrAccessDenied if the alarm has an outstanding notification, or else one of the system-wide error codes.

Capability:

Illegal

IMPORT_C TInt GetAlarmCategory(TAlarmId aAlarmId, TAlarmCategory &aCategory) const;

Description

Retrieves the category of an alarm.

Parameters

TAlarmId aAlarmId The unique identifier of the alarm under query. TAlarmCategory &aCategory On return, contains the category of the alarm.

Return value

TInt KErrNone if successful, KErrNotFound if the alarm does not exist, otherwise one of the system-wide error codes.

Capability:

Illegal

IMPORT_C TInt GetAlarmOwner(TAlarmId aAlarmId, TFullName &aThreadName) const;

Description

Retrieves the full name of the thread that owns the specified alarm.

Parameters

TAlarmId aAlarmId The unique identifier of the alarm under query. TFullName &aThreadName On return, contains the name of the owning session.

Return value

TInt KErrNone if successful, KErrNotFound if the alarm has no originating session ID or if the session is no longer connected, otherwise one of the system-wide errors.

Capability:

Security policy note:

If the user does not have WriteDeviceData capability then we need to check that the alarm belongs to the user SID (The SID is stored as part of the alarm)

IMPORT_C TInt SetAlarmStatus(TAlarmId aAlarmId, TAlarmStatus aStatus) const;

Description

Sets an alarm's status to either enabled or disabled.

Parameters

TAlarmId aAlarmId Unique identifier of the alarm. TAlarmStatus aStatus Contains the status to be applied.

Return value

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

Capability:

Illegal

IMPORT_C TInt GetAlarmStatus(TAlarmId aAlarmId, TAlarmStatus &aStatus) const;

Description

Retrieves the status of the alarm.

Parameters

TAlarmId aAlarmId The unique identifier of an alarm under query. TAlarmStatus &aStatus On return, the alarm status.

Return value

TInt KErrNone if successful, KErrNotFound if the alarm does not exist, otherwise one of the system-wide errors.

Capability:

Security policy note:

If the user does not have WriteDeviceData capability then we need to check that the alarm belongs to the user SID (The SID is stored as part of the alarm)

IMPORT_C TInt SetAlarmDayOrTimed(TAlarmId aAlarmId, TAlarmDayOrTimed aDayOrTimed) const;

Description

Specifies whether an alarm belongs to a timed or untimed event.

Parameters

TAlarmId aAlarmId Unique identifier of the alarm. TAlarmDayOrTimed aDayOrTimed Whether an alarm is for a timed or untimed event.

Return value

TInt KErrNone if successful, otherwise one of the system-wide errors.

Capability:

Illegal

IMPORT_C TInt GetAlarmDayOrTimed(TAlarmId aAlarmId, TAlarmDayOrTimed &aDayOrTimed) const;

Description

Tests whether the specified alarm is for a timed or untimed event.

Parameters

TAlarmId aAlarmId Unique identifier of the alarm under query. TAlarmDayOrTimed &aDayOrTimed On return, whether an alarm is for a timed or untimed event.

Return value

TInt KErrNone if successful, otherwise one of the system-wide errors.

Capability:

Security policy note:

If the user does not have WriteDeviceData capability then we need to check that the alarm belongs to the user SID (The SID is stored as part of the alarm)

IMPORT_C TInt SetAlarmCharacteristics(TAlarmId aAlarmId, TAlarmCharacteristicsFlags aCharacteristics) const;

Description

Sets the characteristics of a specified alarm.

If the session-specific flag is removed, the outstanding notification is completed.

Parameters

TAlarmId aAlarmId Unique identifier of the alarm. TAlarmCharacteristicsFlags aCharacteristics Alarm characteristics to apply.

Return value

TInt KErrNone if successful, otherwise one of the system-wide errors.

Capability:

Illegal

IMPORT_C TInt GetAlarmCharacteristics(TAlarmId aAlarmId, TAlarmCharacteristicsFlags &aCharacteristics) const;

Description

Gets the characteristics of an alarm.

Parameters

TAlarmId aAlarmId Unique identifier of the alarm under query. TAlarmCharacteristicsFlags &aCharacteristics On return, contains the charcteristics of the alarm specified.

Return value

TInt KErrNone if successful, otherwise one of the system-wide errors.

Capability:

Security policy note:

If the user does not have WriteDeviceData capability then we need to check that the alarm belongs to the user SID (The SID is stored as part of the alarm)

IMPORT_C TInt SetClientData(const TASShdAlarm &aAlarm);

Description

Updates an alarm's client-specific data in the alarm server.

The TASShdAlarm class contains a number of client-specific fields. These fields are for use by clients of the alarm server to hold any data associated with an alarm. Although this data is not used in any way by the alarm server itself, clients can ensure that the alarm server keeps its own copy of the specified alarm up to date with that of the client.

Parameters

const TASShdAlarm &aAlarm The client-side alarm, whose corresponding server-side alarm is to be updated.

Return value

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

Capability:

Security policy note:

If the user does not have WriteDeviceData capability then we need to check that the alarm belongs to the user SID (The SID is stored as part of the alarm)

IMPORT_C TInt AlarmDataAttachL(TAlarmId aAlarmId, const TDesC8 &aData) const;

Description

Associates the specified data with an alarm.

This is arbitrary client-specific data, for which the alarm server simply acts as a router.

Parameters

TAlarmId aAlarmId Unique identifier of the alarm. const TDesC8 &aData Client-specific data to associate with the alarm.

Return value

TInt KErrNone if successful, KErrInUse if the specified alarm already has data assigned to it, or one of the system-wide error codes.

Capability:

Security policy note:

If the user does not have WriteDeviceData capability then we need to check that the alarm belongs to the user SID (The SID is stored as part of the alarm)

IMPORT_C TInt AlarmDataDetach(TAlarmId aAlarmId) const;

Description

Removes any previously attached alarm data from the specified alarm.

This releases any resources allocated by the alarm server for this alarm.

Parameters

TAlarmId aAlarmId Unique identifier for the alarm.

Return value

TInt KErrNone if successful, KErrNotFound if the specified alarm does not exist (or the specified alarm does not have any data), or another of the system-wide error codes.

inline TInt AlarmDataDetatch(TAlarmId aAlarmId) const;

Description

RASCliSession::AlarmDataDetach() should be used instead

Parameters

TAlarmId aAlarmId

Return value

TInt

Capability:

Illegal

IMPORT_C TInt AlarmDataSize(TAlarmId aAlarmId) const;

Description

Returns the size in bytes of any data associated with the specified alarm.

Parameters

TAlarmId aAlarmId Unique identifier of the alarm under query.

Return value

TInt The size in bytes of the alarm's data, or an error. KErrNotFound is returned if the specified alarm does not have any associated data.

Capability:

Security policy note:

If the user does not have ReadUserData capability then we need to check that the alarm belongs to the user SID (The SID is stored as part of the alarm)

IMPORT_C TInt GetAlarmData(TAlarmId aAlarmId, TDes8 &aSink) const;

Description

Retrieves the data attached to the specified alarm.

This is data previously attached using AlarmDataAttachL().

Parameters

TAlarmId aAlarmId Unique identifier of the alarm under query. TDes8 &aSink On return, contains the data associated with the alarm. This buffer must be large enough to contain all the data or a panic occurs.

Return value

TInt KErrNone if successful, KErrNotFound if the specified alarm does not have any associated data, or a system-wide error.

Capability:

Security policy note:

If the user does not have ReadUserData capability then we need to check that the alarm belongs to the user SID (The SID is stored as part of the alarm)

IMPORT_C TInt GetAlarmData(TAlarmId aAlarmId, HBufC8 *&aSink) const;

Description

Retrieves the data attached to the specified alarm.

This is data previously attached using AlarmDataAttachL().

Parameters

TAlarmId aAlarmId Unique identifier of the alarm under query. HBufC8 *&aSink On return, contains the data associated with the alarm, or NULL if the specified alarm does not have any associated data, or an error was returned.

Return value

TInt KErrNone if successful, KErrNotFound if the specified alarm does not have any associated data, or a system-wide error.

Capability:

Security policy note:

If the user does not have WriteDeviceData capability then we need to check that the alarm belongs to the user SID (The SID is stored as part of the alarm)

IMPORT_C TInt SetAlarmStatusByCategory(TAlarmCategory aCategory, TAlarmStatus aStatus) const;

Description

Set the status of all alarms in the specified category.

Parameters

TAlarmCategory aCategory An alarm category. TAlarmStatus aStatus An alarm status.

Return value

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

Capability:

Illegal

IMPORT_C TInt GetAlarmCountForCategory(TAlarmCategory aCategory) const;

Description

Returns the number of alarms in a specified category.

Parameters

TAlarmCategory aCategory Category of alarm under query.

Return value

TInt Number of alarms in the specified category, or, if negative, one of the standard error codes..

Capability:

Security policy note:

If the user does not have WriteDeviceData capability then we need to check that the alarm belongs to the user SID (The SID is stored as part of the alarm)

IMPORT_C TInt AlarmDeleteAllByCategory(TAlarmCategory aCategory, TBool aDeleteOnlyOrphanedAlarmsInCategory) const;

Description

Deletes all alarms in the queue corresponding to a specified category.

You can also specify that only the orphaned alarms of that category be deleted.

Parameters

TAlarmCategory aCategory Category of alarms to be deleted. TBool aDeleteOnlyOrphanedAlarmsInCategory ETrue: delete only orphaned alarms within the category. EFalse: delete all alarms within the category.

Return value

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

Capability:

Security policy note:

If the user does not have WriteDeviceData capability then we need to check that the alarm belongs to the user SID (The SID is stored as part of the alarm)

IMPORT_C TInt AlarmDeleteByCategory(TAlarmCategory aCategory, TDeleteType aWhatToDelete) const;

Description

Deletes alarms in the queue corresponding to a specified category and type.

Parameters

TAlarmCategory aCategory Category of alarms to be deleted. TDeleteType aWhatToDelete specify what type of alarms to delte within the category.

Return value

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

Capability:

Illegal

IMPORT_C void GetAvailableCategoryListL(RArray< TAlarmCategory > &aCategories) const;

Description

Retrieves a list of all alarm categories in use within the alarm server.

Parameters

RArray< TAlarmCategory > &aCategories On return, contains the list of available categories.

Capability:

Illegal

IMPORT_C void GetAlarmIdListForCategoryL(TAlarmCategory aCategory, RArray< TAlarmId > &aAlarmIds) const;

Description

Retrieves a list of all alarm identifiers for alarms within the server of a specified category.

Parameters

TAlarmCategory aCategory Category of alarms to find. RArray< TAlarmId > &aAlarmIds On return, contains the list of alarms.

Capability:

Illegal

IMPORT_C TInt AlarmCountByState(TAlarmState aState) const;

Description

Returns the number of alarms in a specified state.

Parameters

TAlarmState aState Alarm state of interest.

Return value

TInt Number of alarms in the specified state.

Capability:

Illegal

IMPORT_C void GetAlarmIdListByStateL(TAlarmState aState, RArray< TAlarmId > &aAlarmIds) const;

Description

Retrieves a list of the unique identifiers of all alarms in a specified state.

Parameters

TAlarmState aState Alarm state that you are interested in. RArray< TAlarmId > &aAlarmIds On return, contains the unique identifiers of the alarms in the specified state.

Capability:

Illegal

IMPORT_C void GetAlarmIdListL(RArray< TAlarmId > &aAlarmIds) const;

Description

Retrieves a list of the unique identifiers of all the alarms in the alarm server.

Parameters

RArray< TAlarmId > &aAlarmIds On return, contains a list of unique identifiers.

Capability:

Illegal

IMPORT_C TInt GetNextDueAlarmId(TAlarmId &aAlarmId) const;

Description

Retrieves the unique identifier of the next alarm in the alarm server queue.

Parameters

TAlarmId &aAlarmId On return, contains the unique identifier of the next alarm due.

Return value

TInt KErrNone if successful, KNullAlarmId if there are no alarms in the queue, otherwise another one of the system-wide error codes.

Capability:

Illegal

IMPORT_C TInt NumberOfAlarmsActiveInQueue() const;

Description

Returns the number of alarms that are currently active within the alarm queue. Active alarms are:

Alarms that have not yet notified.

Alarms that are in the queued or snoozed state, and are enabled.

Return value

TInt Number of active alarms, or an error code.

Capability:

WriteDeviceData

IMPORT_C TInt SetAlarmSoundState(TAlarmGlobalSoundState aState) const;

Description

Sets the alarm sound state to on or off.

Parameters

TAlarmGlobalSoundState aState The alarm sound state.

Return value

TInt KErrNone if successful, otherwise one of the system-wide errors.

Capability:

Illegal

IMPORT_C TInt GetAlarmSoundState(TAlarmGlobalSoundState &aState) const;

Description

Retrieves the alarm sound state. The alarm sound can be on or off.

Parameters

TAlarmGlobalSoundState &aState On return, contains the alarm sound state.

Return value

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

Capability:

WriteDeviceData

IMPORT_C TInt SetAlarmSoundsSilentUntil(const TTime &aLocalTime) const;

Description

Disables alarm sounds until a specified time.

Alarms still expire and clients are notified during this period, but no sound is played.

Parameters

const TTime &aLocalTime Time, in local time, when alarm sounds are to be played once more.

Return value

TInt KErrNone if successful, KErrArgument if the time is in the past, otherwise another one of the system-wide error codes.

Capability:

WriteDeviceData

IMPORT_C TInt SetAlarmSoundsSilentFor(TTimeIntervalMinutes aTimeToRemainSilentFor) const;

Description

Disables alarm sounds for a specified interval.

Alarms still expire and clients are notified during this period, but no sound is played.

NOTE: If user or some application changes system time or UTC offset (for example by using User::SetUTCOffset(), User::SetHomeTime(), User::SetUTCTimeAndOffset() etc) the silent periond will be cancelled.

Parameters

TTimeIntervalMinutes aTimeToRemainSilentFor Time interval in minutes, during which no sound is to be played.

Return value

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

Capability:

Illegal

IMPORT_C TInt GetAlarmSoundsSilentUntil(TTime &aLocalTime) const;

Description

Retrieves the time at which all alarm sounds resume.

Parameters

TTime &aLocalTime On return, contains the time, in local time, when sounds resume.

Return value

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

Capability:

WriteDeviceData

IMPORT_C TInt CancelAlarmSilence() const;

Description

Cancels the silent period, turning the alarm sounds on.

Return value

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

Capability:

Illegal

IMPORT_C TBool AlarmSoundsTemporarilySilenced() const;

Description

Tests whether the alarm server has temporarily disabled sounds.

Return value

TBool ETrue: alarms are temporarily silent. EFalse: sounds are not silent.

Capability:

WriteDeviceData

IMPORT_C void SetAlarmPlayIntervalsL(const CArrayFix< TASCliSoundPlayDefinition > &aIntervals) const;

Description

Sets the list of alarm intervals.

Alarm intervals consist of a duration and an offset.

Parameters

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

Leave codes

KErrGeneral If the array is inappropriate, for example, if intervals overlap or has no elements. Also, from v9.2 onwards, if the array has only one element and the Repeat Setting is set to RepeatLast. KErrArgument If no interval has an offset of zero. KErrNotSupported The Alarm Play Intervals cannot be set because Alarm Play Intervals is disabled by resource file. (from v9.2 onwards)

Capability:

Illegal

IMPORT_C void GetAlarmPlayIntervalsL(CArrayFix< TASCliSoundPlayDefinition > &aIntervals) const;

Description

Retrieves the list of alarm intervals.

They are stored in ascending order of offset.

Parameters

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

Capability:

Illegal

IMPORT_C void NotifyChange(TRequestStatus &aStatus, TAlarmId &aAlarmId);

Description

Enables client notification when alarm settings change, and when the next alarm time is calculated.

A panic occurs if notification is already active.

Parameters

TRequestStatus &aStatus The request status object that is to be signalled. On return, contains one of the TAlarmChangeEvent enumeration values. If an error occurs, the TRequestStatus object contains one of the standard system-wide error codes. TAlarmId &aAlarmId An alarm identifier relating to the type of event that took place. If the type of event that occurred relates to a particular alarm, this object is populated with that alarm's identiifer. Otherwise it contains an undefined value.

See also:

• TAlarmChangeEvent

Capability:

Illegal

IMPORT_C void NotifyChangeCancel() const;

Description

Cancels any previous change notification request.

Panic codes

Panics with AlarmClientUtils::EAlarmClientPanicNotificationCancel if the notification fails to occur.