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

• CBase - Base class for all classes to be instantiated on the heap

• CCalSession - A handle to the calendar file

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

• Class Summary

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.

Capability:

Illegal

IMPORT_C ~CCalSession();

Description

Destructor for the session. Clear away any resources.

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.

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.

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.

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.

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:

• The calendar files can be stored on any drive.

• Since the directories are not seen by clients, the filenames returned are a combination of drive letter and file name, in other words DriveLetter:FileName

• The files are ordered alphabetically by drive letter. Files on the same drive are ordered by filename, for instance a:agenda, c:agenda, c:calendar, d:agenda, d:calendar.

Return value

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

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.

Capability:

Illegal

IMPORT_C void StopChangeNotification();

Description

Stop all notifications from this session.

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.

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.

Capability:

Illegal

IMPORT_C void EnablePubSubNotificationsL();

Description

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

Capability:

Illegal

IMPORT_C void DisablePubSubNotificationsL();

Description

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

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.

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.

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

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

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.