CCalSession Class Reference

class CCalSession : public CBase

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.

A calendar file can be opened on any writable drive. Note that if the file is opened on a removable media and that media is removed, operations will leave with KErrNotReady. This error can also happen when trying to access file attachments on removed media. When this error occurs, the user should close the CCalSession and re-open it once the media has been replaced. It is recommended that when using a calendar file on removable media, the user should watch for when the media is removed / replaced using the RFs::NotifyChange API.

The session object must not be destroyed until all the objects which where created by referencing it have been destroyed.

Inherits from

Public Member Functions
~CCalSession()
IMPORT_C CCalCalendarInfo *CalendarInfoL()
IMPORT_C TCalCollectionIdCollectionIdL()
IMPORT_C voidCreateCalFileL(const TDesC &)
IMPORT_C voidCreateCalFileL(const TDesC &, const CCalCalendarInfo &)
IMPORT_C const TDesC &DefaultFileNameL()
IMPORT_C voidDeleteCalFileL(const TDesC &)
IMPORT_C voidDisableChangeBroadcast()
IMPORT_C voidDisablePubSubNotificationsL()
IMPORT_C voidEnableChangeBroadcast()
IMPORT_C voidEnablePubSubNotificationsL()
IMPORT_C voidFileIdL(TCalFileId &)
IMPORT_C voidGetFileNameL(TCalPubSubData, TDes &)
CCalSessionImpl &Impl()
IMPORT_C TBoolIsFileNameL(TCalPubSubData, const TDesC &)
IMPORT_C TBoolIsOpenedFileL(TCalPubSubData)
IMPORT_C CDesCArray *ListCalFilesL()
IMPORT_C CCalSession *NewL()
IMPORT_C CCalSession *NewL(CCalSession &)
IMPORT_C voidOpenL(const TDesC &)
IMPORT_C voidOpenL(const TDesC &, CalCommon::TCalFileVersionSupport &)
IMPORT_C voidSetCalendarInfoL(const CCalCalendarInfo &)
IMPORT_C voidStartChangeNotification(MCalChangeCallBack2 &, const CCalChangeNotificationFilter &)
IMPORT_C voidStartChangeNotification(MCalChangeCallBack *, MCalChangeCallBack::TChangeEntryType, TBool, TTime, TTime)
IMPORT_C voidStartFileChangeNotificationL(MCalFileChangeObserver &)
IMPORT_C voidStopChangeNotification()
IMPORT_C voidStopFileChangeNotification()
IMPORT_C TInt_DebugRequestAllocatedCellsL()
IMPORT_C TInt_DebugRequestAllocatedHeapSizeL()
IMPORT_C void_DebugSetHeapFailL(RAllocator::TAllocFail, TInt)
IMPORT_C void__dbgClearTzClientCacheL(TBool)
Private Member Functions
CCalSession()
voidConstructL()
voidConstructL(CCalSession &)
Inherited Functions
CBase::CBase()
CBase::Delete(CBase *)
CBase::Extension_(TUint,TAny *&,TAny *)
CBase::operator new(TUint)
CBase::operator new(TUint,TAny *)
CBase::operator new(TUint,TLeave)
CBase::operator new(TUint,TLeave,TUint)
CBase::operator new(TUint,TUint)
CBase::~CBase()
Private Attributes
CCalSessionImpl *iImpl

Constructor & Destructor Documentation

CCalSession()

CCalSession()[private]

~CCalSession()

IMPORT_C~CCalSession()
Destructor for the session. Clear away any resources.
capability
None

Member Functions Documentation

CalendarInfoL()

IMPORT_C CCalCalendarInfo *CalendarInfoL()const
Get calendar info on the currently open calendar file.
leave
KErrNotReady If there is no calendar file open on this CCalSession.
capability
ReadUserData

CollectionIdL()

IMPORT_C TCalCollectionIdCollectionIdL()const

Gets the Collection ID of the currently open Calendar file. Note that:

