Search-Sort +Introduction

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.

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.

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:

Combined search (combination +of more than one simple search criteria)
Search based on whole +and partial words
Case sensitive search
Wildcard search
Count of total search +results
Single level sorting +of search results
Iterative mechanism +for clients to access the search and sort results sequentially.

The following sections include basic information on the search-sort functionality, +which is important to understand before using the search-sort APIs:

Description
Search-sort API summary
Advantages
Limitations

Description

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.

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.

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.

If it is a new query, +the Message Server stores the search query in the cache, and passes the query +to the SQL database.

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.

The iterative method can be used +for searching and sorting a new or a repetitive search query.

The +following table provides detailed information on the fields supported in the +search-sort operation:

+ + + +Operation +Header +Body +TMsvEntry + + + + +

Searching

To, cc, bcc, from, subject

Body part, whole and partial word (case sensitive and insensitive, +whole word, wildcard)

Attachment type, read, unread, new flag, priority, size, MTM type, +iDescription, iDetails, and date and time.

+ + +

Searching with explicit sorting

To, cc, bcc, from, subject

Attachment type, read, unread, new flag, priority, size, MTM type, +iDescription, iDetails, and date and time.

+ + +

Sorting

To, cc, bcc, from, subject

+ +

Attachment type, read, unread, new flag, priority, size, MTM type, +iDescription, iDetails, and date and time.

+ + + +

Key terms

Iterator: 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.
Search-sort cache: Search-sort cache contains frequently requested search-sort queries. +By default, this cache is set to 20 percent of the index entry cache.

For +more information the search-sort cache, see Search-Sort +Cache.

Search-sort +API summary

Use the following APIs available in msgs.dll for +searching and sorting messages:

+ High level class diagram of new search-sort API + + +

CMsvSearchSortOperation

The CMsvSearchSortOperation class is used in the client application for enhanced search-sort operations +on the message store.

This class can be used for the following:
- To run a simple or complex +search-sort request.
- To repeat an earlier +search-sort operation by using the queryId.
- To receive results either +in one chunk using an array or one after the other using an iterative method.
  The +search-sort results can be received as a list of TMsvId or TMsvEntry objects.
CMsvSearchSortQuery

The CMsvSearchSortQuery 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.

This +class provides the following search options:
- Case sensitive search +(SetCaseSensitiveOption)
  
  By default this option +is set to false.
- Whole word search (SetWholeWord)
  
  By +default this option is set to false.
- Wildcard search (SetWildCardSearch)
  
  Allow +the use of the asterisk (*) and question mark (?) wildcards. By default this +option is set to false.
- Subfolder search (SetSubFolderSearch)
  
  Include +the entries within the subfolders in the search result. By default this option +is set to false.
  The subfolder option is valid only for a search +query.
- Explicit single level +sort (using the TMsvMessagePart aMessagePart parameter +in the CMsvSearchSortQuery::AddSearchOptionL function.
  
  Sorting +on one particular message part.
The CMsvSearchSortQuery class is used with the CMsvSearchSortOperation class +when requesting a new search-sort operation.
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 CMsvSearchSortQuery::AddSortOptionL() function. +Sort options can be used with search options when creating a search-sort query.
TMsvMessagePart

The TMsvMessagePart 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 TMsvMessagePart class.
TMsvSearchSortResultType

The TMsvSearchSortResultType is an enumeration class. The client uses TMsvSearchSortResultType to +specify if the search and sort results are returned as TMsvId or TMsvEntry.
TMsvRelationOp

The TMsvRelationOp 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.

For +example, equal to, greater than, greater than or equal to, less than, and +less than or equal to.
TMsvSortOrder

The TMsvSortOrder 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.

Advantages

The +following are the advantages of the enhanced search-sort functionality:

Search messages by the +following fields:
Most of the following fields are applicable to +email messages:
- Sender, recipient list +(cc, to, bcc), subject
- Mail size and size range
- Date and date range
- Message type (SMS, Email, +MMS, and BIO message)
- Priority (high, medium, +and low)
- Attachment types (linked +attachment and file attachment)
- Message status
  
  For +example, New, Read, Unread, and so on.
Search messages containing +a specified string in a specified message part.
Search within subfolders +of the parent folder.
Provides combined search +and sort options to the client.
Provides explicit single +level of sorting with implicit sort by data and time.
Allows client to implement +more versatile UI views.
Returns total number +of search-sort count without sending the resultant data. For example, the +number of unread messages in the inbox.
Provides good RAM performance +for repetitive search-sort requests, as the Messaging framework maintains +a search-sort cache for frequently used search-sort requests.

Limitations

The +following are the limitations of the advanced search and sort functionality:

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.
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.
The following are not +supported in the iterative method because the limitations of SQL:
- Accessing the next set +of values, that is, next n values (results).
- Accessing the previous +value or the previous set of values.
- Accessing a random value +or a random set of values.
Multi level sorting +is not supported.
A search query can use +a maximum of five message parts as search criteria in a combined search.
Sorting on message body +is not supported.
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 TMsvMessagePart enumeration +class for the supported message parts.