New -Search

This tutorial provides the steps to perform new search on messages (mainly, -on email messages).

Introduction

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.

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. - New search-sort request process - -

Simple search

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:
1. Descriptor: For searching -on sender, recipient list (cc, to, bcc), subject, date and date range.
2. Integer: For searching -message size and size range.
3. 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 - }

Combined search

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 -

Iterative 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 - } -

-Search-sort example

SearchSortExample: -Enhanced Search and Sort for Message Store

See also

For conceptual information on search-sort -APIs, see Searching -and Sorting Messages.

+ + + + + +New +Search +

This tutorial provides the steps to perform new search on messages (mainly, +on email messages).

Introduction

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.

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. + New search-sort request process + +

Simple search

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:
1. Descriptor: For searching +on sender, recipient list (cc, to, bcc), subject, date and date range.
2. Integer: For searching +message size and size range.
3. 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 + }

Combined search

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 +

Iterative 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 + } +

+Search-sort example

SearchSortExample: +Enhanced Search and Sort for Message Store