<?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 reference

  PUBLIC "-//OASIS//DTD DITA Reference//EN" "reference.dtd">

<reference id="GUID-B26A4743-F331-5AC3-A40A-28B14B785857" xml:lang="en"><title>SearchSortExample: enhanced search and sort for Message Store</title><shortdesc>This example demonstrates the enhanced search and sort

API for message stores. This API was implemented in Symbian^3. </shortdesc><prolog><metadata><keywords/></metadata></prolog><refbody>

<section id="GUID-B702DCF4-5C83-4AE2-95F5-F09D7DC46255"><title>Purpose</title> <p>Prior to Symbian^3, the Message Store API had limited support

for selecting and sorting message records and fields. From Symbian^3,

the API implements more extensive search and sort options.</p> <p>This example demonstrates the new functionality by implementing the

following use cases: </p> <ul>

<li id="GUID-E9B88EDB-8DD1-5CC2-B6DD-CA8498FE1865"><p>Display the

header information for all message entries. </p> </li>

<li id="GUID-5D07456E-DEDE-578D-961F-138E9DBD9470"><p>Perform a simple

(single search criteria) non-iterative search-sort and display the

matching entries. This has the following options: </p> <ul>

<li id="GUID-73CAF478-2B69-5883-B7A1-4F8B20D884E8"><p>case sensitivity

on / off, </p> </li>

<li id="GUID-D158CBA7-4947-589F-9C1E-FFB0E36A8CEF"><p>whole word search

on / off. </p> </li>

</ul> </li>

<li id="GUID-F2FC91DD-8198-53BB-9C77-5DC30C071AE1"><p>Perform a combined

(more than one search criteria) non-iterative search-sort and display

the number of matching entries. This has the following options: </p> <ul>

<li id="GUID-25CDF7E6-9D22-58C8-8832-03B0723A7F6E"><p>case sensitivity

on / off, </p> </li>

<li id="GUID-35902CB3-B4AF-56D0-937A-A840B3F40CDA"><p>whole word search

on / off. </p> </li>

</ul> </li>

<li id="GUID-54A5DEF1-21F3-5B24-85BA-71450C7E3D2D"><p>Perform an iterative

search-sort (searches for entries one at a time) and display the number

of matching entries. </p> </li>

<li id="GUID-5412D0A2-2A38-5F34-AE9E-AE7940345DDC"><p>Perform a search-sort

using a query ID. The query ID is generated by a previous search-sort

operation. </p> </li>

</ul> <p>Before implementing these use cases, the example creates

a POP3/SMTP message store with five message entries. </p> </section>

<section id="GUID-4FBA245A-78AC-4584-8471-240D504C3ED0"><title>Class

summary</title><p>The example demonstrates the following classes and

enums:</p><ul>

<li><p><xref href="GUID-5D956759-5D21-3715-916E-F7E703172762.dita"><apiname>CMsvSearchSortOperation</apiname></xref></p></li>

<li><p><xref href="GUID-A1ECA70D-1D50-3B5F-9D22-74D0215146E7.dita"><apiname> CMsvSearchSortQuery</apiname></xref></p></li>

<li><p><xref href="GUID-D9BB2EF0-262F-3BCF-8F48-F40FE0D4C107.dita"><apiname> TMsvMessagePart</apiname></xref></p></li>

<li><p><xref href="GUID-A60B4636-F309-3FD6-8D12-D4EE3AC6BC58.dita"><apiname> TMsvSearchSortResultType</apiname></xref></p></li>

</ul></section>

<section id="GUID-9331568B-0BA3-5138-BDCC-65AC225A5328"><title>Download</title> <p>Click on the following link to download the example: <xref href="guid-6013a680-57f9-415b-8851-c4fa63356636/zips/guid-dbb3813f-c947-4359-805e-eeada16f1dbb.zip" scope="external">searchsortexample.zip</xref></p><p>Click: <xref href="guid-6013a680-57f9-415b-8851-c4fa63356636/guid-dbb3813f-c947-4359-805e-eeada16f1dbb.html" scope="peer">browse</xref> to view the example code. </p> </section>

<section id="GUID-F8B3E0E7-FB82-5266-AB40-C1149A782E83"><title>Design and implementation</title> <p><b>Project Implementation</b> </p> <p>The project implements the following classes: </p> <p> <b>CKeyReader:</b> Derived from <codeph>CActive</codeph>. This reads

keypresses and calls the appropriate example function. </p> <p> <b>CMessAsyncWaiter:</b> Derived from <codeph>CActive</codeph>. This

handles the <codeph>CMsvSearchSortOperation::RequestL()</codeph> asynchronous

request. This <codeph>RequestL()</codeph> function takes <codeph>CMessAsyncWaiter::iStatus</codeph> as one of its parameters and then waits on the status. When the

search is complete the client is notified of the event's completion

