<?xml version="1.0" encoding="utf-8"?>

<!-- Copyright (c) 2007-2010 Nokia Corporation and/or its subsidiary(-ies) All rights reserved. -->

<!-- This component and the accompanying materials are made available under the terms of the License 

"Eclipse Public License v1.0" which accompanies this distribution, 

and is available at the URL "http://www.eclipse.org/legal/epl-v10.html". -->

<!-- Initial Contributors:

    Nokia Corporation - initial contribution.

Contributors: 

-->

<!DOCTYPE concept

  PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd">

<concept id="GUID-3F938A76-3F27-56ED-BB3D-0E7EC4ACFB9C" xml:lang="en"><title>New

Search</title><prolog><metadata><keywords/></metadata></prolog><conbody>

<p>This tutorial provides the steps to perform new search on messages (mainly,

on email messages). </p>

<section><title>Introduction</title> <p>You can perform the following types

of search on messages (mainly, on email messages): </p> <ul>

<li id="GUID-5851CB02-D769-546E-B748-E6C1E0C1EB8C"><p> <b>Simple search</b>  </p> <p>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 <i>Sam</i>. </p> </li>

<li id="GUID-3F4B645D-3A6A-5ED8-AF07-41F02D20F551"><p> <b>Combined search</b>  </p> <p>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. </p> <p> <b>Note:</b> You can use maximum of five message parts

as a search criteria in a combined search. </p> <p>For a combined search,

the <xref href="GUID-A1ECA70D-1D50-3B5F-9D22-74D0215146E7.dita#GUID-A1ECA70D-1D50-3B5F-9D22-74D0215146E7/GUID-D5AC69E9-75E0-3179-B12B-1D9521684D4D"><apiname>CMsvSearchSortQuery::AddSearchOptionL()</apiname></xref> 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 <i>Albert</i>,

with <b>subject</b>  <i>Invitation</i>, then you must call the <xref href="GUID-E49C2AFE-5793-37A6-9A08-2A1DD5CCA160.dita"><apiname>AddSearchQueryOptions</apiname></xref> function

twice. </p> <p>However, you can use any functions of the <xref href="GUID-F2882FAD-A108-342E-8E35-039C83EFEF55.dita"><apiname>TMsvSearchSortQuery</apiname></xref> class

only once in each combined search query. </p> </li>

</ul> <p><b>Iterative method</b> </p> <p>You can enable an iterative method

in simple and combined searches: </p> <ul>

<li id="GUID-855C5460-41A4-5946-9973-67624AFFE3D6"><p> <b>Iterative</b>  </p> <p>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. </p> </li>

<li id="GUID-0EA3F74E-E3AA-5DCE-A400-B8D1DA8E998B"><p> <b> Non-iterative</b>  </p> <p>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. </p> </li>

</ul><note> You specify the method with the <codeph>TInt aIterator</codeph> parameter

when the client sends a query to the Message Server. By default, the value

is zero (<codeph>0</codeph>) which indicates the non-iterative method. You

must set it to <codeph>1</codeph> to get specify the iterative method.</note> <fig id="GUID-B440387E-2A93-5DF0-9E81-79FCA72AB5C8">

<title>                 New search-sort request process               </title>

<image href="GUID-21E43B0E-85C7-536E-83A5-E829820775BF_d0e485288_href.png" placement="inline"/>

</fig> </section>

<section><title>Simple search</title> <ol id="GUID-40D841C8-004A-5E15-AB18-DD1E3D9C0164">

<li id="GUID-90D2E877-B63F-57C5-9601-47CC2AE67325"><p>Create a search-sort

query using the <xref href="GUID-A1ECA70D-1D50-3B5F-9D22-74D0215146E7.dita#GUID-A1ECA70D-1D50-3B5F-9D22-74D0215146E7/GUID-B39D5F47-158A-38C8-8552-B3B5581554F7"><apiname>CMsvSearchSortQuery::NewL()</apiname></xref> function. </p> </li>

<li id="GUID-F140F72C-3314-5F79-8F00-5E518CE2A2CF"><p>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. </p> </li>

<li id="GUID-5DBE5827-C1C4-5F38-9F43-76DEFD7FA70E"><p>Add the search-sort

operation using the search query as a parameter using the <xref href="GUID-A1ECA70D-1D50-3B5F-9D22-74D0215146E7.dita#GUID-A1ECA70D-1D50-3B5F-9D22-74D0215146E7/GUID-D5AC69E9-75E0-3179-B12B-1D9521684D4D"><apiname>CMsvSearchSortQuery::AddSearchOptionL()</apiname></xref> function.

