New Search

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.

Figure 1. New search-sort request process

Simple search

1. Create a search-sort query using the CMsvSearchSortQuery::NewL() function.

2. 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.

3. 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.

4. Create a session with the Messaging server using the CMsvSession class.

5. Create a search-sort operation using the CMsvSearchSortOperation class.

6. 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).

7. Wait for the Messaging Server to perform the search.

8. Create an array for storing the results of the search.

9. Retrieve the results from the search into the array using the CMsvSearchSortOperation::GetResultsL() function.

10. 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
        }

See also

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