--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/Symbian3/SDK/Source/GUID-B26A4743-F331-5AC3-A40A-28B14B785857.dita	Wed Mar 31 11:11:55 2010 +0100
@@ -0,0 +1,127 @@
+<?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><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_d0e290601_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 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>
+</refbody></reference>
\ No newline at end of file