1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/epoc32/include/app/CVPbkPhoneNumberMatchStrategy.h Wed Mar 31 12:33:34 2010 +0100
1.3 @@ -0,0 +1,242 @@
1.4 +/*
1.5 +* Copyright (c) 2002-2007 Nokia Corporation and/or its subsidiary(-ies).
1.6 +* All rights reserved.
1.7 +* This component and the accompanying materials are made available
1.8 +* under the terms of "Eclipse Public License v1.0"
1.9 +* which accompanies this distribution, and is available
1.10 +* at the URL "http://www.eclipse.org/legal/epl-v10.html".
1.11 +*
1.12 +* Initial Contributors:
1.13 +* Nokia Corporation - initial contribution.
1.14 +*
1.15 +* Contributors:
1.16 +*
1.17 +* Description: A high level class for matching phone numbers from stores.
1.18 +*
1.19 +*/
1.20 +
1.21 +
1.22 +#ifndef CVPBKPHONENUMBERMATCHSTRATEGY_H
1.23 +#define CVPBKPHONENUMBERMATCHSTRATEGY_H
1.24 +
1.25 +// INCLUDE FILES
1.26 +#include <e32base.h>
1.27 +#include <mvpbkcontactfindobserver.h>
1.28 +#include <mvpbkcontactstorelist.h>
1.29 +
1.30 +// FORWARD DECLARATIONS
1.31 +class CVPbkContactManager;
1.32 +class MVPbkContactOperation;
1.33 +class MVPbkContactStore;
1.34 +class CVPbkPhoneNumberMatchStrategyImpl;
1.35 +class CVPbkContactStoreUriArray;
1.36 +
1.37 +/**
1.38 + * Phone number matching strategy. This is the base class of actual
1.39 + * implementations, but instances of the strategies are created using
1.40 + * this classes NewL function. Actual implementation selection is done
1.41 + * based on the given configuration data.
1.42 + */
1.43 +class CVPbkPhoneNumberMatchStrategy : public CBase
1.44 + {
1.45 + public: // Types
1.46 + /**
1.47 + * Phone number matching mode. The mode can be used to
1.48 + * configure the match algorithms operation mode.
1.49 + */
1.50 + enum TVPbkPhoneNumberMatchMode
1.51 + {
1.52 + /**
1.53 + * Performs the search sequentially for each store.
1.54 + */
1.55 + EVPbkSequentialMatch,
1.56 + /**
1.57 + * Performs the search concurrently for each store.
1.58 + */
1.59 + EVPbkParallelMatch
1.60 + };
1.61 +
1.62 + /**
1.63 + * Phone number matching flags. The flags can be used to
1.64 + * configure the phone number matching strategy.
1.65 + */
1.66 + enum TVPbkPhoneNumberMatchFlags
1.67 + {
1.68 + /**
1.69 + * No additional matching flags.
1.70 + */
1.71 + EVPbkMatchFlagsNone = 0x00000000,
1.72 +
1.73 + /**
1.74 + * Quarantees that only contacts with an exact match
1.75 + * are included in the result set. The resulted contact
1.76 + * links are also field links in this case. The link
1.77 + * points to the first field in the contact with exact
1.78 + * match. See RetrieveField in
1.79 + * MVPbkStoreContactFieldCollection.
1.80 + */
1.81 + EVPbkExactMatchFlag = 0x00000001,
1.82 +
1.83 + /**
1.84 + * Stops the search once at least one contact is found.
1.85 + */
1.86 + EVPbkStopOnFirstMatchFlag = 0x00000002,
1.87 +
1.88 + /**
1.89 + * If all matched contacts have the same
1.90 + * first name and last name field values only first
1.91 + * one is returned.
1.92 + */
1.93 + EVPbkDuplicatedContactsMatchFlag = 0x00000004
1.94 + };
1.95 +
1.96 + /**
1.97 + * CVPbkPhoneNumberMatchStrategy configuration parameter class.
1.98 + * This class can be used to configure the phone number find
1.99 + * strategy.
1.100 + */
1.101 + class TConfig
1.102 + {
1.103 + public:
1.104 + /**
1.105 + * Constructor.
1.106 + *
1.107 + * @param aMaxMatchDigits Maximum number of digits
1.108 + * used in matching.
1.109 + * @param aUriPriorities Array of contact store URIs
1.110 + * to define match priority.
1.111 + * @param aMatchMode Matching mode to be used when
1.112 + * searching for matching contacts.
1.113 + * See TVPbkPhoneNumberMatchMode.
1.114 + * @param aMatchFlags Match configuration flags.
1.115 + * See TVPbkPhoneNumberMatchFlags.
1.116 + */
1.117 + inline TConfig(
1.118 + TInt aMaxMatchDigits,
1.119 + const CVPbkContactStoreUriArray& aUriPriorities,
1.120 + TVPbkPhoneNumberMatchMode aMatchMode,
1.121 + TUint32 aMatchFlags);
1.122 +
1.123 + public: // data
1.124 + ///Own: Maximum number of digits used in matching
1.125 + TInt iMaxMatchDigits;
1.126 + ///Ref: Array of contact store URIs to define match priority
1.127 + const CVPbkContactStoreUriArray& iUriPriorities;
1.128 + ///Own: Matching mode to be used when searching for
1.129 + /// matching contacts
1.130 + TVPbkPhoneNumberMatchMode iMatchMode;
1.131 + ///Own: Flags to configure matching process,
1.132 + /// @see TVPbkPhoneNumberMatchFlags
1.133 + TUint32 iMatchFlags;
1.134 + ///Own: Reserved for future extension
1.135 + TAny* iSpare;
1.136 + };
1.137 +
1.138 + public: // Construction & destruction
1.139 + /**
1.140 + * Acts as a factory function for strategy implementation classes
1.141 + * derived from this class. The actual implementation class is
1.142 + * determined from the parameters of this function.
1.143 + *
1.144 + * @param aConfig Configuration data for phone number matching.
1.145 + * @param aContactManager Contact manager to be used in matching.
1.146 + * @param aObserver Observer for the matching operation.
1.147 + * @return Newly created instance of a class derived from this class.
1.148 + */
1.149 + IMPORT_C static CVPbkPhoneNumberMatchStrategy* NewL(
1.150 + const TConfig& aConfig,
1.151 + CVPbkContactManager& aContactManager,
1.152 + MVPbkContactFindObserver& aObserver);
1.153 +
1.154 + /**
1.155 + * Destructor.
1.156 + */
1.157 + ~CVPbkPhoneNumberMatchStrategy();
1.158 +
1.159 + public: // Interface
1.160 + /**
1.161 + * Tries to find matches for given phone number from the stores
1.162 + * that were specified in the configuration data. This is
1.163 + * asynchronous operation and the observer will be called
1.164 + * back when this operation completes.
1.165 + *
1.166 + * @param aPhoneNumber Phone number to match.
1.167 + */
1.168 + IMPORT_C void MatchL(const TDesC& aPhoneNumber);
1.169 +
1.170 + protected: // Interface for derived classes
1.171 + /**
1.172 + * Returns maximum number of digits used in matching.
1.173 + * @return Maximum number of digits used in matching.
1.174 + */
1.175 + TInt MaxMatchDigits() const;
1.176 +
1.177 + /**
1.178 + * Returns array of stores that are used in matching.
1.179 + * @return Array of stores that are used in matching.
1.180 + */
1.181 + TArray<MVPbkContactStore*> StoresToMatch() const;
1.182 +
1.183 + private: // Interface for derived classes to implement
1.184 + /**
1.185 + * Called from MatchL to indicate derived classes that
1.186 + * matching is about to start.
1.187 + */
1.188 + virtual void InitMatchingL() =0;
1.189 +
1.190 + /**
1.191 + * Creates a new find operation for the next finding step.
1.192 + *
1.193 + * @param aPhoneNumber Phone number to match.
1.194 + * @return Find operation.
1.195 + */
1.196 + virtual MVPbkContactOperation* CreateFindOperationLC(
1.197 + const TDesC& aPhoneNumber) =0;
1.198 +
1.199 + protected: // Implementation
1.200 + /**
1.201 + * Constructor.
1.202 + */
1.203 + CVPbkPhoneNumberMatchStrategy();
1.204 +
1.205 + /**
1.206 + * Initializes the base class. Derived classes must call
1.207 + * this in their ConstructL.
1.208 + * @param aConfig Configuration data for phone number matching.
1.209 + * @param aContactManager Contact manager reference,
1.210 + * @param aObserver Contact find observer reference.
1.211 + */
1.212 + void BaseConstructL(
1.213 + const TConfig& aConfig,
1.214 + CVPbkContactManager& aContactManager,
1.215 + MVPbkContactFindObserver& aObserver);
1.216 +
1.217 + /**
1.218 + * Returns the find observer to be used for find operations
1.219 + * created in CreateFindOperationLC.
1.220 + * @return Contact find observer
1.221 + */
1.222 + MVPbkContactFindObserver& FindObserver() const;
1.223 +
1.224 + private: // Data
1.225 + friend class CVPbkPhoneNumberMatchStrategyImpl;
1.226 + /// Own: Pointer to implementation
1.227 + CVPbkPhoneNumberMatchStrategyImpl* iImpl;
1.228 + };
1.229 +
1.230 +// INLINE FUNCTIONS
1.231 +inline CVPbkPhoneNumberMatchStrategy::TConfig::TConfig(
1.232 + TInt aMaxMatchDigits,
1.233 + const CVPbkContactStoreUriArray& aUriPriorities,
1.234 + TVPbkPhoneNumberMatchMode aMatchMode,
1.235 + TUint32 aMatchFlags) :
1.236 + iMaxMatchDigits(aMaxMatchDigits),
1.237 + iUriPriorities(aUriPriorities),
1.238 + iMatchMode(aMatchMode),
1.239 + iMatchFlags(aMatchFlags)
1.240 + {
1.241 + }
1.242 +
1.243 +#endif // CVPBKPHONENUMBERMATCHSTRATEGY_H
1.244 +
1.245 +// End of File