This ID should not be persisted because it is re-generated whenever the session is connected. This ID identifies the same Calendar file as the file ID retrieved form CCalSession::FileIdL(TCalFileId& aCalFileId)

capability
None

ConstructL()

voidConstructL()[private]

ConstructL(CCalSession &)

voidConstructL(CCalSession &aCalSession)[private]

Parameters

CCalSession & aCalSession

CreateCalFileL(const TDesC &)

IMPORT_C voidCreateCalFileL(const TDesC &aFileName)const
Creates a new calendar file.
leave
KErrNotReady If the calendar file is on a drive where the media has been removed.
capability
WriteUserData
It leaves if the file with the name specified already exists.

Parameters

const TDesC & aFileNameThe 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.

CreateCalFileL(const TDesC &, const CCalCalendarInfo &)

IMPORT_C voidCreateCalFileL(const TDesC &aFileName,
const CCalCalendarInfo &aCalendarInfo
)const
Creates a new calendar file.
leave
KErrNotReady If the calendar file is on a drive where the media has been removed.
capability
WriteUserData
It leaves if the file with the name specified already exists.

Parameters

const TDesC & aFileNameThe 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.
const CCalCalendarInfo & aCalendarInfoThe calendar info to set on the file.

DefaultFileNameL()

IMPORT_C const TDesC &DefaultFileNameL()const
Gets the name of the default calendar file held by the server.
capability
None

DeleteCalFileL(const TDesC &)

IMPORT_C voidDeleteCalFileL(const TDesC &aFileName)const

Deletes a calendar file with the supplied filename. If the file is opened, it will be closed first

This also deletes all calendar attachment files referenced from this calendar store - these are the ones moved when the calendar has taken ownership of the file through the CCalAttachment::NewL APIs. Attachment files stored on a different drive to the calendar file will not be deleted.

capability
WriteUserData
leave
KErrNotSupported aFileName includes a path explicitly.
leave
KErrNotFound The agenda file has not been found.
leave
KErrBadArgument The length of aFileName is zero.
leave
KErrInUse One of the attachment file handles from this calendar store is still open.
leave
KErrNotReady If the calendar file is on a drive where the media has been removed.

Parameters

const TDesC & aFileNameThe combination of drive letter and file name, in other words, DriveLetter:FileName, but not a full path

DisableChangeBroadcast()

IMPORT_C voidDisableChangeBroadcast()
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
None

DisablePubSubNotificationsL()

IMPORT_C voidDisablePubSubNotificationsL()
Disable Publish and Subscribe notifications for changes made by this client only.
capability
None

EnableChangeBroadcast()

IMPORT_C voidEnableChangeBroadcast()
Re-enable all notifications from changes made within this session. This function has the opposite effect of DisableChangeBroadcast.
capability
None

EnablePubSubNotificationsL()

IMPORT_C voidEnablePubSubNotificationsL()
Enable Publish and Subscribe notifications for changes made by this client only.
capability
None

FileIdL(TCalFileId &)

IMPORT_C voidFileIdL(TCalFileId &aCalFileId)const
Gets the file ID of the currently open Calendar file. This is unique to the file.
capability
None

Parameters

TCalFileId & aCalFileIdOn return will be the file ID of the currently open Calendar file. The file ID will be set to KNullFileId if the file is not opened.

GetFileNameL(TCalPubSubData, TDes &)

IMPORT_C voidGetFileNameL(TCalPubSubDataaPubSubData,
TDes &aFileName
)const
Retrieve a calendar file name from its hash value. The hash value comes from the Publish and Subscribe CalInterimAPI data in TCalPubSubData.
capability
None

Parameters

TCalPubSubData aPubSubDataThe publish and subscribe data.
TDes & aFileNameOn return will be the full file name.

Impl()

CCalSessionImpl &Impl()const

IsFileNameL(TCalPubSubData, const TDesC &)

IMPORT_C TBoolIsFileNameL(TCalPubSubDataaPubSubData,
const TDesC &aFileName
)const
Test if the full file name passed is the one that was changed.
capability
None

Parameters

