Repetitive Search

Required background

To do a repetitive search operation, that is searching messages using a query ID, you must first get the query ID of that search operation.

Introduction

Every new search-sort asynchronous query that is successful is assigned with a unique 32 bit integer value, which is referred to as a query ID. This query ID is used to initiate the same search-sort operation (initiate a repetitive query) in future. The query ID can be retrieved using the CMsvSearchSortOperation::GetQueryIdL() function.

Marking

When the search-sort cache reaches its maximum size the message server deletes the least recently used query to accommodate a new one. However, there may be some queries and their results which the client wants to keep in the cache, irrespective of how frequently they are being used.

Such queries can be marked by the client to indicate to the Messaging server that the query should not be disposed from the search-sort cache when the cache is full. Marked queries are considered for deletion only if all of the remaining queries are also marked.

To mark a query ID, use the TBool aMarkQuery parameter in the CMsvSearchSortOperation::RequestL() function in your client application.

IMPORT_C void RequestL (CMsvSearchSortQuery* aQuery, TBool aMarkQuery, TRequestStatus& aQueryStatus, TInt aIterator=0)

Unmarking

To unmark a query ID, use the CMsvSearchSortOperation::UnmarkQuery() function in your client application.

IMPORT_C TInt UnmarkQuery  (const TInt aQueryId )

Figure: Repetitive search request process

Procedure

1. To get a query ID, complete the steps from 1 to 10 in New Search.

2. Get the query ID from step 10 and start the search operation using the query ID as the search parameter.

void CSearchsortExample::SeachSortRequestByQueryIdL()
    {
    //1. 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);

    //2. Create an instance of CMsvSearchSortOperation to perform a 
    //search-sort operation    
    CMSvSearchSortOperation* search = CMSvSearchSortOperation::NewL(*session);
    CleanupStack::PushL(search);
            
    //3. Start the search operation using the query ID as the search parameter
    TRequestStatus aStatus;
    search->RequestL(iQueryId, aStatus);

    //4. Wait for the result
    User::WaitForRequest(aStatus);

    //5. Create an array to hold Search-sort results
    RArray<TMsvId> resultArray;

    //6. 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();
        }

    //7. Store the query ID. This ID can be used in repetitive search queries.
    iQueryId = search->GetQueryIdL();
    
    CleanupStack::PopAndDestroy(2); //search, session  
    }

Search-sort example

SearchSortExample: Enhanced Search and Sort for Message Store

See also

For conceptual information on search-sort APIs, see Search-Sort Introduction.