<?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_d0e283471_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-&gt;SetParentId(KMsvRootIndexEntryIdValue);
    //Set the type of result expected out of the search-sort operation. 
    searchQuery-&gt;SetResultType(EMsvResultAsTMsvId);
    searchQuery-&gt;SetWholeWord(ETrue);
    searchQuery-&gt;SetCaseSensitiveOption(ETrue);
    searchQuery-&gt;SetWildCardSearch(EFalse);
    
    //3. Add search option
    _LIT( KMsgTo, “david@nokia.com”) ;
    searchQuery-&gt;AddSearchOptionL(EMsvTo, KMsgTo, EMsvEqual);
    // Add sort option
    searchQuery-&gt;AddSortOptionL(EMsvSize, EMsvSortAscending);   
    
    //4. Create a session with message server
    // NOTE: CMsvSession::OpenSyncL requires a &amp;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-&gt;RequestL(searchQuery, ETrue, aStatus);

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

    //8. Create an array to hold Search-sort results
    RArray&lt;TMsvId&gt; 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-&gt;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-&gt;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-&gt;AddSearchOptionL(EMsvTo, KMsgTo, EMsvEqual);
    //Add additional option(s) for combined search.
    TInt size = 100;
    searchQuery-&gt;AddSearchOptionL(EMsvSize, size, EMsvGreaterThanOrEqual); // Integer value search
    searchQuery-&gt;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-&gt;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-&gt;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>
</conbody></concept>