by <codeph>CMessAsyncWaiter::RunL()</codeph> being called, after which

the example prepares the buffer and displays the results. </p> <p> <b>CSearchsortExample:</b> Derived from <codeph>CBase</codeph> and <codeph>MMsvSessionObserver</codeph>. <codeph>MMsvSessionObserver</codeph> is an interface for notification of events from a Message Server

session. </p> <p> <codeph>CSearchsortExample</codeph> implements <codeph>HandleSessionEventL()</codeph> to handle the two event types <codeph>EMsvEntriesCreated</codeph> and <codeph>EMsvServerReady</codeph>.

It also creates the SMTP message entries and carries out searching

and sorting. </p> <p><b>Simple non-iterative search-sort</b> </p> <p>The example starts by creating a message server session using <codeph>CMsvSession</codeph>, which represents a channel of communication

between a client thread (client-side MTM, user interface MTM, or message

client application) and the Message Server thread. Then it creates

an instance of <codeph>CMsvSearchSortOperation</codeph> to perform

the search-sort operation, and passes the session object into it. </p> <p>A search-sort query is created using <xref href="GUID-A1ECA70D-1D50-3B5F-9D22-74D0215146E7.dita#GUID-A1ECA70D-1D50-3B5F-9D22-74D0215146E7/GUID-B39D5F47-158A-38C8-8552-B3B5581554F7"><apiname>CMsvSearchSortQuery::NewL()</apiname></xref> and is configured using various member functions of class <xref href="GUID-A1ECA70D-1D50-3B5F-9D22-74D0215146E7.dita"><apiname>CMsvSearchSortQuery</apiname></xref> for instance whether to search for

whole or partial words and the case sensitivity. </p> <p>The search

and sort options are added to the query using <codeph>CMsvSearchSortQuery::AddSearchOptionL()</codeph> and <codeph>CMsvSearchSortQuery::AddSortOptionL()</codeph>. </p> <p>The search-sort operation is started by calling <xref href="GUID-5D956759-5D21-3715-916E-F7E703172762.dita#GUID-5D956759-5D21-3715-916E-F7E703172762/GUID-6C81A72A-3BEC-3D18-9CAD-46E9309C3FEB"><apiname>CMsvSearchSortOperation::RequestL()</apiname></xref>, passing the query as a parameter. If no iterator parameter is specified,

the search defaults to non-iterative. </p> <p>An instance of the <codeph>CMessAsyncWaiter</codeph> class is created for handling the asynchronous

search request. This object is waited on until the Message Server

completes the request. The results of the search are stored in an

array using <xref href="GUID-5D956759-5D21-3715-916E-F7E703172762.dita#GUID-5D956759-5D21-3715-916E-F7E703172762/GUID-1D6974D1-FF31-3B7C-A726-47A8510E9819"><apiname>CMsvSearchSortOperation::GetResultsL()</apiname></xref>. </p> <p>The result count is displayed by calling <xref href="GUID-5D956759-5D21-3715-916E-F7E703172762.dita#GUID-5D956759-5D21-3715-916E-F7E703172762/GUID-5E95F638-1252-3C63-A408-8FBAB445918D"><apiname>CMsvSearchSortOperation::GetResultCountL()</apiname></xref>. </p> <p>The query ID of the search is retrieved from the Message

server, for later use, using the <xref href="GUID-5D956759-5D21-3715-916E-F7E703172762.dita#GUID-5D956759-5D21-3715-916E-F7E703172762/GUID-989B6F32-DE88-373B-9CA4-5474BB6858CD"><apiname>CMsvSearchSortOperation::GetQueryId()</apiname></xref> function. </p> <p><b>Simple iterative search-sort</b> </p> <p>Iterative

search-sort follows the same steps as described above, except that

an iterator parameter is passed to the <codeph>RequestL()</codeph> function. To retrieve the results, <xref href="GUID-5D956759-5D21-3715-916E-F7E703172762.dita#GUID-5D956759-5D21-3715-916E-F7E703172762/GUID-3F38D82E-D350-3C80-8146-A339F1E189D8"><apiname>CMsvSearchSortOperation::GetNextResultL()</apiname></xref> is called in a <codeph>while</codeph> loop to retrieve one entry

at a time. Iterative searching is useful when the client may not have

enough memory to store an array of results. </p> <p><b>Combined search-sort</b> </p> <p>A combined search-sort is done by adding additional search

options using <codeph>CMsvSearchSortQuery::AddSearchOptionL()</codeph>. </p> <p><b>Search-sort using a query ID</b> </p> <p>A query ID

identifies a search-sort query. It is obtained by calling <xref href="GUID-5D956759-5D21-3715-916E-F7E703172762.dita#GUID-5D956759-5D21-3715-916E-F7E703172762/GUID-1893C3C7-4F77-3630-B115-A161CCA2665A"><apiname>CMsvSearchSortOperation::GetQueryIdL()</apiname></xref> following the completion

