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