<?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 task
  PUBLIC "-//OASIS//DTD DITA Task//EN" "task.dtd">
<task id="GUID-222C2B18-F348-4B16-BB00-E5FAC11AE528" xml:lang="en"><title>Searching
Email Messages</title><shortdesc>This section describes how to search for a given string in the
email messages.</shortdesc><prolog><metadata><keywords/></metadata></prolog><taskbody>
<prereq id="GUID-FBBFDDA9-2462-4B2C-90FF-C9F8BC0B1BF2"><p>Perform the steps
described in <xref href="GUID-1DCB0B64-0B70-4F34-81A7-E00A996AD626.dita">Listing,
Accessing and Launching Mailboxes</xref>.</p></prereq>
<context id="GUID-F089C9E7-E597-40E9-99E5-883553F63EC8">       <p>Email Client
provides <xref href="GUID-88C7C842-73DA-3E6C-8EB9-F098F1E13703.dita"><apiname>MEmailSearchObserver</apiname></xref> class for handling email
search results and <xref href="GUID-DF759001-8469-37B5-9E3B-53FEB295946F.dita"><apiname>MEmailMessageSearchAsync</apiname></xref> class for initiating
the asynchronous search.</p><p>For a specific mailbox, the search function
searches for a given string in all the fields of the messages.</p><p>The search
client is notified of each found message and the <xref href="GUID-88C7C842-73DA-3E6C-8EB9-F098F1E13703.dita#GUID-88C7C842-73DA-3E6C-8EB9-F098F1E13703/GUID-B05D1394-EF24-3D04-B8AE-6B02D5F9F1A9"><apiname>MEmailSearchObserver::SearchCompletedL()</apiname></xref> method
notifies when the search is completed.</p><note> Only one search can be performed
at a time. If a search is already in progress, returns <codeph>KErrNotReady</codeph>.</note> 
   </context>
<steps id="GUID-4DD07DEC-6017-4237-BE46-1D69E5FBD744-GENID-1-12-1-8-1-1-4-1-3-1-5-1-6-1-3-3">
<step id="GUID-A7151932-CABC-443B-8A6A-8C0E130ABC35"><cmd>Implement the <xref href="GUID-88C7C842-73DA-3E6C-8EB9-F098F1E13703.dita"><apiname>MEmailSearchObserver</apiname></xref> class
and initiate the search using <xref href="GUID-FCDFA4A7-2C82-3FE7-8C0B-2035C6602290.dita#GUID-FCDFA4A7-2C82-3FE7-8C0B-2035C6602290/GUID-1E592410-A37E-3F53-9A89-EF248A67F0BE"><apiname>MEmailMailbox::MessageSearchL()</apiname></xref>.</cmd>
<info><p><codeblock xml:space="preserve">MEmailMailbox* mailbox = mailboxes[i];
MEmailMessageSearchAsync* search = mailbox-&gt;MessageSearchL();
CleanupReleasePushL( *search );
search-&gt;StartSearchL( *this ); // this implements MEmailSearchObserver
</codeblock></p></info>
</step>
<step id="GUID-B22C450B-5135-41E5-9113-4958F7E031E4"><cmd>To cancel the search
use <xref href="GUID-DF759001-8469-37B5-9E3B-53FEB295946F.dita#GUID-DF759001-8469-37B5-9E3B-53FEB295946F/GUID-2D775D93-1C2C-3D4B-8730-4ED5BE2C9579"><apiname>MEmailMessageSearchAsync::Cancel()</apiname></xref> method.</cmd>
</step>
</steps>
<example><p>The following code snippet shows an example of how to search for
a given string on all the mailboxes that are found.</p><codeblock xml:space="preserve">TInt CEmailClientApiTester::SearchWithResultsL( CItemParser&amp; /* aItem */)
	{
		TInt ret(KErrNone);    
		MEmailClientApi* mailClient = CreateFactoryAndClientApiLC();  // Factory, client
		RMailboxPtrArray mailboxes;   
		CleanupResetAndRelease&lt;MEmailMailbox&gt;::PushL( mailboxes );    // Mailboxes
		mailClient-&gt;GetMailboxesL( mailboxes );
		if (mailboxes.Count() &gt; 0)
		{
			MEmailMailbox* mailbox = mailboxes[0]; // Do the test with the first found mailbox
			MEmailMessageSearchAsync* searchAPI;            
			searchAPI = mailbox-&gt;MessageSearchL();
			searchAPI-&gt;AddSearchKeyL(_L("Test1"));
			searchAPI-&gt;AddSearchKeyL(_L("Test2"));        
			TEmailSortCriteria criteria;
			criteria.iAscending = ETrue;
			criteria.iField = TEmailSortCriteria::EByDate;                 
			searchAPI-&gt;SetSortCriteriaL(criteria);
			CSearchObserver* obs = CSearchObserver::NewL(this);
			CleanupStack::PushL( obs );        
			searchAPI-&gt;StartSearchL(*obs);
			TInt status = searchAPI-&gt;Status();
			iLog-&gt;Log( _L( "Search started, ascending=true, status=%d"), status);
			obs-&gt;Wait();
			searchAPI-&gt;Reset();
			searchAPI-&gt;AddSearchKeyL(_L("Test1"));
			searchAPI-&gt;AddSearchKeyL(_L("Test2"));        
			criteria.iAscending = EFalse;
			criteria.iField = TEmailSortCriteria::EByDate;                 
			searchAPI-&gt;SetSortCriteriaL(criteria);
			searchAPI-&gt;StartSearchL(*obs);
			status = searchAPI-&gt;Status();
			obs-&gt;Wait();
			searchAPI-&gt;Release();        
		}
		else
		{
			ret = KErrNotFound;        
		}
		CleanupStack::PopAndDestroy(4); // factory, mailClient, mailboxes, observer return ret;
	}
</codeblock></example>
</taskbody><related-links>
<link href="GUID-B87B9E01-F5EB-40F6-A580-A7E46869AE39.dita"><linktext>Email Client
API Overview</linktext></link>
<link href="GUID-1DCB0B64-0B70-4F34-81A7-E00A996AD626.dita"><linktext>Listing,
Accessing and Launching Mailboxes</linktext></link>
<link href="GUID-FC308B84-E109-48F3-90F1-78F0C837CC56.dita"><linktext>Creating,
Replying and Forwarding Email Messages</linktext></link>
</related-links></task>