--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/Symbian3/SDK/Source/GUID-3F938A76-3F27-56ED-BB3D-0E7EC4ACFB9C.dita	Thu Jan 21 18:18:20 2010 +0000
@@ -0,0 +1,186 @@
+<?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_d0e258906_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>
\ No newline at end of file