There are three versions of the <xref href="GUID-99504AB6-680F-3D96-BA10-CF04D8C23554.dita"><apiname>AddSearchOptionL()</apiname></xref> function,

each of which takes a different parameter type: </p> <ol id="GUID-9E468043-DDA7-53D3-A859-1EA1588ABFB5">

<li id="GUID-B73CCE8B-B404-553A-AE55-F16BAE3BDCC6"><p>Descriptor: For searching

on sender, recipient list (cc, to, bcc), subject, date and date range. </p> </li>

<li id="GUID-3A0E35A3-FE7A-5853-94FA-7247F92DBBB5"><p>Integer: For searching

message size and size range. </p> </li>

<li id="GUID-B026C578-BC3F-51C8-AA60-F1EE42B58E10"><p>Boolean: For searching

on priority (high, medium and low), attachment types, message status. </p> </li>

</ol> <p> Note: If necessary, enable sorting of search result in ascending

or descending order on the message part added in the query. </p> </li>

<li id="GUID-79E1C31B-D45A-5F24-8761-A789005A77A0"><p>Create a session with

the Messaging server using the <xref href="GUID-2DA04D96-F0AD-3FDC-9E36-1C27D889AF4B.dita"><apiname>CMsvSession</apiname></xref> class. </p> </li>

<li id="GUID-1159ADC2-1226-575E-BA82-3ECE7010630A"><p>Create a search-sort

operation using the <xref href="GUID-5D956759-5D21-3715-916E-F7E703172762.dita"><apiname>CMsvSearchSortOperation</apiname></xref> class. </p> </li>

<li id="GUID-0FC467F8-F7F1-5FEA-9CBC-5EF7E756834C"><p>Start the search-sort

operation by calling the <xref href="GUID-5D956759-5D21-3715-916E-F7E703172762.dita#GUID-5D956759-5D21-3715-916E-F7E703172762/GUID-6C81A72A-3BEC-3D18-9CAD-46E9309C3FEB"><apiname>CMsvSearchSortOperation::RequestL()</apiname></xref> function

and passing the query as a parameter. Do not include an iterator parameter.

It will default to zero (non-iterative). </p> </li>

<li id="GUID-5C94A9EF-88F1-5B71-9D7A-2EF7C69D77AB"><p>Wait for the Messaging

Server to perform the search. </p> </li>

<li id="GUID-D2EAE048-D5CA-5728-967E-4830873E11DE"><p>Create an array for

storing the results of the search. </p> </li>

<li id="GUID-8258A7BA-DF95-59B9-B9C9-AEDE61EFEEA7"><p>Retrieve the results

from the search into the array using the <xref href="GUID-5D956759-5D21-3715-916E-F7E703172762.dita#GUID-5D956759-5D21-3715-916E-F7E703172762/GUID-1D6974D1-FF31-3B7C-A726-47A8510E9819"><apiname>CMsvSearchSortOperation::GetResultsL()</apiname></xref> function. </p> </li>

<li id="GUID-0B0C26C5-6FA7-5CFA-8C5B-9CEB5C7BC5C0"><p>Get the query ID of

the search from the Messaging server, if necessary, for later use using the <xref href="GUID-5D956759-5D21-3715-916E-F7E703172762.dita#GUID-5D956759-5D21-3715-916E-F7E703172762/GUID-989B6F32-DE88-373B-9CA4-5474BB6858CD"><apiname>CMsvSearchSortOperation::GetQueryId()</apiname></xref> function. </p> </li>

</ol> <codeblock xml:space="preserve">/**

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  

    }	</codeblock></section>

<section id="GUID-AE684DF2-5BF3-5B87-8C10-6F69C87622CA"><title>Combined search</title> <p>To

create a combined search, add an additional search options in step 3. </p> <codeblock id="GUID-E85BCF64-B96D-5B2C-A4B4-E55B3B4AC83B" xml:space="preserve">    //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

     </codeblock> </section>

<section id="GUID-0553ACB4-0ABD-5EC8-B7BC-D3217373064B"><title>Iterative search</title> <p>To

create an iterative search, specify an iterative parameter at step 6. </p> <codeblock id="GUID-130C7E2A-157A-5D2E-97D9-DCF7CBBD0301" xml:space="preserve">     // 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

        }

</codeblock> </section>

<example><title>Search-sort example</title> <p><xref href="GUID-B26A4743-F331-5AC3-A40A-28B14B785857.dita">SearchSortExample:

Enhanced Search and Sort for Message Store </xref>  </p> </example>

<section><title>See also</title> <p>For conceptual information on search-sort

APIs, see <xref href="GUID-32C1FC8B-F7D2-5275-BDF2-0D662551294C.dita">Searching

and Sorting Messages</xref>. </p> </section>