--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/contacts_plat/virtual_phonebook_engine_api/inc/CVPbkTopContactManager.h Wed Sep 01 12:29:52 2010 +0100
@@ -0,0 +1,364 @@
+/*
+* Copyright (c) 2005-2007 Nokia Corporation and/or its subsidiary(-ies).
+* All rights reserved.
+* This component and the accompanying materials are made available
+* under the terms of "Eclipse Public License v1.0"
+* which accompanies this distribution, and is available
+* at the URL "http://www.eclipse.org/legal/epl-v10.html".
+*
+* Initial Contributors:
+* Nokia Corporation - initial contribution.
+*
+* Contributors:
+*
+* Description: Top Contact manager
+*
+*/
+
+
+#ifndef VPBKTOPCONTACTMANAGER_H
+#define VPBKTOPCONTACTMANAGER_H
+
+// INCLUDES
+#include <e32base.h>
+
+// FORWARD DECLARATIONS
+class MVPbkContactLink;
+class MVPbkContactLinkArray;
+class CVPbkContactLinkArray;
+class CVPbkContactManager;
+class MVPbkContactViewBase;
+class MVPbkContactOperationBase;
+class MVPbkBaseContact;
+class MVPbkOperationObserver;
+template<typename T>
+class MVPbkOperationResultObserver;
+class MVPbkOperationErrorObserver;
+
+class CVPbkTopContactManagerImpl;
+
+// CLASS DECLARATION
+
+/**
+ * A class for managing Top Contact properties of contacts.
+ * All main operations are asynchronous and accept two observers.
+ * One used to signal completion and return result if necessary.
+ * Another one used to signal an error if operation fails.
+ *
+ * @example
+ * A client that re-orders the existing top contacts in the phone
+ *
+ * class CTopContactManagerClient :
+ * public CActive,
+ * public MVPbkOperationObserver,
+ * public MVPbkOperationErrorObserver,
+ * public MVPbkOperationResultObserver<MVPbkContactViewBase*>
+ * ...
+ *
+ * // MVPbkOperationObserver
+ * void CTopContactManagerClient::VPbkOperationCompleted(
+ * MVPbkContactOperationBase*)
+ * {
+ * FinishCommand( KErrNone );
+ * }
+ *
+ * //From MVPbkOperationErrorObserver
+ * void CTopContactManagerClient::VPbkOperationFailed(
+ * MVPbkContactOperationBase*,
+ * TInt aError )
+ * {
+ * FinishCommand( aError );
+ * }
+ *
+ * // From MVPbkOperationResultObserver
+ * void CTopContactManagerClient::VPbkOperationResultCompleted(
+ * MVPbkContactOperationBase*,
+ * MVPbkContactViewBase* aView )
+ * {
+ * iView = aView;
+ * delete iTopContactOperation;
+ * iTopContactOperation = NULL;
+ * IssueRequest(EShowMoveDlg);
+ * }
+ * // --------------------------------------------------------------------------
+ * // CTopContactManagerClient::RunL
+ * // State Machine using TopContactManager
+ * // --------------------------------------------------------------------------
+ * //
+ * void CTopContactManagerClient::RunL()
+ * {
+ * switch(iState)
+ * {
+ * case ELoadingTopContacts:
+ * {
+ * // This async call will fall into VPbkOperationResultCompleted on success with
+ * // MVPbkContactOperationBase object as a result
+ * // Otherwise, it will fall into VPbkOperationFailed callback
+ * iTopContactOperation = iVPbkTopContactManager->GetTopContactsViewL(
+ * *this,
+ * *this );
+ * break;
+ * }
+ * case EShowMoveDlg:
+ * {
+ * ShowDlgL(); // confirm re-ordering top contacts with user
+ * break;
+ * }
+ * case ESavingTopContacts:
+ * {
+ * // Do re-ordering via Top Manager
+ * // This async call will fall into VPbkOperationResultCompleted on success with
+ * // MVPbkContactOperationBase object as a result
+ * // Otherwise, it will fall into VPbkOperationFailed callback
+ * iTopContactOperation = iVPbkTopContactManager->SetTopOrderL(
+ * *iTopContacts,
+ * *this,
+ * *this );
+ * CleanupStack::PopAndDestroy(); //topContacts
+ * break;
+ * }
+ *
+ * ...
+ * }
+ * }
+ *
+*/
+NONSHARABLE_CLASS( CVPbkTopContactManager ) : public CBase
+ {
+ public:
+
+ /**
+ * Creates the top contact manager.
+ * @param aContactManager Contact manager which already has its stores opened.
+ */
+ IMPORT_C static CVPbkTopContactManager* NewL( CVPbkContactManager& aContactManager );
+
+ /**
+ * Creates the top contact manager passing an already constructed top
+ * contacts view as a parameter. This greatly improves performance of adding
+ * new favorites as the top contact view contsrution can be a heavy operation.
+ *
+ * Note, passing the view doesn't affect the view and links fetching
+ * (e.g. GetTopContactsViewL, GetTopContactLinksL, etc.)
+ *
+ * @param aContactManager Contact manager which already has its stores opened.
+ * @param aTopView top contact view which already has been constructed.
+ */
+ IMPORT_C static CVPbkTopContactManager* NewL(
+ CVPbkContactManager& aContactManager,
+ MVPbkContactViewBase& aTopView);
+
+ /**
+ * Creates the top contact manager.
+ * Holds its own CVPbkContactManager instance.
+ *
+ */
+ IMPORT_C static CVPbkTopContactManager* NewL();
+
+ IMPORT_C ~CVPbkTopContactManager();
+
+ public:
+
+ /**
+ * Get top contacts as contact view.
+ *
+ * If CVPbkTopContactManager was created without giving an external
+ * contact manager as reference, then calling GetTopContactsViewL()
+ * will open the default store if it is not already open.
+ *
+ * @param aResultObserver The observer that gets ready contacts view.
+ * @param aErrorObserver The observer for error notification.
+ */
+ IMPORT_C MVPbkContactOperationBase* GetTopContactsViewL(
+ MVPbkOperationResultObserver<MVPbkContactViewBase*>& aResultObserver,
+ MVPbkOperationErrorObserver& aErrorObserver);
+
+ /**
+ * Get NON-top contacts as contact view.
+ *
+ * If CVPbkTopContactManager was created without giving an external
+ * contact manager as reference, then calling GetNonTopContactsViewL()
+ * will open the default store if it is not already open.
+ *
+ * @param aResultObserver The observer that gets ready contacts view.
+ * @param aErrorObserver The observer for error notification.
+ */
+ IMPORT_C MVPbkContactOperationBase* GetNonTopContactsViewL(
+ MVPbkOperationResultObserver<MVPbkContactViewBase*>& aResultObserver,
+ MVPbkOperationErrorObserver& aErrorObserver );
+
+ /**
+ * Get top contacts as contact link array.
+ *
+ * @param aResultObserver The observer that gets top contact links array.
+ * @param aErrorObserver The observer for error notification.
+ */
+ IMPORT_C MVPbkContactOperationBase* GetTopContactLinksL(
+ MVPbkOperationResultObserver<MVPbkContactLinkArray*>& aResultObserver,
+ MVPbkOperationErrorObserver& aErrorObserver );
+
+ /**
+ * Get NON-top contacts as contact link array.
+ *
+ * @param aResultObserver The observer that gets non-top contact links array.
+ * @param aErrorObserver The observer for error notification.
+ */
+ IMPORT_C MVPbkContactOperationBase* GetNonTopContactLinksL(
+ MVPbkOperationResultObserver<MVPbkContactLinkArray*>& aResultObserver,
+ MVPbkOperationErrorObserver& aErrorObserver );
+
+ /**
+ * Sets a contact as Top Contact. It will become the last top contact.
+ * If a contact manager was not given during
+ * construction, then a contact manager is created and the store which
+ * is defined in the first link will be opened.
+ * The stores used to create aContactLink should be loaded.
+ *
+ * If the contact already is a Top Contact, then the Top order of that
+ * contact is not modified.
+ *
+ * @param aContactLink The contact link.
+ * @param aObserver The observer that gets the completion event.
+ * @param aErrorObserver The observer for error notification.
+ */
+ IMPORT_C MVPbkContactOperationBase* AddToTopL(
+ const MVPbkContactLink& aContactLink,
+ MVPbkOperationObserver& aObserver,
+ MVPbkOperationErrorObserver& aErrorObserver );
+
+ /**
+ * Sets contacts as Top Contacts.
+ * The Top ordering will be according to the arrays order.
+ * If a contact manager was not given during
+ * construction, then a contact manager is created and the store which
+ * is defined in the first link will be opened.
+ * The store used to create aContactLinks should be loaded.
+ *
+ * If the contact already is a Top Contact, then the Top order of that
+ * contact is not modified.
+ *
+ * A zero length array is valid input and produces no changes.
+ * aObserver will be notified asynchronously.
+ *
+ * @param aContactLinks The contact links.
+ * @param aObserver The observer that gets the completion event.
+ * @param aErrorObserver The observer for error notification.
+ */
+ IMPORT_C MVPbkContactOperationBase* AddToTopL(
+ const MVPbkContactLinkArray& aContactLinks,
+ MVPbkOperationObserver& aObserver,
+ MVPbkOperationErrorObserver& aErrorObserver );
+
+ /**
+ * Sets contacts as Top Contacts. Accepts a packed link array.
+ * The Top ordering will be according to the arrays order.
+ * If a contact manager was not given during
+ * construction, then a contact manager is created and the store which
+ * is defined in the first link will be opened.
+ *
+ * If the contact already is a Top Contact, then the Top order of that
+ * contact is not modified.
+ *
+ * A zero length array is valid input and produces no changes.
+ * aObserver will be notified asynchronously.
+ *
+ * @param aPackedLinks A contact link array in packed form.
+ * @param aObserver The observer that gets the completion event.
+ * @param aErrorObserver The observer for error notification.
+ */
+ IMPORT_C MVPbkContactOperationBase* AddToTopL(
+ const TDesC8& aPackedLinks,
+ MVPbkOperationObserver& aObserver,
+ MVPbkOperationErrorObserver& aErrorObserver );
+
+ /**
+ * Removes a contact from the Top.
+ * If a contact manager was not given during
+ * construction, then a contact manager is created and the store which
+ * is defined in the link will be opened.
+ * The stores used to create aContactLink should be loaded.
+ *
+ * @param aContactLink The contact link.
+ * @param aObserver The observer that gets the completion event.
+ * @param aErrorObserver The observer for error notification.
+ */
+ IMPORT_C MVPbkContactOperationBase* RemoveFromTopL(
+ const MVPbkContactLink& aContactLink,
+ MVPbkOperationObserver& aObserver,
+ MVPbkOperationErrorObserver& aErrorObserver );
+
+ /**
+ * Removes contacts from the Top.¨
+ * If a contact manager was not given during
+ * construction, then a contact manager is created and the store which
+ * is defined in the first link will be opened.
+ * The store used to create aContactLinks should be loaded.
+ *
+ * A zero length array is valid input and produces no changes.
+ * aObserver will be notified asynchronously.
+ *
+ * @param aContactLinks The contact links.
+ * @param aObserver The observer that gets the completion event.
+ * @param aErrorObserver The observer for error notification.
+ */
+ IMPORT_C MVPbkContactOperationBase* RemoveFromTopL(
+ const MVPbkContactLinkArray& aContactLinks,
+ MVPbkOperationObserver& aObserver,
+ MVPbkOperationErrorObserver& aErrorObserver );
+
+ /**
+ * Removes contacts from the Top. Accepts a packed link array.
+ * If a contact manager was not given during
+ * construction, then a contact manager is created and the store which
+ * is defined in the first link will be opened.
+ *
+ * A zero length array is valid input and produces no changes.
+ * aObserver will be notified asynchronously.
+ *
+ * @param aPackedLinks A contact link array in packed form.
+ * @param aObserver The observer that gets the completion event.
+ * @param aErrorObserver The observer for error notification.
+ */
+ IMPORT_C MVPbkContactOperationBase* RemoveFromTopL(
+ const TDesC8& aPackedLinks,
+ MVPbkOperationObserver& aObserver,
+ MVPbkOperationErrorObserver& aErrorObserver );
+
+ /**
+ * Sets the new order of top contacts.
+ * Ordering is done within the subset of contacts that were given.
+ * Ignores contacts that are not already Top.
+ * The store used to create aContactLinks should be loaded.
+ *
+ * A zero length array is valid input and produces no changes.
+ * aObserver will be notified asynchronously.
+ *
+ * @param aContactLinks The contacts to be reordered. Order is
+ * determined by the array order, ie. first is top.
+ * @param aObserver The observer that gets the completion event.
+ * @param aErrorObserver The observer for error notification.
+ */
+ IMPORT_C MVPbkContactOperationBase* SetTopOrderL(
+ const MVPbkContactLinkArray& aContactLinks,
+ MVPbkOperationObserver& aObserver,
+ MVPbkOperationErrorObserver& aErrorObserver );
+
+ public: // helper methods related to top contacts.
+
+ /**
+ * Checks whether a contact is top contact.
+ *
+ * @param aContact A contact.
+ * @return ETrue if aContact it top contact, otherwise EFalse
+ */
+ IMPORT_C static TBool IsTopContact( const MVPbkBaseContact& aContact );
+
+ private: // construction
+ CVPbkTopContactManager();
+
+ private: // data
+ CVPbkTopContactManagerImpl* iImpl;
+ };
+
+#endif //VPBKTOPCONTACTMANAGER_H
+//End of file