Calendar Views

The CCalSession class provides the following views for accessing the calendar:

Entry view

You can access and manipulate calendar entries with CCalEntryView.
Instance view

With CCalInstanceView you can access and delete multiple calendar instances generated from an entry.

Entry view

You can use the entry view object to perform the following functions on a calendar entry:

Fetch by calling CCalEntryView::FetchL().
Update by calling CCalEntryView::UpdateL().
Save by calling CCalEntryView::StoreL().
Delete by calling CCalEntryView::DeleteL().

To access a calendar entry, you need to create an entry view with the CCalEntryView::NewL() function.

Instance view

A calendar event can have one or more occurrences. An event occurs more than once if a repeat rule has been set. Each occurrence is known as an instance (also called a schedule).

An instance view can be created with a CCalSession object array. CCalInstanceView::FindInstanceL() allows you to search all files within the array.

void FindInstanceL(RPointerArray< CCalInstance >
    &aMatchedInstanceList, CalCommon::TCalViewFilter aCalViewFilter, const
    CalCommon::TCalTimeRange &aTimeRange, const TCalSearchParams
    &aSearchParams) const;

CCalInstanceView::FindInstanceL() returns instances across multiple files in the form of an RPointerArray object. The other parameters specify the following filtering criteria:

entry type
time range within which the entries need to be found
search text along with the search options.

You can get the next and previous instances relative to a specified time using CCalInstanceView::NextInstanceL() and CCalInstanceView::PreviousInstanceL() respectively.

Call CCalInstanceView::DeleteL() to delete any instance returned by CCalInstanceView::FindInstanceL(). If all the instances are deleted, the entry gets deleted automatically. CCalInstanceView::DeleteL() must be used in conjunction with CCalInstanceView::FindInstanceL().

Multiple Calendar File Searching

The following functions find instances across calendar collections (multiple calendar files).

```
CCalInstanceIterator* FindInstanceByUidL(TCalCollectionId aCollectionId, const TDesC8& aUid, const TCalTime& aInstanceTime) const;
```
This function creates an instance iterator containing instances that relate to a UID (unique identifier). The iterator contains a collection ID, a global UID (GUID) and a time. The parameters are used to tell the iterator which instance to start iterating from. The aCollectionId parameter identifies the file from which the starting instance comes. The aInstanceTime parameter identifies the time of the starting instance.
```
CCalInstance* FindInstanceL(const TCalInstanceId& aLocalId)
```
In the function above TCalInstanceId is a datatype that contains TCalCollectionId, CCalLocalUid and CCalTime.

This function only returns a single instance.
```
CCalInstanceIterator* FindInstanceL(const CCalFindInstanceSettings& aSettings, const TCalInstanceId& aInstanceId);
```
This function contains a CCalFindInstanceSettings parameter that sets filtering criteria. As before TCalInstanceId identifies the starting instance.

The functions above are based on the following deprecated functions:

CCalInstanceIterator* FindInstanceByUidL(const TDesC8 &aUid, const TCalTime &aInstanceTime);

CCalInstance* FindInstanceL(TCalLocalUid aLocalId, const TCalTime& aInstanceTime);

CCalInstanceIterator* FindInstanceL(const CCalFindInstanceSettings& aSettings, TCalLocalUid aLocalId, const TCalTime& aInstanceTime);

Parent topic: Concepts