diff -r 000000000000 -r e686773b3f54 contacts_plat/virtual_phonebook_engine_api/inc/CVPbkPhoneNumberMatchStrategy.h --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/contacts_plat/virtual_phonebook_engine_api/inc/CVPbkPhoneNumberMatchStrategy.h Tue Feb 02 10:12:17 2010 +0200 @@ -0,0 +1,242 @@ +/* +* Copyright (c) 2002-2007 Nokia Corporation and/or its subsidiary(-ies). +* All rights reserved. +* This component and the accompanying materials are made available +* under the terms of "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: +* +* Description: A high level class for matching phone numbers from stores. +* +*/ + + +#ifndef CVPBKPHONENUMBERMATCHSTRATEGY_H +#define CVPBKPHONENUMBERMATCHSTRATEGY_H + +// INCLUDE FILES +#include +#include +#include + +// FORWARD DECLARATIONS +class CVPbkContactManager; +class MVPbkContactOperation; +class MVPbkContactStore; +class CVPbkPhoneNumberMatchStrategyImpl; +class CVPbkContactStoreUriArray; + +/** + * Phone number matching strategy. This is the base class of actual + * implementations, but instances of the strategies are created using + * this classes NewL function. Actual implementation selection is done + * based on the given configuration data. + */ +class CVPbkPhoneNumberMatchStrategy : public CBase + { + public: // Types + /** + * Phone number matching mode. The mode can be used to + * configure the match algorithms operation mode. + */ + enum TVPbkPhoneNumberMatchMode + { + /** + * Performs the search sequentially for each store. + */ + EVPbkSequentialMatch, + /** + * Performs the search concurrently for each store. + */ + EVPbkParallelMatch + }; + + /** + * Phone number matching flags. The flags can be used to + * configure the phone number matching strategy. + */ + enum TVPbkPhoneNumberMatchFlags + { + /** + * No additional matching flags. + */ + EVPbkMatchFlagsNone = 0x00000000, + + /** + * Quarantees that only contacts with an exact match + * are included in the result set. The resulted contact + * links are also field links in this case. The link + * points to the first field in the contact with exact + * match. See RetrieveField in + * MVPbkStoreContactFieldCollection. + */ + EVPbkExactMatchFlag = 0x00000001, + + /** + * Stops the search once at least one contact is found. + */ + EVPbkStopOnFirstMatchFlag = 0x00000002, + + /** + * If all matched contacts have the same + * first name and last name field values only first + * one is returned. + */ + EVPbkDuplicatedContactsMatchFlag = 0x00000004 + }; + + /** + * CVPbkPhoneNumberMatchStrategy configuration parameter class. + * This class can be used to configure the phone number find + * strategy. + */ + class TConfig + { + public: + /** + * Constructor. + * + * @param aMaxMatchDigits Maximum number of digits + * used in matching. + * @param aUriPriorities Array of contact store URIs + * to define match priority. + * @param aMatchMode Matching mode to be used when + * searching for matching contacts. + * See TVPbkPhoneNumberMatchMode. + * @param aMatchFlags Match configuration flags. + * See TVPbkPhoneNumberMatchFlags. + */ + inline TConfig( + TInt aMaxMatchDigits, + const CVPbkContactStoreUriArray& aUriPriorities, + TVPbkPhoneNumberMatchMode aMatchMode, + TUint32 aMatchFlags); + + public: // data + ///Own: Maximum number of digits used in matching + TInt iMaxMatchDigits; + ///Ref: Array of contact store URIs to define match priority + const CVPbkContactStoreUriArray& iUriPriorities; + ///Own: Matching mode to be used when searching for + /// matching contacts + TVPbkPhoneNumberMatchMode iMatchMode; + ///Own: Flags to configure matching process, + /// @see TVPbkPhoneNumberMatchFlags + TUint32 iMatchFlags; + ///Own: Reserved for future extension + TAny* iSpare; + }; + + public: // Construction & destruction + /** + * Acts as a factory function for strategy implementation classes + * derived from this class. The actual implementation class is + * determined from the parameters of this function. + * + * @param aConfig Configuration data for phone number matching. + * @param aContactManager Contact manager to be used in matching. + * @param aObserver Observer for the matching operation. + * @return Newly created instance of a class derived from this class. + */ + IMPORT_C static CVPbkPhoneNumberMatchStrategy* NewL( + const TConfig& aConfig, + CVPbkContactManager& aContactManager, + MVPbkContactFindObserver& aObserver); + + /** + * Destructor. + */ + ~CVPbkPhoneNumberMatchStrategy(); + + public: // Interface + /** + * Tries to find matches for given phone number from the stores + * that were specified in the configuration data. This is + * asynchronous operation and the observer will be called + * back when this operation completes. + * + * @param aPhoneNumber Phone number to match. + */ + IMPORT_C void MatchL(const TDesC& aPhoneNumber); + + protected: // Interface for derived classes + /** + * Returns maximum number of digits used in matching. + * @return Maximum number of digits used in matching. + */ + TInt MaxMatchDigits() const; + + /** + * Returns array of stores that are used in matching. + * @return Array of stores that are used in matching. + */ + TArray StoresToMatch() const; + + private: // Interface for derived classes to implement + /** + * Called from MatchL to indicate derived classes that + * matching is about to start. + */ + virtual void InitMatchingL() =0; + + /** + * Creates a new find operation for the next finding step. + * + * @param aPhoneNumber Phone number to match. + * @return Find operation. + */ + virtual MVPbkContactOperation* CreateFindOperationLC( + const TDesC& aPhoneNumber) =0; + + protected: // Implementation + /** + * Constructor. + */ + CVPbkPhoneNumberMatchStrategy(); + + /** + * Initializes the base class. Derived classes must call + * this in their ConstructL. + * @param aConfig Configuration data for phone number matching. + * @param aContactManager Contact manager reference, + * @param aObserver Contact find observer reference. + */ + void BaseConstructL( + const TConfig& aConfig, + CVPbkContactManager& aContactManager, + MVPbkContactFindObserver& aObserver); + + /** + * Returns the find observer to be used for find operations + * created in CreateFindOperationLC. + * @return Contact find observer + */ + MVPbkContactFindObserver& FindObserver() const; + + private: // Data + friend class CVPbkPhoneNumberMatchStrategyImpl; + /// Own: Pointer to implementation + CVPbkPhoneNumberMatchStrategyImpl* iImpl; + }; + +// INLINE FUNCTIONS +inline CVPbkPhoneNumberMatchStrategy::TConfig::TConfig( + TInt aMaxMatchDigits, + const CVPbkContactStoreUriArray& aUriPriorities, + TVPbkPhoneNumberMatchMode aMatchMode, + TUint32 aMatchFlags) : + iMaxMatchDigits(aMaxMatchDigits), + iUriPriorities(aUriPriorities), + iMatchMode(aMatchMode), + iMatchFlags(aMatchFlags) + { + } + +#endif // CVPBKPHONENUMBERMATCHSTRATEGY_H + +// End of File