// Copyright (c) 2002-2009 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 "Symbian Foundation License v1.0" to Symbian Foundation members and "Symbian Foundation End User License Agreement v1.0" to non-members

// which accompanies this distribution, and is available

// at the URL "http://www.symbianfoundation.org/legal/licencesv10.html".

//

// Initial Contributors:

// Nokia Corporation - initial contribution.

//

// Contributors:

//

// Description:

//

#ifndef __CNTVIEWFINDCONFIG_H__

#define __CNTVIEWFINDCONFIG_H__

#include <e32base.h>

#include "ecom/ecom.h"		// For REComSession

class CContactViewFindConfigInterface : public CBase

/** An interface class that enables implementers to configure the way in which 

words are matched in CContactViewBase::ContactsMatchingCriteriaL() and CContactViewBase::ContactsMatchingPrefixL().

By default these two functions use TDesC16::MatchC() to do the matching, but 

where this is not appropriate, for instance in Chinese locales, a plug-in 

that implements this interface should be supplied. The plug-in's UID should 

be passed to CContactViewBase::SetViewFindConfigPlugin(), then the plug-in 

will be loaded when ContactsMatchingCriteriaL() or ContactsMatchingPrefixL() 

is called. Note that the plug-in is only loaded once per view, not each time 

a find is requested. Note also that the plug-in is optional. If no plug-in 

is supplied, TDesC16::MatchC() is used instead. 

@publishedPartner

@released

*/

	{

	public:

	static CContactViewFindConfigInterface* NewL(TUid aImplementationUid);

	inline virtual ~CContactViewFindConfigInterface();

	//pure virtual methods to be implemented by the plugin.

	/** May be used by the implementor of the interface to provide construction-like 

	behaviour.

	For example, it might be used to open a connection to a predictive text input 

	database, or might be used for reference counting of shared objects (using 

	TLS to store the data). */

	virtual void OpenL() = 0;

	/** May be used by the implementor of the interface to provide destruction-like 

	behaviour.

	For example, it might be used to close a connection to a predictive text input 

	database, or might be used for reference counting of shared objects (using 

	TLS to store the data). */

	virtual void Close() = 0;

	/** Searches for a string with wildcards in a single field in a contact item.

	@param aContactsField The contents of the contact item field to search.

	@param aWord The string to search for in aContactsField. Note that it contains 

	a '*' wildcard character at the end and optionally one at the beginning, depending 

	on whether ContactsMatchingCriteriaL() or ContactsMatchingPrefixL() was called.

	@return ETrue if aWord is found in aContactsField. EFalse if not. */

	virtual TBool Match(const TDesC& aContactsField, const TDesC& aWord) = 0;

	/** Tests whether a specified word is valid to be matched by the plug-in's implementation 

	of Match().

	For instance, in an implementation for a Chinese locale, this function would 

	return EFalse for non-Chinese words.

	Any words that are not valid to be matched by the plug-in will be matched 

	using TDesC16::MatchC() instead.

	@param aWord The word to be checked. Note that it contains a '*' wildcard 

	character at the end and optionally one at the beginning, depending on whether 

	ContactsMatchingCriteriaL() or ContactsMatchingPrefixL() was called.

	@return ETrue if the word is valid for matching by the plug-in, EFalse if not. */

	virtual TBool IsWordValidForMatching(const TDesC& aWord) = 0;

	/** An optimisation function that may be used to implement incremental find, i.e. 

	involving only the results of a previous search, rather than the entire view.

	This function is not called in v7.0s, but is provided for possible future use.

	@param aItemString The string that is being searched.

	@param aSearchText The string to search for.

	@return ETrue if aSearchText is found in aItemString. EFalse if not. */

	virtual TBool MatchRefineL( const TDesC& aItemString, const TDesC &aSearchText) = 0;

	private:

	//The uid is stored here,so that it can be used during destruction of the instance.

	TUid iDtor_ID_Key;

	};

#include <cntviewfindconfig.inl>

#endif