Working with Multiple Calendar Instances

Required background

Before you start, you must be familiar with the Calendar component.

Introduction

For a Calendar session, CCalSession, to access a file (or collection) it must connect to the server. More than one file may be opened and multiple Calendar sessions (or instances) can be created. A second Calendar session can share the first session's connection to the server. This is possible because the handle to the file is separate from the session to the server.

A calendar application uses CCalInstanceView::FindInstanceL() to find and change Calendar instances across multiple files and other data collections. When a Calendar collection changes a subscriber application is notified by the file observer. Each file has its own observer.

A calendar entry can be stored, updated and deleted. Changes to calendar instances are committed to a calendar.

Procedure

A calendar entry can be located within any one of a number of different calendar collections. An application can access entry instances across multiple calendar collections. To do this an instance view must be created using the calendar collections to be searched. These collections must share the same session.

To find instances across multiple Calendars follow the steps below.

1. Call CCalSession::NewL() to create a session and establish a connection to the server.

2. Call the first session CCalSession::NewL(*session1) to create a second session with the same connection.

3. Place the sessions in an array using the declaration RPointerArray<CCalSession>.

4. Register the sessions with instance view CCalInstanceView.

5. Use CCalInstanceView to find instances of a calendar entry.

   Each instance has a collection ID which uniquely identifies its source. The unique ID enables the application to fetch the metadata associated with the source. (Example metadata includes creation time, type and filename.)

6. To clean up the objects created earlier delete the instances by calling RPointerArray::ResetAndDestroy().

{
...
// Create a session
CCalSession* session1 = CCalSession::NewL();
session1->OpenL(KCalendarFilename1);

// Get the collection ID
TCalCollectionId collectionId1 = session1->CollectionId();

// Create a second session
CCalSession* session2 = CCalSession::NewL(*session1);
session2->OpenL(KCalendarFilename2);
TCalCollectionId collectionId2 = session2->CollectionId();

RPointerArray<CCalSession> calSessions;
calSessions.AppendL(session1);
calSessions.AppendL(session2);

// Find all instances within a given time range
CCalInstanceView* instanceView = CCalInstanceView::NewL(calSessions);
RPointerArray<CCalInstance> instances;
TCalTime start;
start.SetTimeUtcL(TCalTime::MinTime());
TCalTime end;
end.SetTimeUtcL(TCalTime::MaxTime());
CalCommon::TCalTimeRange timeRange(start, end);
instanceView->FindInstanceL(instances, CalCommon::EIncludeAll, timeRange);

// An application finds which session an instance belongs to
TCalCollectionId id = instanceArray[index]->InstanceIdL().iCollectionId;

switch (id)
    {
    case collectionId1:
        // Fetch meta data about session1
        break;
    case collectionId2:
        // Fetch meta data about session2
        break;
    }

...

// Clean up objects
delete instances;

// Delete without closing session1 or session2
delete instanceView;
calSessions.ResetAndDestroy();

// Close session1 but do not disconnect from the server
delete session1;

// Close session2 and disconnect from the server
delete session2;
}