Symbian
Symbian OS Library

SYMBIAN OS V9.3

[Index] [Spacer] [Previous] [Next]



Location: calsession.h
Link against: calinterimapi.lib

Class CCalSession

class CCalSession : public CBase;

Description

A handle to the calendar file.

When the client instantiates a CCalSession, it will connect to the calendar server. In turn, the client can use its APIs, for instance to create or open a calendar file.

The agenda data in the file can be accessed as entries. To access the entries, clients should use class CCalEntryView or CCalInstanceView to process the entry data. However, both view classes require the handle to the file which is represented by this class.

Derivation

Members

Defined in CCalSession:
CreateCalFileL(), DefaultFileNameL(), DeleteCalFileL(), DisableChangeBroadcast(), DisablePubSubNotificationsL(), EnableChangeBroadcast(), EnablePubSubNotificationsL(), FileIdL(), GetFileNameL(), IsFileNameL(), IsOpenedFileL(), ListCalFilesL(), NewL(), OpenL(), StartChangeNotification(), StartChangeNotification(), StopChangeNotification(), ~CCalSession()

Inherited from CBase:
Delete(), Extension_(), operator new()

See also


Construction and destruction


NewL()

Capability: Illegal

static IMPORT_C CCalSession *NewL();

Description

Allocates and constructs a session to the Calendar server.

Return value

CCalSession *

Pointer to the newly created session.


~CCalSession()

Capability: Illegal

IMPORT_C ~CCalSession();

Description

Destructor for the session. Clear away any resources.

[Top]


Member functions


CreateCalFileL()

Capability: WriteUserData

IMPORT_C void CreateCalFileL(const TDesC &aFileName) const;

Description

Creates a new calendar file. It leaves if the file with the name specified already exists.

Parameters

const TDesC &aFileName

The name of the file to create. This is a combination of drive letter and file name, in other words, DriveLetter:FileName, but not a full path.


OpenL()

Capability: ReadUserData

IMPORT_C void OpenL(const TDesC &aFileName) const;

Description

Opens an calendar file using the server.

If another agenda file is open in the same server session, it is closed.

Parameters

const TDesC &aFileName

The agenda file to open. This is a combination of drive letter and file name, in other words, DriveLetter:FileName, but not a full path. It leaves if a path is included explicitly. A default file is opened if aFileName is KNullDesC.

Leave codes

KErrEof

If the calendar file is corrupt and cannot be opened because an unexpected end of file was reached.

KErrCorrupt

If the calendar file is corrupt and cannot be opened.


DefaultFileNameL()

Capability: Illegal

IMPORT_C const TDesC &DefaultFileNameL() const;

Description

Gets the name of the default calendar file held by the server.

Return value

const TDesC &

The default filename. This is a combination of a drive letter and a file name, in other words, DriveLetter:FileName but not a full path.


DeleteCalFileL()

Capability: WriteUserData

IMPORT_C void DeleteCalFileL(const TDesC &aFileName) const;

Description

Deletes a calendar file with the supplied filename.

If the file is opened, it will be closed first

Parameters

const TDesC &aFileName

The combination of drive letter and file name, in other words, DriveLetter:FileName, but not a full path

Leave codes

KErrNotSupported

aFileName includes a path explicitly.

KErrNotFound

The agenda file has not been found.

KErrBadArgument

The length of aFileName is zero.


ListCalFilesL()

Capability: Illegal

IMPORT_C CDesCArray *ListCalFilesL() const;

Description

Gets a list of all calendar files held by the server. The caller takes ownership of the returned descriptor array. Note that:

Return value

CDesCArray *

A list of filenames of the Agenda files held by the server. This is NULL if no file has been found.


StartChangeNotification()

Capability: Illegal

IMPORT_C void StartChangeNotification(MCalChangeCallBack2 &aCallBack, const CCalChangeNotificationFilter &aFilter);

Description

