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