<?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-3BDF7402-8AD6-57C7-849A-145E08EC7E86"><title>Using Calendar Entry Time Iteration</title><shortdesc>This topic introduces Calender iterator classes and describes how device implementers can use instance iterators for searching and sorting. </shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody><section><title>Required background</title> <p>General knowledge of searching and sorting as well as <xref href="GUID-00631ED2-1B7F-5FC4-9E81-4B6DF7946631.dita">Calendar</xref>. </p> <p>The following terms are referred to within this topic </p> <dl><dlentry><dt>Iterator</dt> <dd><p>An object that allows a program to move through each element within a range of data. </p> </dd> </dlentry> <dlentry><dt>Instance iterator</dt> <dd><p>For the Calendar component an instance is an occurence of a Calendar entry. Therefore, an instance iterator points to each occurence of a Calendar entry. </p> </dd> </dlentry> <dlentry><dt>Sort criteria</dt> <dd><p>Rules that decide the order in which Calendar instances are arranged. </p> </dd> </dlentry> </dl> </section> <section><title>Introduction</title> <p>Instance iteration is a function of the <xref href="GUID-00631ED2-1B7F-5FC4-9E81-4B6DF7946631.dita">Calendar</xref> component within the PIM Application Services collection. This document describes the classes within Calendar that enable searching and sorting of Calendar instances. The iterators used for searching and sorting are created using three distinct factory methods of the <xref href="GUID-58BA8611-A364-3E30-B5F0-E5787E19C48C.dita"><apiname>CCalInstanceView</apiname></xref> class. Each iterator has a different behaviour which is described in the following sections </p> <ul><li id="GUID-769BCC5B-9FEB-5DC2-B085-43B803FB6A38"><p><xref href="GUID-3BDF7402-8AD6-57C7-849A-145E08EC7E86.dita#GUID-3BDF7402-8AD6-57C7-849A-145E08EC7E86/GUID-C5AD3E96-A40C-5DE2-B0F1-38BF349580DA">Iterating over instances in a time range view</xref>  </p> </li> <li id="GUID-A9549EAC-5440-5AA1-9A13-3DFB29BF775F"><p><xref href="GUID-3BDF7402-8AD6-57C7-849A-145E08EC7E86.dita#GUID-3BDF7402-8AD6-57C7-849A-145E08EC7E86/GUID-E8A1810A-00EB-59E6-BC0A-17F58C603D31">Iterating over all instances, from a starting instance</xref>  </p> </li> <li id="GUID-EFD4B921-8CD7-5E6C-AC8E-737D87B3CC22"><p><xref href="GUID-3BDF7402-8AD6-57C7-849A-145E08EC7E86.dita#GUID-3BDF7402-8AD6-57C7-849A-145E08EC7E86/GUID-640721A8-A26E-5C53-9E8F-7AA4DB66902E">Iterating over a repeating meeting schedule, from a starting instance</xref>  </p> </li> </ul> <p><b>CCalInstanceIterator</b> </p> <p>The instance iterator class <xref href="GUID-3028274E-F033-3218-BA44-2BC2B0BE58E7.dita"><apiname>CCalInstanceIterator</apiname></xref> provides standard functions for iterating through a set of Calendar instances </p> <codeblock id="GUID-9E516778-E6AE-5A76-A0B6-610E22D480F6" xml:space="preserve">CCalInstance* CCalInstanceIterator::NextL();

CCalInstance* CCalInstanceIterator::PreviousL();

TBool CCalInstanceIterator::HasMore() const;

TInt CCalInstanceIterator::Count() const;

