1 /*

     2 * Copyright (c) 2002-2007 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:  A high level class for matching phone numbers from stores.

    15 *

    16 */

    17 

    18 

    19 #ifndef CVPBKPHONENUMBERMATCHSTRATEGY_H

    20 #define CVPBKPHONENUMBERMATCHSTRATEGY_H

    21 

    22 // INCLUDE FILES

    23 #include <e32base.h>

    24 #include <mvpbkcontactfindobserver.h>

    25 #include <mvpbkcontactstorelist.h>

    26 

    27 // FORWARD DECLARATIONS

    28 class CVPbkContactManager;

    29 class MVPbkContactOperation;

    30 class MVPbkContactStore;

    31 class CVPbkPhoneNumberMatchStrategyImpl;

    32 class CVPbkContactStoreUriArray;

    33 

    34 /**

    35  * Phone number matching strategy. This is the base class of actual 

    36  * implementations, but instances of the strategies are created using

    37  * this classes NewL function. Actual implementation selection is done

    38  * based on the given configuration data.

    39  */

    40 class CVPbkPhoneNumberMatchStrategy : public CBase

    41     {

    42     public: // Types

    43         /**

    44          * Phone number matching mode. The mode can be used to

    45          * configure the match algorithms operation mode.

    46          */

    47         enum TVPbkPhoneNumberMatchMode

    48             {

    49             /**

    50              * Performs the search sequentially for each store.

    51              */

    52             EVPbkSequentialMatch,

    53             /**

    54              * Performs the search concurrently for each store.

    55              */

    56             EVPbkParallelMatch

    57             };

    58 

    59         /**

    60          * Phone number matching flags. The flags can be used to 

    61          * configure the phone number matching strategy.

    62          */

    63         enum TVPbkPhoneNumberMatchFlags

    64             {

    65             /**

    66              * No additional matching flags.

    67              */

    68             EVPbkMatchFlagsNone         = 0x00000000,

    69 

    70             /**

    71              * Quarantees that only contacts with an exact match 

    72              * are included in the result set. The resulted contact 

    73              * links are also field links in this case. The link 

    74              * points to the first field in the contact with exact 

    75              * match. See RetrieveField in 

    76              * MVPbkStoreContactFieldCollection.

    77              */

    78             EVPbkExactMatchFlag         = 0x00000001,

    79 

    80             /**

    81              * Stops the search once at least one contact is found.

    82              */

    83             EVPbkStopOnFirstMatchFlag   = 0x00000002,

    84             

    85             /**

    86              * If all matched contacts have the same

    87              * first name and last name field values only first

    88              * one is returned.

    89              */

    90             EVPbkDuplicatedContactsMatchFlag   = 0x00000004

    91             };

    92 

    93         /**

    94          * CVPbkPhoneNumberMatchStrategy configuration parameter class.

    95          * This class can be used to configure the phone number find

    96          * strategy.

    97          */

    98         class TConfig

    99             {

   100             public:

   101                 /**

   102                  * Constructor.

   103                  *

   104                  * @param aMaxMatchDigits   Maximum number of digits 

   105                  *                          used in matching.

   106                  * @param aUriPriorities    Array of contact store URIs 

   107                  *                          to define match priority.

   108                  * @param aMatchMode    Matching mode to be used when 

   109                  *                      searching for matching contacts. 

   110                  *                      See TVPbkPhoneNumberMatchMode.

   111                  * @param aMatchFlags   Match configuration flags. 

   112                  *                      See TVPbkPhoneNumberMatchFlags.

   113                  */

   114                 inline TConfig(

   115                         TInt aMaxMatchDigits, 

   116                         const CVPbkContactStoreUriArray& aUriPriorities,

   117                         TVPbkPhoneNumberMatchMode aMatchMode,

   118                         TUint32 aMatchFlags);

   119 

   120             public: // data

   121                 ///Own: Maximum number of digits used in matching

   122                 TInt iMaxMatchDigits;

   123                 ///Ref: Array of contact store URIs to define match priority

   124                 const CVPbkContactStoreUriArray& iUriPriorities;

   125                 ///Own: Matching mode to be used when searching for 

   126                 ///     matching contacts

   127                 TVPbkPhoneNumberMatchMode iMatchMode;

   128                 ///Own: Flags to configure matching process, 

   129                 ///     @see TVPbkPhoneNumberMatchFlags

   130                 TUint32 iMatchFlags;

   131                 ///Own: Reserved for future extension

   132                 TAny* iSpare;

   133             };

   134 

   135     public: // Construction & destruction

   136         /**

   137          * Acts as a factory function for strategy implementation classes 

   138          * derived from this class. The actual implementation class is 

   139          * determined from the parameters of this function.

   140          *

   141          * @param aConfig Configuration data for phone number matching.

   142          * @param aContactManager Contact manager to be used in matching.

   143          * @param aObserver Observer for the matching operation.

   144          * @return Newly created instance of a class derived from this class.

   145          */

   146         IMPORT_C static CVPbkPhoneNumberMatchStrategy* NewL(

   147                 const TConfig& aConfig,

   148                 CVPbkContactManager& aContactManager, 

   149                 MVPbkContactFindObserver& aObserver);

   150 

   151         /**

   152          * Destructor.

   153          */

   154         ~CVPbkPhoneNumberMatchStrategy();

   155 

   156     public: // Interface

   157         /**

   158          * Tries to find matches for given phone number from the stores 

   159          * that were specified in the configuration data. This is 

   160          * asynchronous operation and the observer will be called 

   161          * back when this operation completes.

   162          *

   163          * @param aPhoneNumber Phone number to match.

   164          */

   165         IMPORT_C void MatchL(const TDesC& aPhoneNumber);

   166 

   167     protected: // Interface for derived classes

   168         /**

   169          * Returns maximum number of digits used in matching.

   170          * @return Maximum number of digits used in matching.

   171          */

   172         TInt MaxMatchDigits() const;

   173 

   174         /**

   175          * Returns array of stores that are used in matching.

   176          * @return Array of stores that are used in matching.

   177          */

   178         TArray<MVPbkContactStore*> StoresToMatch() const;

   179 

   180     private: // Interface for derived classes to implement

   181         /**

   182          * Called from MatchL to indicate derived classes that 

   183          * matching is about to start.

   184          */

   185         virtual void InitMatchingL() =0;

   186 

   187         /**

   188          * Creates a new find operation for the next finding step.

   189          *

   190          * @param aPhoneNumber Phone number to match.

   191          * @return Find operation.

   192          */

   193         virtual MVPbkContactOperation* CreateFindOperationLC(

   194                 const TDesC& aPhoneNumber) =0;

   195 

   196     protected: // Implementation

   197         /**

   198          * Constructor.

   199          */

   200         CVPbkPhoneNumberMatchStrategy();

   201 

   202         /**

   203          * Initializes the base class. Derived classes must call 

   204          * this in their ConstructL.

   205          * @param aConfig Configuration data for phone number matching.

   206          * @param aContactManager   Contact manager reference,

   207          * @param aObserver Contact find observer reference.

   208          */

   209         void BaseConstructL(

   210                 const TConfig& aConfig,

   211                 CVPbkContactManager& aContactManager,

   212                 MVPbkContactFindObserver& aObserver);

   213         

   214         /**

   215          * Returns the find observer to be used for find operations 

   216          * created in CreateFindOperationLC.

   217          * @return Contact find observer

   218          */

   219         MVPbkContactFindObserver& FindObserver() const;

   220         

   221     private: // Data

   222         friend class CVPbkPhoneNumberMatchStrategyImpl;

   223         /// Own: Pointer to implementation

   224         CVPbkPhoneNumberMatchStrategyImpl* iImpl;

   225     };

   226 

   227 // INLINE FUNCTIONS

   228 inline CVPbkPhoneNumberMatchStrategy::TConfig::TConfig(

   229         TInt aMaxMatchDigits, 

   230         const CVPbkContactStoreUriArray& aUriPriorities,

   231         TVPbkPhoneNumberMatchMode aMatchMode,

   232         TUint32 aMatchFlags) :

   233     iMaxMatchDigits(aMaxMatchDigits),

   234     iUriPriorities(aUriPriorities),

   235     iMatchMode(aMatchMode),

   236     iMatchFlags(aMatchFlags)

   237     {

   238     }

   239 

   240 #endif // CVPBKPHONENUMBERMATCHSTRATEGY_H

   241 

   242 // End of File