CCalSession Class Reference

#include <app/calsession.h>

Link against: calinterimapi.lib

class CCalSession : public CBase

Inherits from

CCalSession

Public Member Functions
	~CCalSession()
IMPORT_C CCalCalendarInfo *	CalendarInfoL()
IMPORT_C TCalCollectionId	CollectionIdL()
IMPORT_C void	CreateCalFileL(const TDesC &)
IMPORT_C void	CreateCalFileL(const TDesC &, const CCalCalendarInfo &)
IMPORT_C const TDesC &	DefaultFileNameL()
IMPORT_C void	DeleteCalFileL(const TDesC &)
IMPORT_C void	DisableChangeBroadcast()
IMPORT_C void	DisablePubSubNotificationsL()
IMPORT_C void	EnableChangeBroadcast()
IMPORT_C void	EnablePubSubNotificationsL()
IMPORT_C void	FileIdL(TCalFileId &)
IMPORT_C void	GetFileNameL(TCalPubSubData, TDes &)
CCalSessionImpl &	Impl()
IMPORT_C TBool	IsFileNameL(TCalPubSubData, const TDesC &)
IMPORT_C TBool	IsOpenedFileL(TCalPubSubData)
IMPORT_C CDesCArray *	ListCalFilesL()
IMPORT_C CCalSession *	NewL()
IMPORT_C CCalSession *	NewL(CCalSession &)
IMPORT_C void	OpenL(const TDesC &)
IMPORT_C void	OpenL(const TDesC &, CalCommon::TCalFileVersionSupport &)
IMPORT_C void	SetCalendarInfoL(const CCalCalendarInfo &)
IMPORT_C void	StartChangeNotification(MCalChangeCallBack2 &, const CCalChangeNotificationFilter &)
IMPORT_C void	StartChangeNotification(MCalChangeCallBack *, MCalChangeCallBack::TChangeEntryType, TBool, TTime, TTime)
IMPORT_C void	StartFileChangeNotificationL(MCalFileChangeObserver &)
IMPORT_C void	StopChangeNotification()
IMPORT_C void	StopFileChangeNotification()
IMPORT_C TInt	_DebugRequestAllocatedCellsL()
IMPORT_C TInt	_DebugRequestAllocatedHeapSizeL()
IMPORT_C void	_DebugSetHeapFailL(RAllocator::TAllocFail, TInt)
IMPORT_C void	__dbgClearTzClientCacheL(TBool)

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

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

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.

Constructor & Destructor Documentation

~CCalSession ( )

IMPORT_C

~CCalSession

(

)

Destructor for the session. Clear away any resources.

capability: None

Member Function 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

Returns: The calendar file's calendar info. If none has been set on the file, CCalCalendarInfo::IsValid will return EFalse.

CollectionIdL ( )

IMPORT_C TCalCollectionId

CollectionIdL

(

)

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

Returns: Return the Collection ID of the currently open Calendar file, 0 if the file has not been opened.

CreateCalFileL ( const TDesC & )

IMPORT_C void

CreateCalFileL

(

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.

Parameter	Description
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.

CreateCalFileL ( const TDesC &, const CCalCalendarInfo & )

IMPORT_C void	CreateCalFileL	(	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.

Parameter	Description
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.
aCalendarInfo	The 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

Returns: 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 ( const TDesC & )

IMPORT_C void

DeleteCalFileL

(

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.

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

DisableChangeBroadcast ( )

IMPORT_C void

DisableChangeBroadcast

(

)

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 void

DisablePubSubNotificationsL

(

)

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

capability: None

EnableChangeBroadcast ( )

IMPORT_C void

EnableChangeBroadcast

(

)

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

capability: None

EnablePubSubNotificationsL ( )

IMPORT_C void

EnablePubSubNotificationsL

(

)

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

capability: None

FileIdL ( TCalFileId & )

IMPORT_C void

FileIdL

(

TCalFileId &

aCalFileId

)

const

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

capability: None

Parameter	Description
aCalFileId	On 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 void	GetFileNameL	(	TCalPubSubData	aPubSubData,
			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

Parameter	Description
aPubSubData	The publish and subscribe data.
aFileName	On return will be the full file name.

Impl ( )

CCalSessionImpl &

Impl

(

)

const

IsFileNameL ( TCalPubSubData, const TDesC & )

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

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

capability: None

Parameter	Description
aPubSubData	The publish and subscribe data.
aFileName	The full file name to test.

Returns: ETrue if the full file name passed is the one that was changed, EFalse if not.

IsOpenedFileL ( TCalPubSubData )

IMPORT_C TBool

IsOpenedFileL

(

TCalPubSubData

aPubSubData

)

const

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

capability: None

Parameter	Description
aPubSubData	The publish and subscribe data.

Returns: ETrue if the publish and subscribe data relates to the currently open calendar file, EFalse if not.

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.

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

NewL ( )

IMPORT_C CCalSession *

NewL

(

)

[static]

Allocates and constructs a session to the Calendar server.

capability: None

Returns: Pointer to the newly created session.

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

Parameter	Description
aCalSession	A reference to CalSession which is created beforehand.

Returns: Pointer to the newly created session which shares the handle to the Calendar server with aCalSession.

OpenL ( const TDesC & )

IMPORT_C void

OpenL

(

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.

Parameter	Description
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.

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

IMPORT_C void	OpenL	(	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

Parameter	Description
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. The default file is opened if aFileName is KNullDesC.
aFileSupportStatus	On 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 void

SetCalendarInfoL

(

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

Parameter	Description
aCalendarInfo	The calendar info to set on the file.

StartChangeNotification ( MCalChangeCallBack2 &, const CCalChangeNotificationFilter & )

IMPORT_C void	StartChangeNotification	(	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

Parameter	Description
aCallBack	The class to notify when a change occurs.
aFilter	Filter notifications to only notify on certain types of entries.

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

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

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

Deprecated

capability: None

Parameter	Description
aCallBack	The class to notify when a change occurs.
aChangeEntryType	Filter notifications to only notify on entries of the specified type (event/todo/all).
aIncludeUndatedTodos	Filter notifications to include undated todos.
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.
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.

StartFileChangeNotificationL ( MCalFileChangeObserver & )

IMPORT_C void

StartFileChangeNotificationL

(

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

Parameter	Description
aCallBack	The class to notify when a change occurs.

StopChangeNotification ( )

IMPORT_C void

StopChangeNotification

(

)

Stop entry notifications from this session.

capability: None

StopFileChangeNotification ( )

IMPORT_C void

StopFileChangeNotification

(

)

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

Returns: The number of cells allocated on the heap.

_DebugRequestAllocatedHeapSizeL ( )

IMPORT_C TInt

_DebugRequestAllocatedHeapSizeL

(

)

_DebugSetHeapFailL ( RAllocator::TAllocFail, TInt )

IMPORT_C void	_DebugSetHeapFailL	(	RAllocator::TAllocFail	aFail,
			TInt	aRate
		)

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.

Parameter	Description
aFail	An enumeration which indicates how to simulate heap allocation failure.
aRate	The rate of failure; when aType is RAllocator::EDeterministic, heap allocation fails every aRate attempt.

__dbgClearTzClientCacheL ( TBool )

IMPORT_C void

__dbgClearTzClientCacheL

(

TBool

aRestartCaching

)

Clears timezone information cached at client side. This API should be used for debug purpose.

capability: None

Parameter	Description
aRestartCaching	Set to ETrue if caching needs to be restarted after clearing current cache.