</codeblock> <p> <xref href="GUID-3028274E-F033-3218-BA44-2BC2B0BE58E7.dita#GUID-3028274E-F033-3218-BA44-2BC2B0BE58E7/GUID-8A6F3455-ED23-3C84-B056-2092A8B7EE18"><apiname>CCalInstanceIterator::NextL()</apiname></xref> returns the next instance in the set. If there are no more instances to be returned then it returns a NULL pointer. </p> <p> <xref href="GUID-3028274E-F033-3218-BA44-2BC2B0BE58E7.dita#GUID-3028274E-F033-3218-BA44-2BC2B0BE58E7/GUID-82DA6CF2-E7E2-33B8-B4AE-9B42FF784BB4"><apiname>CCalInstanceIterator::PreviousL()</apiname></xref> returns the previous instance in the set. If there are no more instances to be returned then the API returns a NULL pointer. </p> <p> <xref href="GUID-3028274E-F033-3218-BA44-2BC2B0BE58E7.dita#GUID-3028274E-F033-3218-BA44-2BC2B0BE58E7/GUID-3B6962D3-3833-343D-ADA1-B07158845626"><apiname>CCalInstanceIterator::HasMore()</apiname></xref> returns <codeph>ETrue</codeph> when there are more instances to be returned by <codeph>NextL()</codeph>, and <codeph>EFalse</codeph> when there are not. </p> <p> <b> Note:</b> It is advised that <xref href="GUID-3028274E-F033-3218-BA44-2BC2B0BE58E7.dita#GUID-3028274E-F033-3218-BA44-2BC2B0BE58E7/GUID-3B6962D3-3833-343D-ADA1-B07158845626"><apiname>CCalInstanceIterator::HasMore()</apiname></xref> is not used. It has no advantage and is less efficient than checking whether the value returned by <codeph>NextL()</codeph> is a NULL pointer or not. </p> <p> <xref href="GUID-3028274E-F033-3218-BA44-2BC2B0BE58E7.dita#GUID-3028274E-F033-3218-BA44-2BC2B0BE58E7/GUID-64E1A2C8-866B-3011-8B65-D9E6C78A1EA4"><apiname> CCalInstanceIterator::Count()</apiname></xref> returns the number of instances that are in the set of instances defined by the parameters that were used to create the iterator. </p> <p> <b> Note:</b> It is advised that <codeph>CCalInstanceIterator::Count()</codeph> is not used because it takes a long time to work out the number of instances in the set. </p> <p>The iterator has been designed for efficient memory usage. The instances that are returned are owned by the calling application and should therefore be deleted by the calling application. So that the calling application benefits from this when iterating, it is recommended that <codeph>CCalInstance</codeph> objects are queried, as needed, and then deleted before the application moves on to the next instance. </p> <p>Please note that the instance iterator has undefined behaviour if changes are made to the Calendar data file after the iterator has been created. Therefore, if an entry is stored, updated, or deleted by your application or another application the iterator should be destroyed and recreated. </p> <p><b>CCalFindInstanceSettings</b> </p> <p>This instance settings class is used to set filtering options when creating two of the iterators. </p> <p>The following functions use the instance settings class </p> <codeblock id="GUID-14F667B6-3B81-5F62-90BF-EF2819D300B6" xml:space="preserve">

CCalFindInstanceSettings* CCalFindInstanceSettings::NewL(CalCommon::TCalViewFilter aFilter, const CalCommon::TCalTimeRange& aTimeRange);

void CCalFindInstanceSettings::SetTextSearchL(const CCalInstanceView::TCalSearchParams&amp; aSearchParams);           </codeblock> <p>The constructor of this class takes a time range and a view filter, which describe the types of instances that should be returned. </p> <p>An application can also optionally specify some search text using the <codeph>CCalFindInstanceSettings::SetSearchTextL()</codeph> function. </p> <p>Four APIs in the <codeph>CCalInstanceSettings</codeph> class support customised sorting and filtering by priority and 32-bit user integer </p> <codeblock id="GUID-E168CBBB-CF3D-54BB-B1C0-CAE0DAC27684" xml:space="preserve">// Define the filter for the 32 bit user integer

void SetUserIntFilter(const CalCommon::TCalUserIntFilter& aUserIntFilter);

</codeblock> <p>The parameter class <codeph>CalCommon::TCalUserIntFilter</codeph> has two members </p> <ul><li id="GUID-536050CC-8F04-5A0E-80CC-D658438E132C"><p>Mask – specifies which bits are valid in the filter. </p> </li> <li id="GUID-2A6445CA-3299-50DA-B0DE-577705B39BF2"><p>Value – specifies the matched value. </p> </li> </ul> <p>A <xref href="GUID-BB7C2921-86A6-30B3-8092-4338A88C36CE.dita"><apiname>CCalFindInstanceSettings</apiname></xref> object with an empty <codeph>CCalSortCriteria</codeph> object calls <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>. The instances return with the default sort order. </p> <p>Instances are ordered first by instance time. For instances with equal times the default sort order, applied by <codeph>CCalInstanceView::FindInstanceL()</codeph>, is as follows </p> <ul><li id="GUID-1FE5706F-5A81-5882-BB7C-68BC3F554069"><p>To-do entries. Two or more to-do entries are ordered by due date, priority then start date </p> </li> <li id="GUID-D299087F-0121-54EC-9FB7-8369EEFA5B66"><p>Anniversaries </p> </li> <li id="GUID-7F2AAFDB-E28E-5BF0-A9DA-381EAB1EF690"><p>Day notes </p> </li> <li id="GUID-56F3700D-3542-54A0-8CCA-E6470228A436"><p>Appointments. Two or more appointments are ordered by start time then end time. </p> </li> </ul> <p>If two instances are the same then completed to-do instances appear after non-completed ones. </p> <p><b>CCalSortCriteria</b> </p> <p>The <xref href="GUID-E702E469-D282-3C85-9F78-6E8472EACB9C.dita"><apiname>CCalSortCriteria</apiname></xref> class represents a sort criterion sequence. Items within the sequence are represented by the <xref href="GUID-9AE83544-CC85-3872-8CBA-4D6EBF765E7C.dita"><apiname>CCalSortCriterion</apiname></xref> class. Sequence items are applied to determine the order of the calendar instances. If the first criterion is to order instances by end time and the second criterion is to order instances by priority, the instances are sorted by end time and then by priority. </p> <p>You can fetch the <codeph>CCalSortCriteria</codeph> through <codeph>CCalFindInstanceSettings</codeph> using the following functions </p> <codeblock id="GUID-9F5C391F-3CCF-5C75-90BF-B9FA2B83DEEB" xml:space="preserve">

