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
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:
-
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 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.
Note: 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.
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 CMsvSearchSortQuery::AddSortOptionL() function. Sort options can be used with search options when creating a search-sort query. -
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.
-
The TMsvSearchSortResultType is an enumeration class. The client uses TMsvSearchSortResultType to specify if the search and sort results are returned as TMsvId or TMsvEntry.
-
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.
-
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:
Note: Most of the following fields are applicable to email messages: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:
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.