SearchSortExample: -enhanced search and sort for Message Store

Purpose

Prior to Symbian^3, the Message Store API -had limited support for selecting and sorting message records and fields. -From Symbian^3, the API implements more extensive search and sort options.

This -example demonstrates the new functionality by implementing the following use -cases:

Display the header information -for all message entries.
Perform a simple (single -search criteria) non-iterative search-sort and display the matching entries. -This has the following options:
- case sensitivity on -/ off,
- whole word search on -/ off.
Perform a combined (more -than one search criteria) non-iterative search-sort and display the number -of matching entries. This has the following options:
- case sensitivity on -/ off,
- whole word search on -/ off.
Perform an iterative -search-sort (searches for entries one at a time) and display the number of -matching entries.
Perform a search-sort -using a query ID. The query ID is generated by a previous search-sort operation.

Before implementing these use cases, the example creates a POP3/SMTP -message store with five message entries.

Class summary

The example demonstrates the following -classes and enums:

CMsvSearchSortOperation CMsvSearchSortQuery TMsvMessagePart TMsvSearchSortResultType

Download

Click -on the following link to download the example: searchsortexample.zip

Click: browse to view the example code.

Design -and implementation

Project Implementation

The project -implements the following classes:

CKeyReader: Derived from CActive. -This reads keypresses and calls the appropriate example function.

CMessAsyncWaiter: Derived -from CActive. This handles the CMsvSearchSortOperation::RequestL() asynchronous -request. This RequestL() function takes CMessAsyncWaiter::iStatus as -one of its parameters and then waits on the status. When the search is complete -the client is notified of the event's completion by CMessAsyncWaiter::RunL() being -called, after which the example prepares the buffer and displays the results.

CSearchsortExample: Derived -from CBase and MMsvSessionObserver. MMsvSessionObserver is -an interface for notification of events from a Message Server session.

CSearchsortExample implements HandleSessionEventL() to handle the two event types EMsvEntriesCreated and EMsvServerReady. -It also creates the SMTP message entries and carries out searching and sorting.

Simple -non-iterative search-sort

The example starts by creating a message -server session using CMsvSession, which represents a channel -of communication between a client thread (client-side MTM, user interface -MTM, or message client application) and the Message Server thread. Then it -creates an instance of CMsvSearchSortOperation to perform -the search-sort operation, and passes the session object into it.

A -search-sort query is created using CMsvSearchSortQuery::NewL() and -is configured using various member functions of class CMsvSearchSortQuery for -instance whether to search for whole or partial words and the case sensitivity.

The -search and sort options are added to the query using CMsvSearchSortQuery::AddSearchOptionL() and CMsvSearchSortQuery::AddSortOptionL().

The search-sort operation is started by calling CMsvSearchSortOperation::RequestL(), -passing the query as a parameter. If no iterator parameter is specified, the -search defaults to non-iterative.

An instance of the CMessAsyncWaiter class -is created for handling the asynchronous search request. This object is waited -on until the Message Server completes the request. The results of the search -are stored in an array using CMsvSearchSortOperation::GetResultsL().

The -result count is displayed by calling CMsvSearchSortOperation::GetResultCountL().

The -query ID of the search is retrieved from the Message server, for later use, -using the CMsvSearchSortOperation::GetQueryId() function.

Simple -iterative search-sort

Iterative search-sort follows the same steps -as described above, except that an iterator parameter is passed to the RequestL() function. -To retrieve the results, CMsvSearchSortOperation::GetNextResultL() is -called in a while loop to retrieve one entry at a time. Iterative -searching is useful when the client may not have enough memory to store an -array of results.

Combined search-sort

A combined search-sort -is done by adding additional search options using CMsvSearchSortQuery::AddSearchOptionL().

Search-sort -using a query ID

A query ID identifies a search-sort query. It -is obtained by calling CMsvSearchSortOperation::GetQueryIdL() following -the completion of CMsvSearchSortOperation::RequestL(). -In this example, the query ID generated by the simple non-iterative search-sort -is used to repeat the same search-sort. The overloaded CMsvSearchSortOperation::RequestL() function -is used to initiate a search-sort operation with a query ID.

After -the request completes, a list of index entry ID objects (TMsvId or TMsvEntry depending -on how the query was configured, using CMsvSearchSortQuery::SetResultType()) -is retrieved using CMsvSearchSortOperation::GetResultsL(). -Finally the matching results are displayed in the console.

Building and -configuring

To build the example:

You can build the example -from your IDE or the command line.

If you use an IDE, import the bld.inf file -of the example into your IDE, and use the build command of the IDE.

If -you use the command line, open a command prompt, and set the current directory -to the source code directory of the example. You can then build the example -with the SBSv1 build tools with the following commands:

bldmake -bldfiles

abld build

How to use bldmake and How to use abld describe -how to use the SBSv1 build tools.
For the emulator, the -example builds an executable called searchsortexample.exe in -the epoc32\release\winscw\<udeb or urel>\ folder.

Running the -example

searchsortexample.exe takes user -input from the console. The menu for the current example is as shown below:

- -

The user input is handled by CKeyReader::RunL().

For -simple and combined non-iterative search-sort, the user provides the following -inputs: 1) the text in the "To" field to search for, 2) whether case sensitivity -is on of off, 3) whether whole word searching is on or off.

The input -values are saved in variables which are passed to the function CSearchsortExample::SearchSortRequestWithoutIteratorL(), -and the settings are made accordingly.

For the combined search-sort -the 2nd and 3rd search options (size and subject) are hard coded. The iterative -search-sort searches by size, which is also hard coded.

To execute -a search-sort using a query ID, CMsvSearchSortOperation::RequestL() must -first have been called because it generates the query ID. So, either option -2 or 3 must have been called before option 5.