TCalPubSubData aPubSubDataThe publish and subscribe data.
const TDesC & aFileNameThe full file name to test.

IsOpenedFileL(TCalPubSubData)

IMPORT_C TBoolIsOpenedFileL(TCalPubSubDataaPubSubData)const
Test if the publish and subscribe data relates to the currently open calendar file.
capability
None

Parameters

TCalPubSubData aPubSubDataThe publish and subscribe data.

ListCalFilesL()

IMPORT_C CDesCArray *ListCalFilesL()const
Gets a list of all calendar files held by the server. The caller takes ownership of the returned descriptor array.
capability
None
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.

NewL()

IMPORT_C CCalSession *NewL()[static]
Allocates and constructs a session to the Calendar server.
capability
None

NewL(CCalSession &)

IMPORT_C CCalSession *NewL(CCalSession &aCalSession)[static]

Allocates and constructs a session to the Calendar server

Pre-condition
At least one object of CalSession has been created (which means a connection to server has been established).
capability
None

Parameters

CCalSession & aCalSessionA reference to CalSession which is created beforehand.

OpenL(const TDesC &)

IMPORT_C voidOpenL(const TDesC &aFileName)const

Opens an calendar file using the server.

If another agenda file is open in the same server session, it is closed.
capability
ReadUserData
leave
KErrEof If the calendar file is corrupt and cannot be opened because an unexpected end of file was reached.
leave
KErrInUse If there is an undeleted view, entry or instance from the file opened with this calendar session. These must all be deleted before a new file can be opened.
leave
KErrNotFound If the file has not been created. Call CCalSession::CreateCalFileL to create the file.
leave
KErrCorrupt If the calendar file is corrupt and cannot be opened.
leave
KErrNotSupported If the file name is not specified in the format DriveLetter:FileName.
leave
KErrNotSupported If the file is not a supported version. The parameter aFileSupportStatus will be set to EUnsupportedFileVersion in this case.
leave
KErrNotReady If the calendar file is on a drive where the media has been removed.

Parameters

const TDesC & aFileNameThe 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.

OpenL(const TDesC &, CalCommon::TCalFileVersionSupport &)

IMPORT_C voidOpenL(const TDesC &aFileName,
CalCommon::TCalFileVersionSupport &aFileSupportStatus
)const

Opens a calendar file using the server.

If another calendar file is open in the same server session, it is closed.
leave
KErrEof If the calendar file is corrupt and cannot be opened because an unexpected end of file was reached.
leave
KErrInUse If there is an undeleted view, entry or instance from the file opened with this calendar session. These must all be deleted before a new file can be opened.
leave
KErrNotFound If the file has not been created. Call CCalSession::CreateCalFileL to create the file.
leave
KErrCorrupt If the calendar file is corrupt and cannot be opened.
leave
KErrNotSupported If the file name is not specified in the format DriveLetter:FileName.
leave
KErrNotSupported If the file is not a supported version. The parameter aFileSupportStatus will be set to EUnsupportedFileVersion in this case.
leave
KErrNotReady If the calendar file is on a drive where the media has been removed. Otherwise one of the system wide error codes.
Pre-condition
The file to be opened has been created.
Post-condition
The file has been opened and it is now possible to build an entry view or instance view. If the file requires conversion, the conversion will take place while building the view.
capability
ReadUserData

Parameters

const TDesC & aFileNameThe agenda file to open. This is a combination of drive letter and file name, in other words, DriveLetter:FileName, but not a full path. The default file is opened if aFileName is KNullDesC.
CalCommon::TCalFileVersionSupport & aFileSupportStatusOn return indicates whether or not the calendar file needs to be converted from an older version. File conversion takes place when opening the first instance view or entry view.

SetCalendarInfoL(const CCalCalendarInfo &)

IMPORT_C voidSetCalendarInfoL(const CCalCalendarInfo &aCalendarInfo)const
Set calendar info on the currently open calendar file.
leave
KErrNotReady If there is no calendar file open on this CCalSession.
capability
WriteUserData

Parameters

