<?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-20DDA21D-B5DE-5D24-9E75-69C68EAF1782"><title>Expanded Search Capabilities</title><prolog><metadata><keywords/></metadata></prolog><conbody><section><title>Searches by text field</title> <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> can search all text fields. It is supported by <xref href="GUID-519A4EAF-499B-3AAE-A2E1-51A7B247CB0E.dita#GUID-519A4EAF-499B-3AAE-A2E1-51A7B247CB0E/GUID-AD325212-39DA-3703-8C1B-5E73FE5F2883"><apiname>CalCommon::TCalSearchBehaviour</apiname></xref>. </p> <p>The following fields are searchable: </p> <ul><li id="GUID-85E95DFC-C916-53C3-80FB-7E84ED757FD0"><p>Summary </p> </li> <li id="GUID-848B3B16-EAFF-5A0F-BD74-C2D3B6EF1C8F"><p>Description </p> </li> <li id="GUID-BA0B4130-F335-5F0A-B4C2-4C4FC4DB2E7C"><p>Location </p> </li> <li id="GUID-3EC81270-B95B-55F7-B64B-AB543F21D2EA"><p>Organizer Common Name </p> </li> <li id="GUID-EC81F09C-446F-5444-8005-54DF9948FA31"><p>Organizer Address </p> </li> <li id="GUID-4D64D415-8BD4-50C9-BFA3-AD0904FB7F5C"><p>Organizer Sent-By </p> </li> <li id="GUID-BC0A6A03-2A2D-5E4E-9554-C4823C17AAE5"><p>Attendee Common Name </p> </li> <li id="GUID-00A96037-E8BB-5850-81F9-8FD3320B44B1"><p>Attendee Address </p> </li> <li id="GUID-2C53D207-932B-5641-861C-32D15C23CC0A"><p>Attendee Sent-By </p> </li> </ul> <p>The search string only needs to match one of the fields specified in the filter for it to be considered a matching instance. </p> <p>It is important to note that an entry can have multiple attendees. This means that searching the attendee fields may become quite expensive for a large meeting. </p> <p>Once the flag is added to <xref href="GUID-519A4EAF-499B-3AAE-A2E1-51A7B247CB0E.dita#GUID-519A4EAF-499B-3AAE-A2E1-51A7B247CB0E/GUID-AD325212-39DA-3703-8C1B-5E73FE5F2883"><apiname>CalCommon::TCalSearchBehaviour</apiname></xref>, it is passed to the constructor of <xref href="GUID-58BA8611-A364-3E30-B5F0-E5787E19C48C.dita#GUID-58BA8611-A364-3E30-B5F0-E5787E19C48C/GUID-29AFDCA1-FCD9-3C3B-9749-1548AF9A04E3"><apiname>CCalInstanceView::TCalSearchParams</apiname></xref>. The latter is a search parameter used when instances are found by using the API <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> </section> <section><title>Searches using filters and time ranges</title> <p>The enum <xref href="GUID-519A4EAF-499B-3AAE-A2E1-51A7B247CB0E.dita#GUID-519A4EAF-499B-3AAE-A2E1-51A7B247CB0E/GUID-36EB8FC9-6EF7-3A80-A6B1-00B18C16937B"><apiname>CalCommon::TCalViewFilterFlags</apiname></xref> is used in entry view and instance view to specify entries that are of interest to the client. Class <xref href="GUID-519A4EAF-499B-3AAE-A2E1-51A7B247CB0E.dita#GUID-519A4EAF-499B-3AAE-A2E1-51A7B247CB0E/GUID-1FCA6E9A-1C8B-3599-B247-B6EC0AF6F695"><apiname>CalCommon::TCalTimeRange</apiname></xref> is used to define the time range within which instances fall. </p> </section> <section><title>Searches using an iterator</title> <p>An instance iterator is used to fetch instances and return them to the client one at a time. The iterator can be obtained via the API: </p> <codeblock id="GUID-A3271B59-EDC6-5B6B-B7E4-161F907C0B32" xml:space="preserve">CCalInstanceIterator* CCalInstanceView::FindInstanceL(const CCalFindInstanceSettings&amp; aSettings) const</codeblock> <p> </p> <p> <xref href="GUID-BB7C2921-86A6-30B3-8092-4338A88C36CE.dita"><apiname>CCalFindInstanceSettings</apiname></xref> is an extensible class containing all search parameters. <xref href="GUID-3028274E-F033-3218-BA44-2BC2B0BE58E7.dita"><apiname>CCalInstanceIterator</apiname></xref> is the iterator object which contains search results and the methods used to retrieve the instance. </p> <p>The initial search operation finds all instances and caches the results as instance IDs on the client. As the iterator is called to fetch entries, the instances are cached on the client and returned to the user, one at a time. </p> <p>This procedure is advantageous because less time and RAM are used to retrieve a large number of instances. </p> <p> <xref href="GUID-3028274E-F033-3218-BA44-2BC2B0BE58E7.dita"><apiname>CCalInstanceIterator</apiname></xref> has these exported functions: </p> <codeblock id="GUID-55F11326-35B1-57B3-8FD2-0A65B5206C05" xml:space="preserve">EXPORT_C ~CCalInstanceIterator() 
// The destructor for the instance iterator </codeblock> <codeblock id="GUID-77814002-571A-5FC5-ACD3-F308924FE4FE" xml:space="preserve">EXPORT_C CCalInstance* NextL() 
// Fetches the next instance in the iterator. It returns ownership of instance and the iterator moves to the next instance in its results list.</codeblock> <codeblock id="GUID-999383AA-6F01-5A2A-BEF6-96BA7347805E" xml:space="preserve">EXPORT_C CCalInstance* PreviousL() 
// Fetches the previous instance in the iterator. It returns ownership of the instance and the iterator moves to the previous instance in its results list.</codeblock> <codeblock id="GUID-E68D6B31-2920-5A70-B171-5E8CA3563E09" xml:space="preserve">EXPORT_C TBool HasMore() const 
// Checks to see if there are any more results in the iterator to be returned by calling NextL.</codeblock> <codeblock id="GUID-6E9DCFAC-4903-562C-B744-CA41A09EC8FD" xml:space="preserve">EXPORT_C TInt Count() const 
// Returns the total number of instances found by the iterator.</codeblock> </section> </conbody></concept>