This tutorial provides the steps to perform new search on messages (mainly, on email messages).
You can perform the following types of search on messages (mainly, on email messages):
Simple search
In a simple search, you use only one message field as a search criteria in a search request. The single message field can be: to, from, cc, size, time, message type, message status, priority, attachment type or message body. For example, search for all emails sent to Sam.
Combined search
In a combined search, you use more than one message field as a search criteria in a search request. The message fields can be a combination of: to, from, cc, size, time, message type, message status, priority, attachment type, and message body.
Note: You can use maximum of five message parts as a search criteria in a combined search.
For a combined search, the CMsvSearchSortQuery::AddSearchOptionL() function can be called more than once depending on the message fields you use in the search query. For example, if you have to search all messages from sender Albert, with subject Invitation, then you must call the AddSearchQueryOptions function twice.
However, you can use any functions of the TMsvSearchSortQuery class only once in each combined search query.
Iterative method
You can enable an iterative method in simple and combined searches:
Iterative
The iterative method allows a client to access the search-sort results sequentially one at a time. It is useful when a client cannot, or does not want to provide the memory to receive an array of results.
Non-iterative
This method retrieves the complete results of the query in a single array. It requires sufficient RAM on the client-side. This is particularly useful for queries that return small subset of results.
Note: You specify the method with the
TInt aIterator
parameter
when the client sends a query to the Message Server. By default, the value
is zero (0
) which indicates the non-iterative method. You
must set it to 1
to get specify the iterative method.Figure: New search-sort request process
Create a search-sort query using the CMsvSearchSortQuery::NewL() function.
Configure the query by setting parameters, such as the directory to search in, the format for the results, whether to search for whole or part words, whether to use wild cards, the case sensitivity, the values and fields to search and the sorting options.
Add the search-sort operation using the search query as a parameter using the CMsvSearchSortQuery::AddSearchOptionL() function. There are three versions of the AddSearchOptionL() function, each of which takes a different parameter type:
Descriptor: For searching on sender, recipient list (cc, to, bcc), subject, date and date range.
Integer: For searching message size and size range.
Boolean: For searching on priority (high, medium and low), attachment types, message status.
Note: If necessary, enable sorting of search result in ascending or descending order on the message part added in the query.
Create a session with
the Messaging server using the CMsvSession
class.
Create a search-sort operation using the CMsvSearchSortOperation class.
Start the search-sort operation by calling the CMsvSearchSortOperation::RequestL() function and passing the query as a parameter. Do not include an iterator parameter. It will default to zero (non-iterative).
Wait for the Messaging Server to perform the search.
Create an array for storing the results of the search.
Retrieve the results from the search into the array using the CMsvSearchSortOperation::GetResultsL() function.
Get the query ID of the search from the Messaging server, if necessary, for later use using the CMsvSearchSortOperation::GetQueryId() function.
/** Simple Seachsort request without iterator. */ void CSearchsortExample::SeachSortRequestWithoutIteratorL() { //1. Create an instance of CMsvSearchSortQuery to create a //search-sort query CMsvSearchSortQuery* searchQuery = CMsvSearchSortQuery::NewL(); CleanupStack::PushL(searchQuery); //2. Configure the query. //Search-sort operation is performed on a specified folder. //(e.g, on INBOX, SENT ITEMS, //DRAFT, OUTBOX or any user created folder). Needs to set the value of the folder entry. searchQuery->SetParentId(KMsvRootIndexEntryIdValue); //Set the type of result expected out of the search-sort operation. searchQuery->SetResultType(EMsvResultAsTMsvId); searchQuery->SetWholeWord(ETrue); searchQuery->SetCaseSensitiveOption(ETrue); searchQuery->SetWildCardSearch(EFalse); //3. Add search option _LIT( KMsgTo, “david@nokia.com”) ; searchQuery->AddSearchOptionL(EMsvTo, KMsgTo, EMsvEqual); // Add sort option searchQuery->AddSortOptionL(EMsvSize, EMsvSortAscending); //4. Create a session with message server // NOTE: CMsvSession::OpenSyncL requires a &MMsvObserver parameter. This example assumes that // CSearchSortExample implements MMsvObserver. CMsvSession* session = CMsvSession::OpenSyncL(*this); CleanupStack::PushL(session); //5. Create an instance of CMsvSearchSortOperation to perform a //search-sort operation CMSvSearchSortOperation* search = CMSvSearchSortOperation::NewL(*session); CleanupStack::PushL(search); //6. Start the search operation using the query as a parameter TRequestStatus aStatus; CleanupStack::Pop(searchQuery); // ownership of searchQuery is passed to SearchSortOperation search->RequestL(searchQuery, ETrue, aStatus); //7. Wait for the result User::WaitForRequest(aStatus); //8. Create an array to hold Search-sort results RArray<TMsvId> resultArray; //9. Retrieve the results of the search. The format for the results should be the same as // what is configured in step 2. Else, will leave with the KErrMsvInvalidResultRequest // error TInt err = search->GetResultsL(resultArray); if(ret == KErrNone) { TInt count = resultArray.Count(); } //10. Get the query ID. This ID can be used in repetitive search queries. iQueryId = search->GetQueryIdL(); CleanupStack::PopAndDestroy(2); //search, session }
To create a combined search, add an additional search options in step 3.
//3. Add search option _LIT( KMsgTo, “david@nokia.com”) ; searchQuery->AddSearchOptionL(EMsvTo, KMsgTo, EMsvEqual); //Add additional option(s) for combined search. TInt size = 100; searchQuery->AddSearchOptionL(EMsvSize, size, EMsvGreaterThanOrEqual); // Integer value search searchQuery->AddSearchOptionL(EMsvAttachment, ETrue); // boolean value search
To create an iterative search, specify an iterative parameter at step 6.
// 6. Start the search operation using the query as a parameter // Specify the iterative method const TInt KIterativeSearch = 1 ; TRequestStatus aStatus; CleanupStack::Pop(searchQuery); // ownership of searchQuery is passed to SearchSortOperation search->RequestL(searchQuery, ETrue, aStatus, KIterativeSearch); // 9. The results of an iterative search must be retrieved from the message server one at a time // Retrieve the results of the search one at a time TMsvId result; //GetNextResultL returns the number of results remaining in the search. while( search->GetNextResultL( result ) ) { // process result }
SearchSortExample: Enhanced Search and Sort for Message Store
For conceptual information on search-sort APIs, see Searching and Sorting Messages.