<?xml version="1.0" encoding="utf-8"?>

<!-- Copyright (c) 2007-2010 Nokia Corporation and/or its subsidiary(-ies) All rights reserved. -->

<!-- This component and the accompanying materials are made available under the terms of the License 

"Eclipse Public License v1.0" which accompanies this distribution, 

and is available at the URL "http://www.eclipse.org/legal/epl-v10.html". -->

<!-- Initial Contributors:

    Nokia Corporation - initial contribution.

Contributors: 

-->

<!DOCTYPE concept

  PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd">

<concept xml:lang="en" id="GUID-CD8A3420-6C9B-5774-86FA-85CFE062C400"><title>Calendar Views</title><prolog><metadata><keywords/></metadata></prolog><conbody><p>The <xref href="GUID-609318A7-43F1-3FC1-952B-146B1EA8115D.dita"><apiname>CCalSession</apiname></xref> class provides the following views for accessing the calendar: </p> <ul><li id="GUID-5A7CA871-9C20-52DC-9C2F-E931BF6F7F72"><p>Entry view </p> <p>You can access and manipulate calendar entries with <xref href="GUID-D2835D4E-F0A8-3EDE-BC13-B45E52170556.dita"><apiname>CCalEntryView</apiname></xref>. </p> </li> <li id="GUID-DDF2375F-D209-569D-AA58-FC03C2A5182F"><p>Instance view </p> <p>With <xref href="GUID-58BA8611-A364-3E30-B5F0-E5787E19C48C.dita"><apiname>CCalInstanceView</apiname></xref> you can access and delete multiple calendar instances generated from an entry. </p> </li> </ul> <section><title>Entry view </title> <p>You can use the entry view object to perform the following functions on a calendar entry: </p> <ul><li id="GUID-4679329D-7D83-59FD-9BDD-2445EF9D3637"><p>Fetch by calling <xref href="GUID-D2835D4E-F0A8-3EDE-BC13-B45E52170556.dita#GUID-D2835D4E-F0A8-3EDE-BC13-B45E52170556/GUID-43FA0568-E254-3C7C-BC4C-1C73AFB6421A"><apiname>CCalEntryView::FetchL()</apiname></xref>. </p> </li> <li id="GUID-F27E0D76-CA84-5CED-8230-82761200F2FB"><p>Update by calling <xref href="GUID-D2835D4E-F0A8-3EDE-BC13-B45E52170556.dita#GUID-D2835D4E-F0A8-3EDE-BC13-B45E52170556/GUID-536FA411-5D58-3CE5-8F10-22FA8089FBBF"><apiname>CCalEntryView::UpdateL()</apiname></xref>. </p> </li> <li id="GUID-319DCEBE-B91E-525C-BA5C-3581C865B432"><p>Save by calling <xref href="GUID-D2835D4E-F0A8-3EDE-BC13-B45E52170556.dita#GUID-D2835D4E-F0A8-3EDE-BC13-B45E52170556/GUID-41282158-9CC7-3563-A542-834BE2B10D78"><apiname>CCalEntryView::StoreL()</apiname></xref>. </p> </li> <li id="GUID-5C6E0994-70D8-5267-9507-CFC7BCCD150E"><p>Delete by calling <xref href="GUID-D2835D4E-F0A8-3EDE-BC13-B45E52170556.dita#GUID-D2835D4E-F0A8-3EDE-BC13-B45E52170556/GUID-4B78A543-8F12-3E68-8C09-D178FBB8F83E"><apiname>CCalEntryView::DeleteL()</apiname></xref>. </p> </li> </ul> <p>To access a calendar entry, you need to create an entry view with the <xref href="GUID-D2835D4E-F0A8-3EDE-BC13-B45E52170556.dita#GUID-D2835D4E-F0A8-3EDE-BC13-B45E52170556/GUID-795FE89C-9074-3DFB-9C67-99E002DE386C"><apiname>CCalEntryView::NewL()</apiname></xref> function. </p> </section> <section><title>Instance view</title> <p>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). </p> <p>An instance view can be created with a <xref href="GUID-609318A7-43F1-3FC1-952B-146B1EA8115D.dita"><apiname>CCalSession</apiname></xref> object array. <xref href="GUID-58BA8611-A364-3E30-B5F0-E5787E19C48C.dita#GUID-58BA8611-A364-3E30-B5F0-E5787E19C48C/GUID-961D3CE4-3C92-3A15-BDD1-19FF3D970F83"><apiname>CCalInstanceView::FindInstanceL()</apiname></xref> allows you to search all files within the array. </p> <codeblock id="GUID-EAB3795E-8A73-5F50-83A9-732FF4F34CEA" xml:space="preserve">void FindInstanceL(RPointerArray&lt; CCalInstance &gt;

    &aMatchedInstanceList, CalCommon::TCalViewFilter aCalViewFilter, const

    CalCommon::TCalTimeRange &aTimeRange, const TCalSearchParams

    &amp;aSearchParams) const;</codeblock> <p> <xref href="GUID-58BA8611-A364-3E30-B5F0-E5787E19C48C.dita#GUID-58BA8611-A364-3E30-B5F0-E5787E19C48C/GUID-961D3CE4-3C92-3A15-BDD1-19FF3D970F83"><apiname>CCalInstanceView::FindInstanceL()</apiname></xref> returns instances across multiple files in the form of an <xref href="GUID-AAA13D1F-1BD7-3331-BB8C-11FA2795B53F.dita"><apiname>RPointerArray</apiname></xref> object. The other parameters specify the following filtering criteria: </p> <ul><li id="GUID-4565DEFA-7536-56FC-9FF5-29A6D59B5E6C"><p>entry type </p> </li> <li id="GUID-55CAF240-089B-5976-836E-0E93B38501ED"><p>time range within which the entries need to be found </p> </li> <li id="GUID-A60A6082-A5A8-5176-9EE7-AEE04042289F"><p>search text along with the search options. </p> </li> </ul> <p>You can get the next and previous instances relative to a specified time using <xref href="GUID-58BA8611-A364-3E30-B5F0-E5787E19C48C.dita#GUID-58BA8611-A364-3E30-B5F0-E5787E19C48C/GUID-1B622C9A-BAD5-3BF2-9D50-DB490C4A30A4"><apiname>CCalInstanceView::NextInstanceL()</apiname></xref> and <xref href="GUID-58BA8611-A364-3E30-B5F0-E5787E19C48C.dita#GUID-58BA8611-A364-3E30-B5F0-E5787E19C48C/GUID-6397E6CA-122F-3CC7-93F1-75CFA1FBF921"><apiname>CCalInstanceView::PreviousInstanceL()</apiname></xref> respectively. </p> <p>Call <xref href="GUID-58BA8611-A364-3E30-B5F0-E5787E19C48C.dita#GUID-58BA8611-A364-3E30-B5F0-E5787E19C48C/GUID-0960F4DF-AC2F-3E79-AACD-DC16DC364FB8"><apiname>CCalInstanceView::DeleteL()</apiname></xref> to delete any instance returned by <xref href="GUID-58BA8611-A364-3E30-B5F0-E5787E19C48C.dita#GUID-58BA8611-A364-3E30-B5F0-E5787E19C48C/GUID-961D3CE4-3C92-3A15-BDD1-19FF3D970F83"><apiname>CCalInstanceView::FindInstanceL()</apiname></xref>. If all the instances are deleted, the entry gets deleted automatically. <xref href="GUID-58BA8611-A364-3E30-B5F0-E5787E19C48C.dita#GUID-58BA8611-A364-3E30-B5F0-E5787E19C48C/GUID-0960F4DF-AC2F-3E79-AACD-DC16DC364FB8"><apiname>CCalInstanceView::DeleteL()</apiname></xref> must be used in conjunction with <xref href="GUID-58BA8611-A364-3E30-B5F0-E5787E19C48C.dita#GUID-58BA8611-A364-3E30-B5F0-E5787E19C48C/GUID-961D3CE4-3C92-3A15-BDD1-19FF3D970F83"><apiname>CCalInstanceView::FindInstanceL()</apiname></xref>. </p> <p><b>Multiple Calendar File Searching</b> </p> <p>The following functions find instances across calendar collections (multiple calendar files). </p> <ul><li id="GUID-35F941B6-B325-5C56-A39B-EFED498B6AFB"><codeblock id="GUID-C4802DF0-FB53-5AD0-904F-8BCCD463AA5F" xml:space="preserve">CCalInstanceIterator* FindInstanceByUidL(TCalCollectionId aCollectionId, const TDesC8&amp; aUid, const TCalTime&amp; aInstanceTime) const;</codeblock> <p>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 <xref href="GUID-EC4A403F-238F-32D6-AC78-8039B14CB8FA.dita"><apiname>aCollectionId</apiname></xref> parameter identifies the file from which the starting instance comes. The <xref href="GUID-B11D895B-A2CF-3838-A6FC-9D054E9BBE1E.dita"><apiname>aInstanceTime</apiname></xref> parameter identifies the time of the starting instance. </p> </li> <li id="GUID-634BB40B-A31C-5190-BB5A-FE022467478D"><codeblock id="GUID-B96944F9-D812-5956-B002-2EE6FF917F60" xml:space="preserve">CCalInstance* FindInstanceL(const TCalInstanceId&amp; aLocalId)</codeblock> <p>In the function above <xref href="GUID-A9EAAEB8-411D-33DD-9BA4-0D9356A999BC.dita"><apiname>TCalInstanceId</apiname></xref> is a datatype that contains <xref href="GUID-C935AA17-6546-3975-91D0-C7325F6E6D10.dita"><apiname>TCalCollectionId</apiname></xref>, <xref href="GUID-1343D7E5-3020-3888-A092-E89295424375.dita"><apiname>CCalLocalUid</apiname></xref> and <xref href="GUID-5CC27067-1E4C-395D-8604-0343211406C5.dita"><apiname>CCalTime</apiname></xref>. </p> <p>This function only returns a single instance. </p> </li> <li id="GUID-16E1142E-2F3D-5A22-9377-151E47C20E10"><codeblock id="GUID-1C533CDE-D418-5282-A462-33E504BC51F3" xml:space="preserve">CCalInstanceIterator* FindInstanceL(const CCalFindInstanceSettings&amp; aSettings, const TCalInstanceId&amp; aInstanceId);</codeblock> <p>This function contains a <xref href="GUID-BB7C2921-86A6-30B3-8092-4338A88C36CE.dita"><apiname>CCalFindInstanceSettings</apiname></xref> parameter that sets filtering criteria. As before <xref href="GUID-A9EAAEB8-411D-33DD-9BA4-0D9356A999BC.dita"><apiname>TCalInstanceId</apiname></xref> identifies the starting instance. </p> </li> </ul> <p>The functions above are based on the following deprecated functions: </p> <codeblock id="GUID-45462FD8-3053-5C02-9B1A-A1E04E52CB24" xml:space="preserve">CCalInstanceIterator* FindInstanceByUidL(const TDesC8 &amp;aUid, const TCalTime &amp;aInstanceTime);</codeblock> <codeblock id="GUID-575E7CFA-E14E-536B-935E-1FD5F579B86C" xml:space="preserve">CCalInstance* FindInstanceL(TCalLocalUid aLocalId, const TCalTime&amp; aInstanceTime);</codeblock> <codeblock id="GUID-1F6AC23B-6DB7-59E8-9A21-7304B6083836" xml:space="preserve">CCalInstanceIterator* FindInstanceL(const CCalFindInstanceSettings&amp; aSettings, TCalLocalUid aLocalId, const TCalTime&amp; aInstanceTime);