1 /*

     2 * Copyright (c) 2002-2009 Nokia Corporation and/or its subsidiary(-ies).

     3 * All rights reserved.

     4 * This component and the accompanying materials are made available

     5 * under the terms of "Eclipse Public License v1.0"

     6 * which accompanies this distribution, and is available

     7 * at the URL "http://www.eclipse.org/legal/epl-v10.html".

     8 *

     9 * Initial Contributors:

    10 * Nokia Corporation - initial contribution.

    11 *

    12 * Contributors:

    13 *

    14 * Description: 

    15 *

    16 */

    17 

    18 

    19 #ifndef __CNTVIEWFINDCONFIG_H__

    20 #define __CNTVIEWFINDCONFIG_H__

    21 

    22 #include <e32base.h>

    23 #include "ecom/ecom.h"		// for recomsession

    24 

    25 class CContactViewFindConfigInterface : public CBase

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

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

    28 

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

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

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

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

    33 will be loaded when ContactsMatchingCriteriaL() or ContactsMatchingPrefixL() 

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

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

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

    37 @publishedPartner

    38 @released

    39 */

    40 	{

    41 	public:

    42 	static CContactViewFindConfigInterface* NewL(TUid aImplementationUid);

    43 	inline virtual ~CContactViewFindConfigInterface();

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

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

    46 	behaviour.

    47 	

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

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

    50 	TLS to store the data). */

    51 	virtual void OpenL() = 0;

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

    53 	behaviour.

    54 	

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

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

    57 	TLS to store the data). */

    58 	virtual void Close() = 0;

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

    60 	

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

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

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

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

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

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

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

    68 	of Match().

    69 	

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

    71 	return EFalse for non-Chinese words.

    72 	

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

    74 	using TDesC16::MatchC() instead.

    75 	

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

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

    78 	ContactsMatchingCriteriaL() or ContactsMatchingPrefixL() was called.

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

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

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

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

    83 	

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

    85 	

    86 	@param aItemString The string that is being searched.

    87 	@param aSearchText The string to search for.

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

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

    90 	private:

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

    92 	TUid iDtor_ID_Key;

    93 	};

    94 

    95 #include <cntviewfindconfig.inl>

    96 

    97 #endif