<?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 OS v9.5. </shortdesc><prolog><metadata><keywords/></metadata></prolog><refbody>
<section><title>Purpose</title> <p>Prior to v9.5 the Message Store API had
limited support for selecting and sorting message records and fields. In v9.5,
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><title>Class summary</title><p>The example demonstrates the following
classes and enums:</p><p><xref href="GUID-5D956759-5D21-3715-916E-F7E703172762.dita"><apiname>CMsvSearchSortOperation</apiname></xref> <xref href="GUID-A1ECA70D-1D50-3B5F-9D22-74D0215146E7.dita"><apiname> CMsvSearchSortQuery</apiname></xref> <xref href="GUID-D9BB2EF0-262F-3BCF-8F48-F40FE0D4C107.dita"><apiname> TMsvMessagePart</apiname></xref> <xref href="GUID-A60B4636-F309-3FD6-8D12-D4EE3AC6BC58.dita"><apiname> TMsvSearchSortResultType</apiname></xref></p></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_d0e262349_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-6C81A72A-3BEC-3D18-9CAD-46E9309C3FEB"><apiname>CMsvSearchSortOperation::RequestL()</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><title>See also</title><p><xref href="GUID-32C1FC8B-F7D2-5275-BDF2-0D662551294C.dita">Search-Sort
Overview</xref></p></section>
</refbody></reference>