of <xref href="GUID-5D956759-5D21-3715-916E-F7E703172762.dita#GUID-5D956759-5D21-3715-916E-F7E703172762/GUID-6C81A72A-3BEC-3D18-9CAD-46E9309C3FEB"><apiname>CMsvSearchSortOperation::RequestL()</apiname></xref>. In this

example, the query ID generated by the simple non-iterative search-sort

is used to repeat the same search-sort. The overloaded <codeph>CMsvSearchSortOperation::RequestL()</codeph> function is used to initiate a search-sort operation with a query

ID. </p> <p>After the request completes, a list of index entry ID

objects (<xref href="GUID-A4B1F874-27C0-3BB6-9D29-C35C75A5DB98.dita"><apiname>TMsvId</apiname></xref> or <xref href="GUID-5A23B804-2C06-3407-9D48-1BFB212D699F.dita"><apiname>TMsvEntry</apiname></xref> depending on how the query was configured, using <xref href="GUID-A1ECA70D-1D50-3B5F-9D22-74D0215146E7.dita#GUID-A1ECA70D-1D50-3B5F-9D22-74D0215146E7/GUID-B040D6BA-670D-3CBF-B1F7-9AFD1F99267B"><apiname>CMsvSearchSortQuery::SetResultType()</apiname></xref>) is retrieved using <codeph>CMsvSearchSortOperation::GetResultsL()</codeph>. Finally the matching results are displayed in the console. </p> </section>

<section id="GUID-AE5E0880-9CAB-57E5-83CB-196D487935DE"><title>Building

and configuring</title> <p>To build the example: </p> <ul>

<li id="GUID-61C94258-567F-575E-A75C-29D2165FC2CA"><p>You can build

the example from your IDE or the command line. </p> <p>If you use

an IDE, import the <filepath>bld.inf</filepath> file of the example

into your IDE, and use the build command of the IDE. </p> <p>If you

use the command line, open a command prompt, and set the current directory

to the source code directory of the example. You can then build the

example with the SBSv1 build tools with the following commands: </p> <p><userinput>bldmake bldfiles</userinput> </p> <p><userinput>abld

build</userinput> </p> <p> <xref href="GUID-793A5EF9-CC16-5EEB-9011-6431EA76EB15.dita">How to use bldmake</xref> and <xref href="GUID-B6B54E07-3B34-5D5C-8815-93383FA8FB4B.dita">How to

use abld</xref> describe how to use the SBSv1 build tools. </p> </li>

<li id="GUID-F470E492-C920-58E0-860C-5CCE24B0C7F4"><p>For the emulator,

the example builds an executable called <filepath>searchsortexample.exe</filepath> in the <filepath>epoc32\release\winscw\&lt;udeb                

or urel&gt;\</filepath> folder. </p> </li>

</ul> </section>

<section id="GUID-B72B706B-BB9F-5A0D-A36A-03135FE99E5C"><title>Running

the example</title> <p> <filepath>searchsortexample.exe</filepath> takes user input from the console. The menu for the current example

is as shown below: </p> <fig id="GUID-53020118-A1E3-56C3-AA81-9CED04533E27">

<image href="GUID-656E2E4F-D7C5-5FDC-B1E6-DFA5970BB3F0_d0e286968_href.jpg" placement="inline"/>

</fig> <p>The user input is handled by <codeph>CKeyReader::RunL()</codeph>. </p> <p>For simple and combined non-iterative search-sort, the

user provides the following inputs: 1) the text in the "To" field

to search for, 2) whether case sensitivity is on of off, 3) whether

whole word searching is on or off. </p> <p>The input values are saved

in variables which are passed to the function <codeph>CSearchsortExample::SearchSortRequestWithoutIteratorL()</codeph>, and the settings are made accordingly. </p> <p>For the combined

search-sort the 2nd and 3rd search options (size and subject) are

hard coded. The iterative search-sort searches by size, which is also

hard coded. </p> <p>To execute a search-sort using a query ID, <xref href="GUID-5D956759-5D21-3715-916E-F7E703172762.dita#GUID-5D956759-5D21-3715-916E-F7E703172762/GUID-2856FD49-D254-3B1D-9F92-634B8BF7B325"><apiname>CMsvSearchSortOperation::RequestL(CMsvSearchSortQuery *,TBool,TRequestStatus

&amp;,TInt)</apiname></xref> must first have been called because it generates

the query ID. So, either option 2 or 3 must have been called before

option 5. </p> </section>

<section id="GUID-23202235-0D1E-4D86-83E1-9EC7A315E682"><title>See

also</title><p><xref href="GUID-32C1FC8B-F7D2-5275-BDF2-0D662551294C.dita">Search-Sort Overview</xref></p></section>