/*

* 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