/*

 * 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 <e32base.h>

 #include <mvpbkcontactfindobserver.h>

 #include <mvpbkcontactstorelist.h>

 // 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<MVPbkContactStore*> 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