Start notification of any changes to calendar entries. These changes can be filtered, and when a change occurs the MCalChangeCallBack2 callback function is called with details about the entry which has changed (TCalLocalUid and entry type) and the type of change (add/delete/modify).

Parameters

MCalChangeCallBack2 &aCallBack

The class to notify when a change occurs.

const CCalChangeNotificationFilter &aFilter

Filter notifications to only notify on certain types of entries.


StopChangeNotification()

Capability: Illegal

IMPORT_C void StopChangeNotification();

Description

Stop all notifications from this session.


DisableChangeBroadcast()

Capability: Illegal

IMPORT_C void DisableChangeBroadcast();

Description

Disable all notifications from changes made within this session. Changes made within other sessions will still be notified. This can be done before a bulk operation, to prevent a large number of notifications from appearing. Note that this call does not disable publish and subscribe notifications. That must be done from DisablePubSubNotificationsL.


EnableChangeBroadcast()

Capability: Illegal

IMPORT_C void EnableChangeBroadcast();

Description

Re-enable all notifications from changes made within this session. This function has the opposite effect of DisableChangeBroadcast.


EnablePubSubNotificationsL()

Capability: Illegal

IMPORT_C void EnablePubSubNotificationsL();

Description

Enable Publish and Subscribe notifications for changes made by this client only.


DisablePubSubNotificationsL()

Capability: Illegal

IMPORT_C void DisablePubSubNotificationsL();

Description

Disable Publish and Subscribe notifications for changes made by this client only.


FileIdL()

Capability: Illegal

IMPORT_C void FileIdL(TCalFileId &aCalFileId) const;

Description

Gets the file ID of the currently open Calendar file. This is unique to the file.

Parameters

TCalFileId &aCalFileId

On return will be the file ID of the currently open Calendar file.


GetFileNameL()

Capability: Illegal

IMPORT_C void GetFileNameL(TCalPubSubData aPubSubData, TDes &aFileName) const;

Description

Retrieve a calendar file name from its hash value. The hash value comes from the Publish and Subscribe CalInterimAPI data in TCalPubSubData.

Parameters

TCalPubSubData aPubSubData

TDes &aFileName

On return will be the full file name.


IsFileNameL()

Capability: Illegal

IMPORT_C TBool IsFileNameL(TCalPubSubData aPubSubData, const TDesC &aFileName) const;

Description

Test if the full file name passed is the one that was changed.

Parameters

TCalPubSubData aPubSubData

The publish and subscribe data.

const TDesC &aFileName

The full file name to test.

Return value

TBool


IsOpenedFileL()

Capability: Illegal

IMPORT_C TBool IsOpenedFileL(TCalPubSubData aPubSubData) const;

Description

Test if the publish and subscribe data relates to the currently open calendar file.

Parameters

TCalPubSubData aPubSubData

The publish and subscribe data.

Return value

TBool


StartChangeNotification()

Capability: Illegal

IMPORT_C void StartChangeNotification(MCalChangeCallBack *aCallBack, MCalChangeCallBack::TChangeEntryType aChangeEntryType, TBool aIncludeUndatedTodos, TTime aFilterStartTime, TTime aFilterEndTime);

Description

Start notification of any changes to calendar entries. These changes can be filtered, and when a change occurs the MCalChangeCallBack callback function is called with the type of entry which has changed (event or todo).

Parameters

MCalChangeCallBack *aCallBack

The class to notify when a change occurs.

MCalChangeCallBack::TChangeEntryType aChangeEntryType

Filter notifications to only notify on entries of the specified type (event/todo/all).

TBool aIncludeUndatedTodos

Filter notifications to include undated todos.

TTime aFilterStartTime

Filter notification to only include entries that are wholly or partly covered by a time range. This specifies the start time of the time range.

TTime aFilterEndTime

Filter notification to only include entries that are wholly or partly covered by a time range. This specifies the end time of the time range.