<?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->MessageSearchL();

CleanupReleasePushL( *search );

search->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<MEmailMailbox>::PushL( mailboxes );    // Mailboxes

		mailClient->GetMailboxesL( mailboxes );

		if (mailboxes.Count() > 0)

		{

			MEmailMailbox* mailbox = mailboxes[0]; // Do the test with the first found mailbox

			MEmailMessageSearchAsync* searchAPI;            

			searchAPI = mailbox->MessageSearchL();

			searchAPI->AddSearchKeyL(_L("Test1"));

			searchAPI->AddSearchKeyL(_L("Test2"));        

			TEmailSortCriteria criteria;

			criteria.iAscending = ETrue;

			criteria.iField = TEmailSortCriteria::EByDate;                 

			searchAPI->SetSortCriteriaL(criteria);

			CSearchObserver* obs = CSearchObserver::NewL(this);

			CleanupStack::PushL( obs );        

			searchAPI->StartSearchL(*obs);

			TInt status = searchAPI->Status();

			iLog->Log( _L( "Search started, ascending=true, status=%d"), status);

			obs->Wait();

			searchAPI->Reset();

			searchAPI->AddSearchKeyL(_L("Test1"));

			searchAPI->AddSearchKeyL(_L("Test2"));        

			criteria.iAscending = EFalse;

			criteria.iField = TEmailSortCriteria::EByDate;                 

			searchAPI->SetSortCriteriaL(criteria);

			searchAPI->StartSearchL(*obs);

			status = searchAPI->Status();

			obs->Wait();

			searchAPI->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>