--- a/Symbian3/SDK/Source/GUID-32C1FC8B-F7D2-5275-BDF2-0D662551294C.dita Wed Mar 31 11:11:55 2010 +0100
+++ b/Symbian3/SDK/Source/GUID-32C1FC8B-F7D2-5275-BDF2-0D662551294C.dita Fri Jun 11 12:39:03 2010 +0100
@@ -1,239 +1,239 @@
-<?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 id="GUID-32C1FC8B-F7D2-5275-BDF2-0D662551294C" xml:lang="en"><title>Search-Sort
-Introduction</title><prolog><metadata><keywords/></metadata></prolog><conbody>
-<p>In Symbian OS v9.3 and earlier, when a search or sort query is made by
-a client, Message Server searches in the permanent file store (a proprietary
-formatted file), and returns the result to the client. </p>
-<p>From Symbian^3 onwards Message Server operates with the SQL
-database to store index entries. With the SQL database implementation the
-Message Server makes a query on the SQL index entry table, and returns the
-result to the client. </p>
-<p>The Messaging Middleware module provides an enhanced API for searching
-and sorting messages. This API can be used only when the SQL database is used
-to store the index entries. The API has the following features: </p>
-<ul>
-<li id="GUID-ACA12109-0146-5E75-A966-7BC6BA760A02"><p>Combined search (combination
-of more than one simple search criteria) </p> </li>
-<li id="GUID-945EFB6D-82CC-5E96-9487-37A6F0687C5A"><p>Search based on whole
-and partial words </p> </li>
-<li id="GUID-AA68CB16-94F8-56D4-98A7-2FB7A0372D24"><p>Case sensitive search </p> </li>
-<li id="GUID-FBDF167C-9DFF-5AF6-9352-17750D4649E3"><p>Wildcard search </p> </li>
-<li id="GUID-82B8AF61-5EE5-5DA1-96C8-EF94267D034D"><p>Count of total search
-results </p> </li>
-<li id="GUID-42BFEC5C-0703-51C5-952B-ACA571BDAFBD"><p>Single level sorting
-of search results </p> </li>
-<li id="GUID-ABDF3B62-0EDC-5256-858C-C958D84D00D1"><p>Iterative mechanism
-for clients to access the search and sort results sequentially. </p> </li>
-</ul>
-<p>The following sections include basic information on the search-sort functionality,
-which is important to understand before using the search-sort APIs: </p>
-<ul>
-<li id="GUID-CF2F2278-378A-5CA8-8E0A-5B7300CDCAA6"><p><xref href="GUID-32C1FC8B-F7D2-5275-BDF2-0D662551294C.dita#GUID-32C1FC8B-F7D2-5275-BDF2-0D662551294C/GUID-F682B9C3-8D9C-586B-94E5-67A24EB90180">Description</xref> </p> </li>
-<li id="GUID-28C84BAA-BD23-5A95-9D9F-402754208292"><p><xref href="GUID-32C1FC8B-F7D2-5275-BDF2-0D662551294C.dita#GUID-32C1FC8B-F7D2-5275-BDF2-0D662551294C/GUID-98960254-25D6-5F63-9788-255205B6D2BB">Search-sort API summary</xref> </p> </li>
-<li id="GUID-B928EB9A-8999-5E5F-9C61-C0DFF9EDA401"><p><xref href="GUID-32C1FC8B-F7D2-5275-BDF2-0D662551294C.dita#GUID-32C1FC8B-F7D2-5275-BDF2-0D662551294C/GUID-995B61DB-FB68-591E-8810-1DA96C882435">Advantages</xref> </p> </li>
-<li id="GUID-89A87B95-6A21-5CBD-B682-439E233AB29E"><p><xref href="GUID-32C1FC8B-F7D2-5275-BDF2-0D662551294C.dita#GUID-32C1FC8B-F7D2-5275-BDF2-0D662551294C/GUID-014C08BD-7FFC-5D2B-A107-316A70D52D12">Limitations</xref> </p> </li>
-</ul>
-<section id="GUID-F682B9C3-8D9C-586B-94E5-67A24EB90180"><title>Description</title> <p>The
-search-sort functionality is based on the client-server architecture. The
-Messaging Middleware module provides an advanced search-sort capability if
-the index entries are stored in an SQL database. </p> <p>The client creates
-a search-sort query, and passes it to the Message Server. The Message Server
-searches in the search-sort cache to check whether the query is a repetitive
-query (a query that was already requested in the past and for which a query
-ID is maintained in the search-sort cache) or a new query. </p> <p>If it is
-a repetitive query, the Message Server gets the index entry from the SQL database,
-and provides the search result to the client. </p> <p>If it is a new query,
-the Message Server stores the search query in the cache, and passes the query
-to the SQL database. </p> <p>In both the cases, the Message Server gets the
-index entry from the SQL database, passes the result to the client, and maintains
-the query in the search-sort cache. </p> <p>The iterative method can be used
-for searching and sorting a new or a repetitive search query. </p> <p>The
-following table provides detailed information on the fields supported in the
-search-sort operation: </p> <table id="GUID-0A7F291E-2B4E-5632-9D54-7C83CA8D1CE0">
-<tgroup cols="4"><colspec colname="col0"/><colspec colname="col1"/><colspec colname="col2"/><colspec colname="col3"/>
-<thead>
-<row>
-<entry>Operation</entry>
-<entry>Header</entry>
-<entry>Body</entry>
-<entry>TMsvEntry</entry>
-</row>
-</thead>
-<tbody>
-<row>
-<entry><p> <b> Searching</b> </p> </entry>
-<entry><p>To, cc, bcc, from, subject </p> </entry>
-<entry><p>Body part, whole and partial word (case sensitive and insensitive,
-whole word, wildcard) </p> </entry>
-<entry><p>Attachment type, read, unread, new flag, priority, size, MTM type,
-iDescription, iDetails, and date and time. </p> </entry>
-</row>
-<row>
-<entry><p> <b> Searching with explicit sorting</b> </p> </entry>
-<entry><p>To, cc, bcc, from, subject </p> </entry>
-<entry><p>-</p> </entry>
-<entry><p>Attachment type, read, unread, new flag, priority, size, MTM type,
-iDescription, iDetails, and date and time. </p> </entry>
-</row>
-<row>
-<entry><p> <b>Sorting</b> </p> </entry>
-<entry><p>To, cc, bcc, from, subject </p> </entry>
-<entry/>
-<entry><p>Attachment type, read, unread, new flag, priority, size, MTM type,
-iDescription, iDetails, and date and time. </p> </entry>
-</row>
-</tbody>
-</tgroup>
-</table> <p><b>Key terms</b> </p> <dl>
-<dlentry>
-<dt>Iterator</dt>
-<dd><p>An iterator is a method that allows a client to access the search and
-sort results sequentially. An iterator is useful when a client does not want
-to provide the memory to receive an array of results. </p> </dd>
-</dlentry>
-<dlentry>
-<dt>Search-sort cache</dt>
-<dd><p>Search-sort cache contains frequently requested search-sort queries.
-By default, this cache is set to 20 percent of the index entry cache. </p> <p>For
-more information the search-sort cache, see <xref href="GUID-45CA1787-F41F-5AA0-9508-B9D683602D41.dita">Search-Sort
-Cache</xref>. </p> </dd>
-</dlentry>
-</dl> </section>
-<section id="GUID-98960254-25D6-5F63-9788-255205B6D2BB"><title>Search-sort
-API summary</title> <p>Use the following APIs available in <filepath>msgs.dll</filepath> for
-searching and sorting messages: </p> <fig id="GUID-B16C2CC4-4269-5F23-88C3-33E87F198D88">
-<title> High level class diagram of new search-sort API
- </title>
-<image href="GUID-0E91173A-BA80-5817-866A-7A284573EBCE_d0e285207_href.png" placement="inline"/>
-</fig> <ul>
-<li id="GUID-9A2D5945-9D5F-5235-BA4F-500CFE5B2CF0"><p> <xref href="GUID-5D956759-5D21-3715-916E-F7E703172762.dita"><apiname>CMsvSearchSortOperation</apiname></xref> </p> <p>The <xref href="GUID-5D956759-5D21-3715-916E-F7E703172762.dita"><apiname>CMsvSearchSortOperation</apiname></xref> class is used in the client application for enhanced search-sort operations
-on the message store. </p> <p>This class can be used for the following: </p> <ul>
-<li id="GUID-7FAD5025-F94D-5824-BFD7-BDFCB83C4F2D"><p>To run a simple or complex
-search-sort request. </p> </li>
-<li id="GUID-94DFA54C-B9B6-5154-BF09-46A45DFCCD1E"><p>To repeat an earlier
-search-sort operation by using the <xref href="GUID-47DEF0FA-908B-31E4-A493-64FE7468F1D1.dita"><apiname>queryId</apiname></xref>. </p> </li>
-<li id="GUID-FBB74619-7822-5EC8-BD69-E7D2F2943896"><p>To receive results either
-in one chunk using an array or one after the other using an iterative method. </p> <note> The
-search-sort results can be received as a list of <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> objects.</note></li>
-</ul> </li>
-<li id="GUID-B757296A-97BD-5816-99BD-7897900CA1F4"><p> <xref href="GUID-A1ECA70D-1D50-3B5F-9D22-74D0215146E7.dita"><apiname>CMsvSearchSortQuery</apiname></xref> </p> <p>The <xref href="GUID-A1ECA70D-1D50-3B5F-9D22-74D0215146E7.dita"><apiname>CMsvSearchSortQuery</apiname></xref> class
-is used in the client application to create a search-sort query. It has an
-interface to add or set the query criteria on various message parts. </p> <p>This
-class provides the following search options: </p> <ul>
-<li id="GUID-F6ABCDEC-C50F-53BA-8817-CA88444765E7"><p>Case sensitive search
-(<xref href="GUID-4F6E4BC7-B77B-390D-BF08-58DF5EF2A959.dita"><apiname>SetCaseSensitiveOption</apiname></xref>) </p> <p>By default this option
-is set to false. </p> </li>
-<li id="GUID-C33F20AC-8F74-5CF6-9446-02227F274E59"><p>Whole word search (<xref href="GUID-D95D1E2A-8D0C-3509-8C51-C36DA28E304D.dita"><apiname>SetWholeWord</apiname></xref>) </p> <p>By
-default this option is set to false. </p> </li>
-<li id="GUID-F9BDA832-A1B8-5596-B619-2A54936D48FB"><p>Wildcard search (<xref href="GUID-BB9B7771-194B-3629-937C-0C829A339463.dita"><apiname>SetWildCardSearch</apiname></xref>) </p> <p>Allow
-the use of the asterisk (*) and question mark (?) wildcards. By default this
-option is set to false. </p> </li>
-<li id="GUID-ACAC32F4-9E34-5A47-A5CB-F9B5D2AE1235"><p>Subfolder search (<xref href="GUID-B06EB103-6ECA-39F0-A3F0-B99D7314CF3C.dita"><apiname>SetSubFolderSearch</apiname></xref>) </p> <p>Include
-the entries within the subfolders in the search result. By default this option
-is set to false. </p> <note> The subfolder option is valid only for a search
-query. </note> </li>
-<li id="GUID-AD053845-DB7D-5447-AD38-A348E51B6DE6"><p>Explicit single level
-sort (using the <codeph>TMsvMessagePart aMessagePart</codeph> parameter
-in the <xref href="GUID-A1ECA70D-1D50-3B5F-9D22-74D0215146E7.dita#GUID-A1ECA70D-1D50-3B5F-9D22-74D0215146E7/GUID-D4A0638E-61AE-3F7D-AB84-D3285F2D4539"><apiname>CMsvSearchSortQuery::AddSearchOptionL</apiname></xref> function. </p> <p>Sorting
-on one particular message part. </p> </li>
-</ul> <p>The <xref href="GUID-A1ECA70D-1D50-3B5F-9D22-74D0215146E7.dita"><apiname>CMsvSearchSortQuery</apiname></xref> class is used with the <xref href="GUID-5D956759-5D21-3715-916E-F7E703172762.dita"><apiname>CMsvSearchSortOperation</apiname></xref> class
-when requesting a new search-sort operation. </p> <note type="important"> By
-default, the search query results are not sorted. To receive a result in a
-sorted order, you must send a sort request by using the <xref href="GUID-A1ECA70D-1D50-3B5F-9D22-74D0215146E7.dita#GUID-A1ECA70D-1D50-3B5F-9D22-74D0215146E7/GUID-CE8F4E20-B1A9-32BF-B1FB-6F4E6CB88C2A"><apiname>CMsvSearchSortQuery::AddSortOptionL()</apiname></xref> function.
-Sort options can be used with search options when creating a search-sort query. </note></li>
-<li id="GUID-6DAE4181-212F-5988-AD0E-C1BF20503952"><p> <xref href="GUID-D9BB2EF0-262F-3BCF-8F48-F40FE0D4C107.dita"><apiname>TMsvMessagePart</apiname></xref> </p> <p>The <xref href="GUID-D9BB2EF0-262F-3BCF-8F48-F40FE0D4C107.dita"><apiname>TMsvMessagePart</apiname></xref> is
-an enumeration type class that contains all parts of the message, including
-index entry and message header. Searching or sorting is done based on the <xref href="GUID-D9BB2EF0-262F-3BCF-8F48-F40FE0D4C107.dita"><apiname>TMsvMessagePart</apiname></xref> class. </p> </li>
-<li id="GUID-EFEB6199-FD8A-55F4-9524-02E5C4A65488"><p> <xref href="GUID-A60B4636-F309-3FD6-8D12-D4EE3AC6BC58.dita"><apiname>TMsvSearchSortResultType</apiname></xref> </p> <p>The <xref href="GUID-A60B4636-F309-3FD6-8D12-D4EE3AC6BC58.dita"><apiname>TMsvSearchSortResultType</apiname></xref> is an enumeration class. The client uses <xref href="GUID-A60B4636-F309-3FD6-8D12-D4EE3AC6BC58.dita"><apiname>TMsvSearchSortResultType</apiname></xref> to
-specify if the search and sort results are returned as <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>. </p> </li>
-<li id="GUID-B07DA71A-4906-5EAB-8A4F-A103EB6F259F"><p> <xref href="GUID-9EC5FF8F-55BF-3D4B-BF1E-6221509E2583.dita"><apiname>TMsvRelationOp</apiname></xref> </p> <p>The <xref href="GUID-9EC5FF8F-55BF-3D4B-BF1E-6221509E2583.dita"><apiname>TMsvRelationOp</apiname></xref> is
-an enumeration type class that is used to provide relational operations between
-the search criteria value and the value in the message part of a message. </p> <p>For
-example, equal to, greater than, greater than or equal to, less than, and
-less than or equal to. </p> </li>
-<li id="GUID-0DA7A049-9FCA-5F7C-9C69-E357BBD5525D"><p> <xref href="GUID-94A91DF4-2362-3042-A230-79B4B294B2F6.dita"><apiname>TMsvSortOrder</apiname></xref> </p> <p>The <xref href="GUID-94A91DF4-2362-3042-A230-79B4B294B2F6.dita"><apiname>TMsvSortOrder</apiname></xref> is
-an enumeration type class that is used to provide the sorting options for
-sorting queries. The search or sort results can be sorted in ascending or
-descending order. </p> </li>
-</ul> </section>
-<section id="GUID-995B61DB-FB68-591E-8810-1DA96C882435"><title>Advantages</title> <p>The
-following are the advantages of the enhanced search-sort functionality: </p> <ul>
-<li id="GUID-D6B66EA5-4E18-5065-8502-7FD78C0147C8"><p>Search messages by the
-following fields: </p><note> Most of the following fields are applicable to
-email messages: </note> <ul>
-<li id="GUID-77DB4B4B-DD60-5164-974A-BD892702FD2B"><p>Sender, recipient list
-(cc, to, bcc), subject </p> </li>
-<li id="GUID-C16729FC-8517-59BF-AEE7-CEF4B6929AC9"><p>Mail size and size range </p> </li>
-<li id="GUID-FDA2E776-CE39-55E6-900E-8EBE826EBABC"><p>Date and date range </p> </li>
-<li id="GUID-24535174-207A-5095-ACCB-38F0A2B4704B"><p>Message type (SMS, Email,
-MMS, and BIO message) </p> </li>
-<li id="GUID-C190645B-B338-5C37-B506-BF783144923D"><p>Priority (high, medium,
-and low) </p> </li>
-<li id="GUID-D8804E92-44D5-5730-A09F-BE5EE62FB505"><p>Attachment types (linked
-attachment and file attachment) </p> </li>
-<li id="GUID-68D9C896-B8B1-5FA4-B833-8A7E9E2A09D0"><p>Message status </p> <p>For
-example, New, Read, Unread, and so on. </p> </li>
-</ul> </li>
-<li id="GUID-D381A082-643C-502A-99A9-1813C2FE5B8D"><p>Search messages containing
-a specified string in a specified message part. </p> </li>
-<li id="GUID-CB9D7CD8-41BF-55EA-B867-5C39192FC984"><p>Search within subfolders
-of the parent folder. </p> </li>
-<li id="GUID-194B52B2-B443-51A2-A7CB-4595CEE0101E"><p>Provides combined search
-and sort options to the client. </p> </li>
-<li id="GUID-21C4E9F2-CF3C-552D-8A4E-E2714060DF87"><p>Provides explicit single
-level of sorting with implicit sort by data and time. </p> </li>
-<li id="GUID-2137FD0D-97F5-58DA-BDC0-2E39EFFA750F"><p>Allows client to implement
-more versatile UI views. </p> </li>
-<li id="GUID-CECCA668-AEBD-5A26-AF0A-D591A7128F65"><p>Returns total number
-of search-sort count without sending the resultant data. For example, the
-number of unread messages in the inbox. </p> </li>
-<li id="GUID-308007D7-B0AC-5E6E-8EB9-2CD56214BED1"><p>Provides good RAM performance
-for repetitive search-sort requests, as the Messaging framework maintains
-a search-sort cache for frequently used search-sort requests. </p> </li>
-</ul> </section>
-<section id="GUID-014C08BD-7FFC-5D2B-A107-316A70D52D12"><title>Limitations</title> <p>The
-following are the limitations of the advanced search and sort functionality: </p> <ul>
-<li id="GUID-1361069B-D79B-5F37-B6D2-5730B73152B4"><p>The search-sort operation
-for a specific value in a specific message part is supported, but searching
-for a specific value in all message parts is not supported. </p> </li>
-<li id="GUID-F0E732EC-D4D5-53AE-A2F2-F09ADF134426"><p>Index entry is migrated
-to SQL. The header and body part are yet to be migrated to SQL. So the iterative
-method is supported only if the message parts in the index entry are used
-in creating the search-sort query. </p> </li>
-<li id="GUID-56127926-2AD8-50CE-81F3-E2CC5AE89EB7"><p>The following are not
-supported in the iterative method because the limitations of SQL: </p> <ul>
-<li id="GUID-F61AF937-A39E-5276-AE13-AEA2F48BF0C3"><p>Accessing the next set
-of values, that is, next <b>n</b> values (results). </p> </li>
-<li id="GUID-17F483B6-427F-59CD-8C47-88D5542E765B"><p>Accessing the previous
-value or the previous set of values. </p> </li>
-<li id="GUID-0323A0FD-DED7-5B44-B53E-565727B59E81"><p>Accessing a random value
-or a random set of values. </p> </li>
-</ul> </li>
-<li id="GUID-C567013B-A385-50B4-BC30-325BB2B073DB"><p>Multi level sorting
-is not supported. </p> </li>
-<li id="GUID-B0BB3E72-1C5F-5F44-AA79-170B4BC2CFD2"><p>A search query can use
-a maximum of five message parts as search criteria in a combined search. </p> </li>
-<li id="GUID-AFC8222E-ACF6-5F11-9D2C-773E9149473E"><p>Sorting on message body
-is not supported. </p> </li>
-<li id="GUID-62916475-9920-5196-9DB3-4F9C517F759B"><p>Search-sort operation
-cannot be performed on all the message parts present in index entry. The supported
-list consists of message parts present in message header, message body and
-a partial list of message parts from index entry. See the <xref href="GUID-D9BB2EF0-262F-3BCF-8F48-F40FE0D4C107.dita"><apiname>TMsvMessagePart</apiname></xref> enumeration
-class for the supported message parts. </p> </li>
-</ul> </section>
-</conbody><related-links>
-<link href="GUID-45CA1787-F41F-5AA0-9508-B9D683602D41.dita"><linktext>Search-Sort
-Cache</linktext></link>
-<link href="GUID-B26A4743-F331-5AC3-A40A-28B14B785857.dita"><linktext>Example code</linktext>
-</link>
+<?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 id="GUID-32C1FC8B-F7D2-5275-BDF2-0D662551294C" xml:lang="en"><title>Search-Sort
+Introduction</title><prolog><metadata><keywords/></metadata></prolog><conbody>
+<p>In Symbian OS v9.3 and earlier, when a search or sort query is made by
+a client, Message Server searches in the permanent file store (a proprietary
+formatted file), and returns the result to the client. </p>
+<p>From Symbian^3 onwards Message Server operates with the SQL
+database to store index entries. With the SQL database implementation the
+Message Server makes a query on the SQL index entry table, and returns the
+result to the client. </p>
+<p>The Messaging Middleware module provides an enhanced API for searching
+and sorting messages. This API can be used only when the SQL database is used
+to store the index entries. The API has the following features: </p>
+<ul>
+<li id="GUID-ACA12109-0146-5E75-A966-7BC6BA760A02"><p>Combined search (combination
+of more than one simple search criteria) </p> </li>
+<li id="GUID-945EFB6D-82CC-5E96-9487-37A6F0687C5A"><p>Search based on whole
+and partial words </p> </li>
+<li id="GUID-AA68CB16-94F8-56D4-98A7-2FB7A0372D24"><p>Case sensitive search </p> </li>
+<li id="GUID-FBDF167C-9DFF-5AF6-9352-17750D4649E3"><p>Wildcard search </p> </li>
+<li id="GUID-82B8AF61-5EE5-5DA1-96C8-EF94267D034D"><p>Count of total search
+results </p> </li>
+<li id="GUID-42BFEC5C-0703-51C5-952B-ACA571BDAFBD"><p>Single level sorting
+of search results </p> </li>
+<li id="GUID-ABDF3B62-0EDC-5256-858C-C958D84D00D1"><p>Iterative mechanism
+for clients to access the search and sort results sequentially. </p> </li>
+</ul>
+<p>The following sections include basic information on the search-sort functionality,
+which is important to understand before using the search-sort APIs: </p>
+<ul>
+<li id="GUID-CF2F2278-378A-5CA8-8E0A-5B7300CDCAA6"><p><xref href="GUID-32C1FC8B-F7D2-5275-BDF2-0D662551294C.dita#GUID-32C1FC8B-F7D2-5275-BDF2-0D662551294C/GUID-F682B9C3-8D9C-586B-94E5-67A24EB90180">Description</xref> </p> </li>
+<li id="GUID-28C84BAA-BD23-5A95-9D9F-402754208292"><p><xref href="GUID-32C1FC8B-F7D2-5275-BDF2-0D662551294C.dita#GUID-32C1FC8B-F7D2-5275-BDF2-0D662551294C/GUID-98960254-25D6-5F63-9788-255205B6D2BB">Search-sort API summary</xref> </p> </li>
+<li id="GUID-B928EB9A-8999-5E5F-9C61-C0DFF9EDA401"><p><xref href="GUID-32C1FC8B-F7D2-5275-BDF2-0D662551294C.dita#GUID-32C1FC8B-F7D2-5275-BDF2-0D662551294C/GUID-995B61DB-FB68-591E-8810-1DA96C882435">Advantages</xref> </p> </li>
+<li id="GUID-89A87B95-6A21-5CBD-B682-439E233AB29E"><p><xref href="GUID-32C1FC8B-F7D2-5275-BDF2-0D662551294C.dita#GUID-32C1FC8B-F7D2-5275-BDF2-0D662551294C/GUID-014C08BD-7FFC-5D2B-A107-316A70D52D12">Limitations</xref> </p> </li>
+</ul>
+<section id="GUID-F682B9C3-8D9C-586B-94E5-67A24EB90180"><title>Description</title> <p>The
+search-sort functionality is based on the client-server architecture. The
+Messaging Middleware module provides an advanced search-sort capability if
+the index entries are stored in an SQL database. </p> <p>The client creates
+a search-sort query, and passes it to the Message Server. The Message Server
+searches in the search-sort cache to check whether the query is a repetitive
+query (a query that was already requested in the past and for which a query
+ID is maintained in the search-sort cache) or a new query. </p> <p>If it is
+a repetitive query, the Message Server gets the index entry from the SQL database,
+and provides the search result to the client. </p> <p>If it is a new query,
+the Message Server stores the search query in the cache, and passes the query
+to the SQL database. </p> <p>In both the cases, the Message Server gets the
+index entry from the SQL database, passes the result to the client, and maintains
+the query in the search-sort cache. </p> <p>The iterative method can be used
+for searching and sorting a new or a repetitive search query. </p> <p>The
+following table provides detailed information on the fields supported in the
+search-sort operation: </p> <table id="GUID-0A7F291E-2B4E-5632-9D54-7C83CA8D1CE0">
+<tgroup cols="4"><colspec colname="col0"/><colspec colname="col1"/><colspec colname="col2"/><colspec colname="col3"/>
+<thead>
+<row>
+<entry>Operation</entry>
+<entry>Header</entry>
+<entry>Body</entry>
+<entry>TMsvEntry</entry>
+</row>
+</thead>
+<tbody>
+<row>
+<entry><p> <b> Searching</b> </p> </entry>
+<entry><p>To, cc, bcc, from, subject </p> </entry>
+<entry><p>Body part, whole and partial word (case sensitive and insensitive,
+whole word, wildcard) </p> </entry>
+<entry><p>Attachment type, read, unread, new flag, priority, size, MTM type,
+iDescription, iDetails, and date and time. </p> </entry>
+</row>
+<row>
+<entry><p> <b> Searching with explicit sorting</b> </p> </entry>
+<entry><p>To, cc, bcc, from, subject </p> </entry>
+<entry><p>-</p> </entry>
+<entry><p>Attachment type, read, unread, new flag, priority, size, MTM type,
+iDescription, iDetails, and date and time. </p> </entry>
+</row>
+<row>
+<entry><p> <b>Sorting</b> </p> </entry>
+<entry><p>To, cc, bcc, from, subject </p> </entry>
+<entry/>
+<entry><p>Attachment type, read, unread, new flag, priority, size, MTM type,
+iDescription, iDetails, and date and time. </p> </entry>
+</row>
+</tbody>
+</tgroup>
+</table> <p><b>Key terms</b> </p> <dl>
+<dlentry>
+<dt>Iterator</dt>
+<dd><p>An iterator is a method that allows a client to access the search and
+sort results sequentially. An iterator is useful when a client does not want
+to provide the memory to receive an array of results. </p> </dd>
+</dlentry>
+<dlentry>
+<dt>Search-sort cache</dt>
+<dd><p>Search-sort cache contains frequently requested search-sort queries.
+By default, this cache is set to 20 percent of the index entry cache. </p> <p>For
+more information the search-sort cache, see <xref href="GUID-45CA1787-F41F-5AA0-9508-B9D683602D41.dita">Search-Sort
+Cache</xref>. </p> </dd>
+</dlentry>
+</dl> </section>
+<section id="GUID-98960254-25D6-5F63-9788-255205B6D2BB"><title>Search-sort
+API summary</title> <p>Use the following APIs available in <filepath>msgs.dll</filepath> for
+searching and sorting messages: </p> <fig id="GUID-B16C2CC4-4269-5F23-88C3-33E87F198D88">
+<title> High level class diagram of new search-sort API
+ </title>
+<image href="GUID-0E91173A-BA80-5817-866A-7A284573EBCE_d0e281521_href.png" placement="inline"/>
+</fig> <ul>
+<li id="GUID-9A2D5945-9D5F-5235-BA4F-500CFE5B2CF0"><p> <xref href="GUID-5D956759-5D21-3715-916E-F7E703172762.dita"><apiname>CMsvSearchSortOperation</apiname></xref> </p> <p>The <xref href="GUID-5D956759-5D21-3715-916E-F7E703172762.dita"><apiname>CMsvSearchSortOperation</apiname></xref> class is used in the client application for enhanced search-sort operations
+on the message store. </p> <p>This class can be used for the following: </p> <ul>
+<li id="GUID-7FAD5025-F94D-5824-BFD7-BDFCB83C4F2D"><p>To run a simple or complex
+search-sort request. </p> </li>
+<li id="GUID-94DFA54C-B9B6-5154-BF09-46A45DFCCD1E"><p>To repeat an earlier
+search-sort operation by using the <xref href="GUID-47DEF0FA-908B-31E4-A493-64FE7468F1D1.dita"><apiname>queryId</apiname></xref>. </p> </li>
+<li id="GUID-FBB74619-7822-5EC8-BD69-E7D2F2943896"><p>To receive results either
+in one chunk using an array or one after the other using an iterative method. </p> <note> The
+search-sort results can be received as a list of <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> objects.</note></li>
+</ul> </li>
+<li id="GUID-B757296A-97BD-5816-99BD-7897900CA1F4"><p> <xref href="GUID-A1ECA70D-1D50-3B5F-9D22-74D0215146E7.dita"><apiname>CMsvSearchSortQuery</apiname></xref> </p> <p>The <xref href="GUID-A1ECA70D-1D50-3B5F-9D22-74D0215146E7.dita"><apiname>CMsvSearchSortQuery</apiname></xref> class
+is used in the client application to create a search-sort query. It has an
+interface to add or set the query criteria on various message parts. </p> <p>This
+class provides the following search options: </p> <ul>
+<li id="GUID-F6ABCDEC-C50F-53BA-8817-CA88444765E7"><p>Case sensitive search
+(<xref href="GUID-4F6E4BC7-B77B-390D-BF08-58DF5EF2A959.dita"><apiname>SetCaseSensitiveOption</apiname></xref>) </p> <p>By default this option
+is set to false. </p> </li>
+<li id="GUID-C33F20AC-8F74-5CF6-9446-02227F274E59"><p>Whole word search (<xref href="GUID-D95D1E2A-8D0C-3509-8C51-C36DA28E304D.dita"><apiname>SetWholeWord</apiname></xref>) </p> <p>By
+default this option is set to false. </p> </li>
+<li id="GUID-F9BDA832-A1B8-5596-B619-2A54936D48FB"><p>Wildcard search (<xref href="GUID-BB9B7771-194B-3629-937C-0C829A339463.dita"><apiname>SetWildCardSearch</apiname></xref>) </p> <p>Allow
+the use of the asterisk (*) and question mark (?) wildcards. By default this
+option is set to false. </p> </li>
+<li id="GUID-ACAC32F4-9E34-5A47-A5CB-F9B5D2AE1235"><p>Subfolder search (<xref href="GUID-B06EB103-6ECA-39F0-A3F0-B99D7314CF3C.dita"><apiname>SetSubFolderSearch</apiname></xref>) </p> <p>Include
+the entries within the subfolders in the search result. By default this option
+is set to false. </p> <note> The subfolder option is valid only for a search
+query. </note> </li>
+<li id="GUID-AD053845-DB7D-5447-AD38-A348E51B6DE6"><p>Explicit single level
+sort (using the <codeph>TMsvMessagePart aMessagePart</codeph> parameter
+in the <xref href="GUID-A1ECA70D-1D50-3B5F-9D22-74D0215146E7.dita#GUID-A1ECA70D-1D50-3B5F-9D22-74D0215146E7/GUID-D4A0638E-61AE-3F7D-AB84-D3285F2D4539"><apiname>CMsvSearchSortQuery::AddSearchOptionL</apiname></xref> function. </p> <p>Sorting
+on one particular message part. </p> </li>
+</ul> <p>The <xref href="GUID-A1ECA70D-1D50-3B5F-9D22-74D0215146E7.dita"><apiname>CMsvSearchSortQuery</apiname></xref> class is used with the <xref href="GUID-5D956759-5D21-3715-916E-F7E703172762.dita"><apiname>CMsvSearchSortOperation</apiname></xref> class
+when requesting a new search-sort operation. </p> <note type="important"> By
+default, the search query results are not sorted. To receive a result in a
+sorted order, you must send a sort request by using the <xref href="GUID-A1ECA70D-1D50-3B5F-9D22-74D0215146E7.dita#GUID-A1ECA70D-1D50-3B5F-9D22-74D0215146E7/GUID-CE8F4E20-B1A9-32BF-B1FB-6F4E6CB88C2A"><apiname>CMsvSearchSortQuery::AddSortOptionL()</apiname></xref> function.
+Sort options can be used with search options when creating a search-sort query. </note></li>
+<li id="GUID-6DAE4181-212F-5988-AD0E-C1BF20503952"><p> <xref href="GUID-D9BB2EF0-262F-3BCF-8F48-F40FE0D4C107.dita"><apiname>TMsvMessagePart</apiname></xref> </p> <p>The <xref href="GUID-D9BB2EF0-262F-3BCF-8F48-F40FE0D4C107.dita"><apiname>TMsvMessagePart</apiname></xref> is
+an enumeration type class that contains all parts of the message, including
+index entry and message header. Searching or sorting is done based on the <xref href="GUID-D9BB2EF0-262F-3BCF-8F48-F40FE0D4C107.dita"><apiname>TMsvMessagePart</apiname></xref> class. </p> </li>
+<li id="GUID-EFEB6199-FD8A-55F4-9524-02E5C4A65488"><p> <xref href="GUID-A60B4636-F309-3FD6-8D12-D4EE3AC6BC58.dita"><apiname>TMsvSearchSortResultType</apiname></xref> </p> <p>The <xref href="GUID-A60B4636-F309-3FD6-8D12-D4EE3AC6BC58.dita"><apiname>TMsvSearchSortResultType</apiname></xref> is an enumeration class. The client uses <xref href="GUID-A60B4636-F309-3FD6-8D12-D4EE3AC6BC58.dita"><apiname>TMsvSearchSortResultType</apiname></xref> to
+specify if the search and sort results are returned as <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>. </p> </li>
+<li id="GUID-B07DA71A-4906-5EAB-8A4F-A103EB6F259F"><p> <xref href="GUID-9EC5FF8F-55BF-3D4B-BF1E-6221509E2583.dita"><apiname>TMsvRelationOp</apiname></xref> </p> <p>The <xref href="GUID-9EC5FF8F-55BF-3D4B-BF1E-6221509E2583.dita"><apiname>TMsvRelationOp</apiname></xref> is
+an enumeration type class that is used to provide relational operations between
+the search criteria value and the value in the message part of a message. </p> <p>For
+example, equal to, greater than, greater than or equal to, less than, and
+less than or equal to. </p> </li>
+<li id="GUID-0DA7A049-9FCA-5F7C-9C69-E357BBD5525D"><p> <xref href="GUID-94A91DF4-2362-3042-A230-79B4B294B2F6.dita"><apiname>TMsvSortOrder</apiname></xref> </p> <p>The <xref href="GUID-94A91DF4-2362-3042-A230-79B4B294B2F6.dita"><apiname>TMsvSortOrder</apiname></xref> is
+an enumeration type class that is used to provide the sorting options for
+sorting queries. The search or sort results can be sorted in ascending or
+descending order. </p> </li>
+</ul> </section>
+<section id="GUID-995B61DB-FB68-591E-8810-1DA96C882435"><title>Advantages</title> <p>The
+following are the advantages of the enhanced search-sort functionality: </p> <ul>
+<li id="GUID-D6B66EA5-4E18-5065-8502-7FD78C0147C8"><p>Search messages by the
+following fields: </p><note> Most of the following fields are applicable to
+email messages: </note> <ul>
+<li id="GUID-77DB4B4B-DD60-5164-974A-BD892702FD2B"><p>Sender, recipient list
+(cc, to, bcc), subject </p> </li>
+<li id="GUID-C16729FC-8517-59BF-AEE7-CEF4B6929AC9"><p>Mail size and size range </p> </li>
+<li id="GUID-FDA2E776-CE39-55E6-900E-8EBE826EBABC"><p>Date and date range </p> </li>
+<li id="GUID-24535174-207A-5095-ACCB-38F0A2B4704B"><p>Message type (SMS, Email,
+MMS, and BIO message) </p> </li>
+<li id="GUID-C190645B-B338-5C37-B506-BF783144923D"><p>Priority (high, medium,
+and low) </p> </li>
+<li id="GUID-D8804E92-44D5-5730-A09F-BE5EE62FB505"><p>Attachment types (linked
+attachment and file attachment) </p> </li>
+<li id="GUID-68D9C896-B8B1-5FA4-B833-8A7E9E2A09D0"><p>Message status </p> <p>For
+example, New, Read, Unread, and so on. </p> </li>
+</ul> </li>
+<li id="GUID-D381A082-643C-502A-99A9-1813C2FE5B8D"><p>Search messages containing
+a specified string in a specified message part. </p> </li>
+<li id="GUID-CB9D7CD8-41BF-55EA-B867-5C39192FC984"><p>Search within subfolders
+of the parent folder. </p> </li>
+<li id="GUID-194B52B2-B443-51A2-A7CB-4595CEE0101E"><p>Provides combined search
+and sort options to the client. </p> </li>
+<li id="GUID-21C4E9F2-CF3C-552D-8A4E-E2714060DF87"><p>Provides explicit single
+level of sorting with implicit sort by data and time. </p> </li>
+<li id="GUID-2137FD0D-97F5-58DA-BDC0-2E39EFFA750F"><p>Allows client to implement
+more versatile UI views. </p> </li>
+<li id="GUID-CECCA668-AEBD-5A26-AF0A-D591A7128F65"><p>Returns total number
+of search-sort count without sending the resultant data. For example, the
+number of unread messages in the inbox. </p> </li>
+<li id="GUID-308007D7-B0AC-5E6E-8EB9-2CD56214BED1"><p>Provides good RAM performance
+for repetitive search-sort requests, as the Messaging framework maintains
+a search-sort cache for frequently used search-sort requests. </p> </li>
+</ul> </section>
+<section id="GUID-014C08BD-7FFC-5D2B-A107-316A70D52D12"><title>Limitations</title> <p>The
+following are the limitations of the advanced search and sort functionality: </p> <ul>
+<li id="GUID-1361069B-D79B-5F37-B6D2-5730B73152B4"><p>The search-sort operation
+for a specific value in a specific message part is supported, but searching
+for a specific value in all message parts is not supported. </p> </li>
+<li id="GUID-F0E732EC-D4D5-53AE-A2F2-F09ADF134426"><p>Index entry is migrated
+to SQL. The header and body part are yet to be migrated to SQL. So the iterative
+method is supported only if the message parts in the index entry are used
+in creating the search-sort query. </p> </li>
+<li id="GUID-56127926-2AD8-50CE-81F3-E2CC5AE89EB7"><p>The following are not
+supported in the iterative method because the limitations of SQL: </p> <ul>
+<li id="GUID-F61AF937-A39E-5276-AE13-AEA2F48BF0C3"><p>Accessing the next set
+of values, that is, next <b>n</b> values (results). </p> </li>
+<li id="GUID-17F483B6-427F-59CD-8C47-88D5542E765B"><p>Accessing the previous
+value or the previous set of values. </p> </li>
+<li id="GUID-0323A0FD-DED7-5B44-B53E-565727B59E81"><p>Accessing a random value
+or a random set of values. </p> </li>
+</ul> </li>
+<li id="GUID-C567013B-A385-50B4-BC30-325BB2B073DB"><p>Multi level sorting
+is not supported. </p> </li>
+<li id="GUID-B0BB3E72-1C5F-5F44-AA79-170B4BC2CFD2"><p>A search query can use
+a maximum of five message parts as search criteria in a combined search. </p> </li>
+<li id="GUID-AFC8222E-ACF6-5F11-9D2C-773E9149473E"><p>Sorting on message body
+is not supported. </p> </li>
+<li id="GUID-62916475-9920-5196-9DB3-4F9C517F759B"><p>Search-sort operation
+cannot be performed on all the message parts present in index entry. The supported
+list consists of message parts present in message header, message body and
+a partial list of message parts from index entry. See the <xref href="GUID-D9BB2EF0-262F-3BCF-8F48-F40FE0D4C107.dita"><apiname>TMsvMessagePart</apiname></xref> enumeration
+class for the supported message parts. </p> </li>
+</ul> </section>
+</conbody><related-links>
+<link href="GUID-45CA1787-F41F-5AA0-9508-B9D683602D41.dita"><linktext>Search-Sort
+Cache</linktext></link>
+<link href="GUID-B26A4743-F331-5AC3-A40A-28B14B785857.dita"><linktext>Example code</linktext>
+</link>
</related-links></concept>
\ No newline at end of file