2 * Copyright (c) 2002-2007 Nokia Corporation and/or its subsidiary(-ies).
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".
9 * Initial Contributors:
10 * Nokia Corporation - initial contribution.
14 * Description: A high level class for matching phone numbers from stores.
19 #ifndef CVPBKPHONENUMBERMATCHSTRATEGY_H
20 #define CVPBKPHONENUMBERMATCHSTRATEGY_H
24 #include <mvpbkcontactfindobserver.h>
25 #include <mvpbkcontactstorelist.h>
27 // FORWARD DECLARATIONS
28 class CVPbkContactManager;
29 class MVPbkContactOperation;
30 class MVPbkContactStore;
31 class CVPbkPhoneNumberMatchStrategyImpl;
32 class CVPbkContactStoreUriArray;
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.
40 class CVPbkPhoneNumberMatchStrategy : public CBase
44 * Phone number matching mode. The mode can be used to
45 * configure the match algorithms operation mode.
47 enum TVPbkPhoneNumberMatchMode
50 * Performs the search sequentially for each store.
54 * Performs the search concurrently for each store.
60 * Phone number matching flags. The flags can be used to
61 * configure the phone number matching strategy.
63 enum TVPbkPhoneNumberMatchFlags
66 * No additional matching flags.
68 EVPbkMatchFlagsNone = 0x00000000,
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.
78 EVPbkExactMatchFlag = 0x00000001,
81 * Stops the search once at least one contact is found.
83 EVPbkStopOnFirstMatchFlag = 0x00000002,
86 * If all matched contacts have the same
87 * first name and last name field values only first
90 EVPbkDuplicatedContactsMatchFlag = 0x00000004
94 * CVPbkPhoneNumberMatchStrategy configuration parameter class.
95 * This class can be used to configure the phone number find
104 * @param aMaxMatchDigits Maximum number of digits
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.
115 TInt aMaxMatchDigits,
116 const CVPbkContactStoreUriArray& aUriPriorities,
117 TVPbkPhoneNumberMatchMode aMatchMode,
118 TUint32 aMatchFlags);
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
131 ///Own: Reserved for future extension
135 public: // Construction & destruction
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.
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.
146 IMPORT_C static CVPbkPhoneNumberMatchStrategy* NewL(
147 const TConfig& aConfig,
148 CVPbkContactManager& aContactManager,
149 MVPbkContactFindObserver& aObserver);
154 ~CVPbkPhoneNumberMatchStrategy();
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.
163 * @param aPhoneNumber Phone number to match.
165 IMPORT_C void MatchL(const TDesC& aPhoneNumber);
167 protected: // Interface for derived classes
169 * Returns maximum number of digits used in matching.
170 * @return Maximum number of digits used in matching.
172 TInt MaxMatchDigits() const;
175 * Returns array of stores that are used in matching.
176 * @return Array of stores that are used in matching.
178 TArray<MVPbkContactStore*> StoresToMatch() const;
180 private: // Interface for derived classes to implement
182 * Called from MatchL to indicate derived classes that
183 * matching is about to start.
185 virtual void InitMatchingL() =0;
188 * Creates a new find operation for the next finding step.
190 * @param aPhoneNumber Phone number to match.
191 * @return Find operation.
193 virtual MVPbkContactOperation* CreateFindOperationLC(
194 const TDesC& aPhoneNumber) =0;
196 protected: // Implementation
200 CVPbkPhoneNumberMatchStrategy();
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.
210 const TConfig& aConfig,
211 CVPbkContactManager& aContactManager,
212 MVPbkContactFindObserver& aObserver);
215 * Returns the find observer to be used for find operations
216 * created in CreateFindOperationLC.
217 * @return Contact find observer
219 MVPbkContactFindObserver& FindObserver() const;
222 friend class CVPbkPhoneNumberMatchStrategyImpl;
223 /// Own: Pointer to implementation
224 CVPbkPhoneNumberMatchStrategyImpl* iImpl;
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)
240 #endif // CVPBKPHONENUMBERMATCHSTRATEGY_H