epoc32/include/app/CVPbkPhoneNumberMatchStrategy.h
author William Roberts <williamr@symbian.org>
Wed, 31 Mar 2010 12:33:34 +0100
branchSymbian3
changeset 4 837f303aceeb
permissions -rw-r--r--
Current Symbian^3 public API header files (from PDK 3.0.h)
This is the epoc32/include tree with the "platform" subtrees removed, and
all but a selected few mbg and rsg files removed.
     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