const CCalCalendarInfo & aCalendarInfoThe calendar info to set on the file.

StartChangeNotification(MCalChangeCallBack2 &, const CCalChangeNotificationFilter &)

IMPORT_C voidStartChangeNotification(MCalChangeCallBack2 &aCallBack,
const CCalChangeNotificationFilter &aFilter
)

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).

capability
None

Parameters

MCalChangeCallBack2 & aCallBackThe class to notify when a change occurs.
const CCalChangeNotificationFilter & aFilterFilter notifications to only notify on certain types of entries.

StartChangeNotification(MCalChangeCallBack *, MCalChangeCallBack::TChangeEntryType, TBool, TTime, TTime)

IMPORT_C voidStartChangeNotification(MCalChangeCallBack *aCallBack,
MCalChangeCallBack::TChangeEntryTypeaChangeEntryType,
TBoolaIncludeUndatedTodos,
TTimeaFilterStartTime,
TTimeaFilterEndTime
)

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).

capability
None

Parameters

MCalChangeCallBack * aCallBackThe class to notify when a change occurs.
MCalChangeCallBack::TChangeEntryType aChangeEntryTypeFilter notifications to only notify on entries of the specified type (event/todo/all).
TBool aIncludeUndatedTodosFilter notifications to include undated todos.
TTime aFilterStartTimeFilter 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 aFilterEndTimeFilter notification to only include entries that are wholly or partly covered by a time range. This specifies the end time of the time range.

StartFileChangeNotificationL(MCalFileChangeObserver &)

IMPORT_C voidStartFileChangeNotificationL(MCalFileChangeObserver &aCallBack)

Start notification of changes to calendar files. When a change occurs, the MCalFileChangeObserver callback function is called with change types (see MCalFileChangeObserver::TChangeType) about the files.

capability
None

Parameters

MCalFileChangeObserver & aCallBackThe class to notify when a change occurs.

StopChangeNotification()

IMPORT_C voidStopChangeNotification()
Stop entry notifications from this session.
capability
None

StopFileChangeNotification()

IMPORT_C voidStopFileChangeNotification()
Stop file change notification from this session.
capability
None

_DebugRequestAllocatedCellsL()

IMPORT_C TInt_DebugRequestAllocatedCellsL()
Gets the total number of cells allocated on the server-side heap. Debug only. Test
Pre-condition
There is an open calendar session.
Post-condition
None

_DebugRequestAllocatedHeapSizeL()

IMPORT_C TInt_DebugRequestAllocatedHeapSizeL()

_DebugSetHeapFailL(RAllocator::TAllocFail, TInt)

IMPORT_C void_DebugSetHeapFailL(RAllocator::TAllocFailaFail,
TIntaRate
)

Simulates a heap allocation failure for the server-side heap. Debug only.

The failure occurs on subsequent calls to new or any of the functions which allocate memory from the server-side heap.

The timing of the allocation failure depends on the type of allocation failure requested, i.e. on the value of aFail.

The simulation of heap allocation failure is cancelled if aFail is given the value RAllocator::ENone.

Notes:

1. If the failure type is RAllocator::EFailNext, the next attempt to allocate from the server-side heap fails; however, no further failures will occur.

2. For failure types RAllocator::EFailNext and RAllocator::ENone, set aRate to 1.

Test
Pre-condition
There is an open calendar session.
Post-condition
The calendar server will fail memory allocation at the specified point.

Parameters

RAllocator::TAllocFail aFailAn enumeration which indicates how to simulate heap allocation failure.
TInt aRateThe rate of failure; when aType is RAllocator::EDeterministic, heap allocation fails every aRate attempt.

__dbgClearTzClientCacheL(TBool)

IMPORT_C void__dbgClearTzClientCacheL(TBoolaRestartCaching)
Clears timezone information cached at client side. This API should be used for debug purpose.
capability
None

Parameters

TBool aRestartCachingSet to ETrue if caching needs to be restarted after clearing current cache.

Member Data Documentation

CCalSessionImpl * iImpl

CCalSessionImpl *iImpl[private]