2 * Copyright (c) 2005-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: Top Contact manager
19 #ifndef VPBKTOPCONTACTMANAGER_H
20 #define VPBKTOPCONTACTMANAGER_H
25 // FORWARD DECLARATIONS
26 class MVPbkContactLink;
27 class MVPbkContactLinkArray;
28 class CVPbkContactLinkArray;
29 class CVPbkContactManager;
30 class MVPbkContactViewBase;
31 class MVPbkContactOperationBase;
32 class MVPbkBaseContact;
33 class MVPbkOperationObserver;
35 class MVPbkOperationResultObserver;
36 class MVPbkOperationErrorObserver;
38 class CVPbkTopContactManagerImpl;
43 * A class for managing Top Contact properties of contacts.
44 * All main operations are asynchronous and accept two observers.
45 * One used to signal completion and return result if necessary.
46 * Another one used to signal an error if operation fails.
49 * A client that re-orders the existing top contacts in the phone
51 * class CTopContactManagerClient :
53 * public MVPbkOperationObserver,
54 * public MVPbkOperationErrorObserver,
55 * public MVPbkOperationResultObserver<MVPbkContactViewBase*>
58 * // MVPbkOperationObserver
59 * void CTopContactManagerClient::VPbkOperationCompleted(
60 * MVPbkContactOperationBase*)
62 * FinishCommand( KErrNone );
65 * //From MVPbkOperationErrorObserver
66 * void CTopContactManagerClient::VPbkOperationFailed(
67 * MVPbkContactOperationBase*,
70 * FinishCommand( aError );
73 * // From MVPbkOperationResultObserver
74 * void CTopContactManagerClient::VPbkOperationResultCompleted(
75 * MVPbkContactOperationBase*,
76 * MVPbkContactViewBase* aView )
79 * delete iTopContactOperation;
80 * iTopContactOperation = NULL;
81 * IssueRequest(EShowMoveDlg);
83 * // --------------------------------------------------------------------------
84 * // CTopContactManagerClient::RunL
85 * // State Machine using TopContactManager
86 * // --------------------------------------------------------------------------
88 * void CTopContactManagerClient::RunL()
92 * case ELoadingTopContacts:
94 * // This async call will fall into VPbkOperationResultCompleted on success with
95 * // MVPbkContactOperationBase object as a result
96 * // Otherwise, it will fall into VPbkOperationFailed callback
97 * iTopContactOperation = iVPbkTopContactManager->GetTopContactsViewL(
104 * ShowDlgL(); // confirm re-ordering top contacts with user
107 * case ESavingTopContacts:
109 * // Do re-ordering via Top Manager
110 * // This async call will fall into VPbkOperationResultCompleted on success with
111 * // MVPbkContactOperationBase object as a result
112 * // Otherwise, it will fall into VPbkOperationFailed callback
113 * iTopContactOperation = iVPbkTopContactManager->SetTopOrderL(
117 * CleanupStack::PopAndDestroy(); //topContacts
126 NONSHARABLE_CLASS( CVPbkTopContactManager ) : public CBase
131 * Creates the top contact manager.
132 * @param aContactManager Contact manager which already has its stores opened.
134 IMPORT_C static CVPbkTopContactManager* NewL( CVPbkContactManager& aContactManager );
137 * Creates the top contact manager.
138 * Holds its own CVPbkContactManager instance.
141 IMPORT_C static CVPbkTopContactManager* NewL();
143 IMPORT_C ~CVPbkTopContactManager();
148 * Get top contacts as contact view.
150 * If CVPbkTopContactManager was created without giving an external
151 * contact manager as reference, then calling GetTopContactsViewL()
152 * will open the default store if it is not already open.
154 * @param aResultObserver The observer that gets ready contacts view.
155 * @param aErrorObserver The observer for error notification.
157 IMPORT_C MVPbkContactOperationBase* GetTopContactsViewL(
158 MVPbkOperationResultObserver<MVPbkContactViewBase*>& aResultObserver,
159 MVPbkOperationErrorObserver& aErrorObserver);
162 * Get NON-top contacts as contact view.
164 * If CVPbkTopContactManager was created without giving an external
165 * contact manager as reference, then calling GetNonTopContactsViewL()
166 * will open the default store if it is not already open.
168 * @param aResultObserver The observer that gets ready contacts view.
169 * @param aErrorObserver The observer for error notification.
171 IMPORT_C MVPbkContactOperationBase* GetNonTopContactsViewL(
172 MVPbkOperationResultObserver<MVPbkContactViewBase*>& aResultObserver,
173 MVPbkOperationErrorObserver& aErrorObserver );
176 * Get top contacts as contact link array.
178 * @param aResultObserver The observer that gets top contact links array.
179 * @param aErrorObserver The observer for error notification.
181 IMPORT_C MVPbkContactOperationBase* GetTopContactLinksL(
182 MVPbkOperationResultObserver<MVPbkContactLinkArray*>& aResultObserver,
183 MVPbkOperationErrorObserver& aErrorObserver );
186 * Get NON-top contacts as contact link array.
188 * @param aResultObserver The observer that gets non-top contact links array.
189 * @param aErrorObserver The observer for error notification.
191 IMPORT_C MVPbkContactOperationBase* GetNonTopContactLinksL(
192 MVPbkOperationResultObserver<MVPbkContactLinkArray*>& aResultObserver,
193 MVPbkOperationErrorObserver& aErrorObserver );
196 * Sets a contact as Top Contact. It will become the last top contact.
197 * If a contact manager was not given during
198 * construction, then a contact manager is created and the store which
199 * is defined in the first link will be opened.
200 * The stores used to create aContactLink should be loaded.
202 * If the contact already is a Top Contact, then the Top order of that
203 * contact is not modified.
205 * @param aContactLink The contact link.
206 * @param aObserver The observer that gets the completion event.
207 * @param aErrorObserver The observer for error notification.
209 IMPORT_C MVPbkContactOperationBase* AddToTopL(
210 const MVPbkContactLink& aContactLink,
211 MVPbkOperationObserver& aObserver,
212 MVPbkOperationErrorObserver& aErrorObserver );
215 * Sets contacts as Top Contacts.
216 * The Top ordering will be according to the arrays order.
217 * If a contact manager was not given during
218 * construction, then a contact manager is created and the store which
219 * is defined in the first link will be opened.
220 * The store used to create aContactLinks should be loaded.
222 * If the contact already is a Top Contact, then the Top order of that
223 * contact is not modified.
225 * A zero length array is valid input and produces no changes.
226 * aObserver will be notified asynchronously.
228 * @param aContactLinks The contact links.
229 * @param aObserver The observer that gets the completion event.
230 * @param aErrorObserver The observer for error notification.
232 IMPORT_C MVPbkContactOperationBase* AddToTopL(
233 const MVPbkContactLinkArray& aContactLinks,
234 MVPbkOperationObserver& aObserver,
235 MVPbkOperationErrorObserver& aErrorObserver );
238 * Sets contacts as Top Contacts. Accepts a packed link array.
239 * The Top ordering will be according to the arrays order.
240 * If a contact manager was not given during
241 * construction, then a contact manager is created and the store which
242 * is defined in the first link will be opened.
244 * If the contact already is a Top Contact, then the Top order of that
245 * contact is not modified.
247 * A zero length array is valid input and produces no changes.
248 * aObserver will be notified asynchronously.
250 * @param aPackedLinks A contact link array in packed form.
251 * @param aObserver The observer that gets the completion event.
252 * @param aErrorObserver The observer for error notification.
254 IMPORT_C MVPbkContactOperationBase* AddToTopL(
255 const TDesC8& aPackedLinks,
256 MVPbkOperationObserver& aObserver,
257 MVPbkOperationErrorObserver& aErrorObserver );
260 * Removes a contact from the Top.
261 * If a contact manager was not given during
262 * construction, then a contact manager is created and the store which
263 * is defined in the link will be opened.
264 * The stores used to create aContactLink should be loaded.
266 * @param aContactLink The contact link.
267 * @param aObserver The observer that gets the completion event.
268 * @param aErrorObserver The observer for error notification.
270 IMPORT_C MVPbkContactOperationBase* RemoveFromTopL(
271 const MVPbkContactLink& aContactLink,
272 MVPbkOperationObserver& aObserver,
273 MVPbkOperationErrorObserver& aErrorObserver );
276 * Removes contacts from the Top.¨
277 * If a contact manager was not given during
278 * construction, then a contact manager is created and the store which
279 * is defined in the first link will be opened.
280 * The store used to create aContactLinks should be loaded.
282 * A zero length array is valid input and produces no changes.
283 * aObserver will be notified asynchronously.
285 * @param aContactLinks The contact links.
286 * @param aObserver The observer that gets the completion event.
287 * @param aErrorObserver The observer for error notification.
289 IMPORT_C MVPbkContactOperationBase* RemoveFromTopL(
290 const MVPbkContactLinkArray& aContactLinks,
291 MVPbkOperationObserver& aObserver,
292 MVPbkOperationErrorObserver& aErrorObserver );
295 * Removes contacts from the Top. Accepts a packed link array.
296 * If a contact manager was not given during
297 * construction, then a contact manager is created and the store which
298 * is defined in the first link will be opened.
300 * A zero length array is valid input and produces no changes.
301 * aObserver will be notified asynchronously.
303 * @param aPackedLinks A contact link array in packed form.
304 * @param aObserver The observer that gets the completion event.
305 * @param aErrorObserver The observer for error notification.
307 IMPORT_C MVPbkContactOperationBase* RemoveFromTopL(
308 const TDesC8& aPackedLinks,
309 MVPbkOperationObserver& aObserver,
310 MVPbkOperationErrorObserver& aErrorObserver );
313 * Sets the new order of top contacts.
314 * Ordering is done within the subset of contacts that were given.
315 * Ignores contacts that are not already Top.
316 * The store used to create aContactLinks should be loaded.
318 * A zero length array is valid input and produces no changes.
319 * aObserver will be notified asynchronously.
321 * @param aContactLinks The contacts to be reordered. Order is
322 * determined by the array order, ie. first is top.
323 * @param aObserver The observer that gets the completion event.
324 * @param aErrorObserver The observer for error notification.
326 IMPORT_C MVPbkContactOperationBase* SetTopOrderL(
327 const MVPbkContactLinkArray& aContactLinks,
328 MVPbkOperationObserver& aObserver,
329 MVPbkOperationErrorObserver& aErrorObserver );
331 public: // helper methods related to top contacts.
334 * Checks whether a contact is top contact.
336 * @param aContact A contact.
337 * @return ETrue if aContact it top contact, otherwise EFalse
339 IMPORT_C static TBool IsTopContact( const MVPbkBaseContact& aContact );
341 private: // construction
342 CVPbkTopContactManager();
345 CVPbkTopContactManagerImpl* iImpl;
348 #endif //VPBKTOPCONTACTMANAGER_H