CCalSortCriteria& SortCriteria(); 

const CCalSortCriteria&amp; SortCriteria() const;</codeblock> <p>You can perform operations on <codeph>CCalSortCriteria</codeph> using the functions below. </p> <ul><li id="GUID-C127C9C3-9B98-541F-8D4A-D51657053839"><p>To append a sort criterion to the end of the array of sort criteria, represented by a <codeph>CCalSortCriteria</codeph> object </p> <codeblock id="GUID-48CF9A8C-72D5-5A5E-A7AC-5000886FADDD" xml:space="preserve">void AppendCriterionL(CalCommon::TCalSortAttribute aAttr, CalCommon::TCalSortDirection aDir);</codeblock> </li> <li id="GUID-4C2447A5-E07C-5586-85DF-482A1AC007FA"><p>To return the number of sort orders contained in the <codeph>CCalSortCriteria</codeph> object </p> <codeblock id="GUID-F93DDC7F-567C-5EDD-B602-57374B3ECE4B" xml:space="preserve">TInt Count() const;</codeblock> </li> <li id="GUID-EBDF7C1C-45E8-5F12-A0A8-9C8F455B59D7"><p>To return a sort criterion at the specified index </p> <codeblock id="GUID-9A648625-7CE9-5AC3-9264-12A319F85FAE" xml:space="preserve">const CCalSortCriterion&amp; AtL(TInt aIndex) const;</codeblock> </li> <li id="GUID-2AF9C67A-5306-52F0-81BB-4769B7423890"><p>To set the order to follow when sorting the instances according to their type </p> <codeblock id="GUID-93C9F817-6587-5DEB-93D5-0DC234D84B6A" xml:space="preserve">void SetEntryTypeOrderL(const RArray&lt;CCalEntry::TType&gt;&amp; aTypeOrder);</codeblock> </li> <li id="GUID-665C765F-7B04-5228-8693-62282661FDC0"><p>To return the type order retained by the sort criteria object </p> <codeblock id="GUID-BA85A3B7-8A53-50F6-8824-3020778CBF90" xml:space="preserve">const RArray&lt;CCalEntry::TType&gt;&amp;  EntryTypeOrder() const;</codeblock> </li> </ul> </section> <section id="GUID-C5AD3E96-A40C-5DE2-B0F1-38BF349580DA"><title>Iterating over instances in a time range view</title> <p>This iterator is given as an alternative to using the normal <xref href="GUID-61153F93-1A72-3122-9693-1242235987F7.dita"><apiname>FindInstanceL()</apiname></xref> call to populate a month view. The benefit of using the iterator is that large views can be created without running out of application memory because the application can create only one instance of the view at a time. The disadvantage is that the iterator is not as fast as the normal <codeph>FindInstanceL()</codeph> call. This is a decision that must be made by the application developer. If there are too many instances for the normal <codeph>FindInstanceL()</codeph> call to work without running out of memory then this iterator could be used to populate the view where it was not possible before. </p> <p>This iterator is created through the <codeph>FindInstanceL()</codeph> API </p> <codeblock id="GUID-EE013B7A-6C9E-5291-BF5B-68720006D185" xml:space="preserve">

CCalInstanceIterator* CCalInstanceView::FindInstanceL(const CCalFindInstanceSettings& aSettings) const;

</codeblock> <p>Iteration starts from the beginning of the time range and instances are returned in the same order as they are from a <codeph>FindInstanceL()</codeph> call. </p> </section> <section id="GUID-E8A1810A-00EB-59E6-BC0A-17F58C603D31"><title>Iterating over all instances, from a starting instance</title> <p>This iterator enables calendar applications to iterate through all instances in the calendar, but starting from a specified instance. </p> <p>The function below is used to create this version of the iterator </p> <codeblock id="GUID-8146E186-49FF-5738-A782-890AE27085DB" xml:space="preserve">

CCalInstanceIterator* CCalFindInstanceSettings::FindInstanceL(const

CCalFindInstanceSettings& aSettings, TCalLocalUid aLocalId, const

TCalTime& aInstanceTime) const; 

          </codeblock> <p>Note that <xref href="GUID-BB7C2921-86A6-30B3-8092-4338A88C36CE.dita"><apiname>CCalFindInstanceSettings</apiname></xref> is used here. <codeph>CCalFindInstanceSettings</codeph> requires the application to provide a time range. It is expected that an application will not want to choose a time range because it is not known how far away the next or previous instance is. When specifying the time range in this iterator it is acceptable to use min time to max time. </p> <p>The starting instance is selected by specifying the local UID of the entry that that instance belongs to, and the time of that instance. If either the time of the instance is incorrect or the local UID does not refer to an entry currently in the calendar store then construction leaves with <codeph>KErrNotFound</codeph>. </p> <p>Here is some example code that demonstrates how to use the iterator </p> <codeblock id="GUID-330AB91F-D449-5FBC-9F89-02CA9437A9BD" xml:space="preserve">

// Find an instance to start from

CCalInstance& startingInstance = GetInstanceFromMonthView();

// Set up the find instance settings

TCalTime startRange;

startRange.SetTimeLocalL(TCalTime::MinTime());

TCalTime endRange;

endRange.SetTimeLocalL(TCalTime::MaxTime());

CalCommon::TCalTimeRange timeRange(startRange, endRange);

CCalFindInstanceSettings* settings = CCalFindInstanceSettings::NewL(CalCommon::EIncludeAll, timeRange);

CleanupStack::PushL(settings);

// Create the iterator

CCalInstanceIterator* iterator = instanceView->FindInstanceL(*settings, startingInstance.Entry()->LocalUidL(),    startingInstance.Time());

CleanupStack::PopAndDestroy(settings);

CleanupStack::PushL(iterator);

// Find the next instance

CCalInstance* nextInstance = iterator->NextL();

delete nextInstance;

// Find the previous instance

CCalInstance* previousInstance = iterator->PreviousL();

delete previousInstance;

CleanupStack::PopAndDestroy(iterator);  </codeblock> </section> <section id="GUID-640721A8-A26E-5C53-9E8F-7AA4DB66902E"><title>Iterating over a repeating meeting schedule, from a starting

          instance </title> <p>This iterator enables applications to iterate through all the instances of a repeating meeting schedule. This means that any instances that are defined by the same guide are considered by the iterator. Instances of other meetings are ignored. For example, this would allow an application to iterate through the instances of a repeating to-do. The user may then mark individual instances as completed. </p> <p>The iterator can be created using the following function </p> <codeblock id="GUID-0781CCA8-6D4C-5B34-88DF-5FD18134A9A0" xml:space="preserve">

CCalInstanceIterator* CCalInstanceView::FindInstanceByUidL(const TDesC8&amp; aUid, const TCalTime&amp; aInstanceTime) const; </codeblock> <p>In a similar way to the previously described iterator, the starting instance is specified by providing the time of the starting instance. This time, however, the application provides the UID of the repeating meeting schedule and not the local UID of the entry. The provided UID is used when considering which instance should be returned. Only those instances of entries belonging to the specified UID are considered. Again if the instance time is incorrect or the UID does not refer to an entry that is currently in the calendar store then construction of the iterator leaves with <codeph>KErrNotFound</codeph>. </p> <p>Here is a code example that demonstrates this iterator </p> <codeblock id="GUID-8B73994B-208E-57F6-83E6-E3298BE8913E" xml:space="preserve">

// Find an instance to start from

CCalInstance& startingInstance = GetInstanceFromMonthView();

// Create the iterator

CCalInstanceIterator* iterator = instanceView->FindInstanceByUidL(startingInstance.Entry()->UidL(), startingInstance.Time());

CleanupStack::PushL(iterator);

// Find the next instance in the repeat meeting schedule

CCalInstance* nextInstance = iterator->NextL();

delete nextInstance;

// Find the previous instance in the repeat meeting schedule

CCalInstance* previousInstance = iterator->PreviousL();

delete previousInstance;