1 /*

     2 * Copyright (c) 2005-2007 Nokia Corporation and/or its subsidiary(-ies).

     3 * All rights reserved.

     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".

     8 *

     9 * Initial Contributors:

    10 * Nokia Corporation - initial contribution.

    11 *

    12 * Contributors:

    13 *

    14 * Description:  Top Contact manager

    15 *

    16 */

    17 

    18 

    19 #ifndef VPBKTOPCONTACTMANAGER_H

    20 #define VPBKTOPCONTACTMANAGER_H

    21 

    22 // INCLUDES

    23 #include <e32base.h>

    24 

    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;

    34 template<typename T>

    35 class MVPbkOperationResultObserver;

    36 class MVPbkOperationErrorObserver;

    37 

    38 class CVPbkTopContactManagerImpl; 

    39 

    40 // CLASS DECLARATION

    41 

    42 /**

    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.

    47  *

    48  * @example

    49  * A client that re-orders the existing top contacts in the phone

    50  *

    51  * class CTopContactManagerClient :

    52  *   public CActive,

    53  *   public MVPbkOperationObserver,   

    54  *   public MVPbkOperationErrorObserver,

    55  *   public MVPbkOperationResultObserver<MVPbkContactViewBase*>

    56  *	  ...

    57  *

    58  * // MVPbkOperationObserver	  

    59  * void CTopContactManagerClient::VPbkOperationCompleted(

    60  *       MVPbkContactOperationBase*)

    61  *   {

    62  *   FinishCommand( KErrNone );

    63  *   }

    64  *

    65  * //From MVPbkOperationErrorObserver

    66  * void CTopContactManagerClient::VPbkOperationFailed(

    67  *       MVPbkContactOperationBase*,

    68  *       TInt aError )

    69  *   {

    70  *   FinishCommand( aError );

    71  *   }

    72  *

    73  * // From MVPbkOperationResultObserver

    74  * void CTopContactManagerClient::VPbkOperationResultCompleted(

    75  *       MVPbkContactOperationBase*,

    76  *       MVPbkContactViewBase* aView )

    77  *   {

    78  *   iView = aView;

    79  *   delete iTopContactOperation;

    80  *   iTopContactOperation = NULL;

    81  *   IssueRequest(EShowMoveDlg);

    82  *   }

    83  *  // --------------------------------------------------------------------------

    84  * // CTopContactManagerClient::RunL

    85  * // State Machine using TopContactManager

    86  * // --------------------------------------------------------------------------

    87  * //

    88  * void CTopContactManagerClient::RunL()

    89  *   {

    90  *   switch(iState)

    91  *   	{

    92  *   	case ELoadingTopContacts:

    93  *   		{

    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(

    98  *   		        *this,

    99  *   		        *this );

   100  *   		break;

   101  *   		}

   102  *   	case EShowMoveDlg:

   103  *   		{

   104  *   		ShowDlgL(); // confirm re-ordering top contacts with user

   105  *   		break;

   106  *   		}

   107  *   	case ESavingTopContacts:

   108  *   		{

   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(

   114  *   		        *iTopContacts,

   115  *   		        *this,

   116  *   		        *this );

   117  *   		CleanupStack::PopAndDestroy(); //topContacts

   118  *   		break;

   119  *   		}

   120  *	  

   121  *     ...

   122  *    }

   123  * }     

   124  *

   125 */

   126 NONSHARABLE_CLASS( CVPbkTopContactManager ) : public CBase

   127     {

   128     public:

   129 

   130     	/**

   131          * Creates the top contact manager.

   132     	 * @param aContactManager Contact manager which already has its stores opened.

   133     	 */

   134         IMPORT_C static CVPbkTopContactManager* NewL( CVPbkContactManager& aContactManager );

   135 

   136         /**

   137          * Creates the top contact manager passing an already constructed top

   138          * contacts view as a parameter. This greatly improves performance of adding 

   139          * new favorites as the top contact view contsrution can be a heavy operation.

   140          * 

   141          * Note, passing the view doesn't affect the view and links fetching 

   142          * (e.g. GetTopContactsViewL, GetTopContactLinksL, etc.)

   143          * 

   144          * @param aContactManager Contact manager which already has its stores opened.

   145          * @param aTopView top contact view which already has been constructed.

   146          */

   147         IMPORT_C static CVPbkTopContactManager* NewL(

   148                 CVPbkContactManager& aContactManager,

   149                 MVPbkContactViewBase& aTopView);

   150         

   151         /**

   152          * Creates the top contact manager.

   153          * Holds its own CVPbkContactManager instance.

   154          * 

   155          */

   156         IMPORT_C static CVPbkTopContactManager* NewL();

   157         

   158         IMPORT_C ~CVPbkTopContactManager();

   159 

   160     public:

   161         

   162         /**

   163          * Get top contacts as contact view.

   164          * 

   165          * If CVPbkTopContactManager was created without giving an external

   166          * contact manager as reference, then calling GetTopContactsViewL()

   167          * will open the default store if it is not already open.

   168          *

   169          * @param aResultObserver The observer that gets ready contacts view.

   170          * @param aErrorObserver The observer for error notification. 

   171          */

   172         IMPORT_C MVPbkContactOperationBase* GetTopContactsViewL(

   173                 MVPbkOperationResultObserver<MVPbkContactViewBase*>& aResultObserver,

   174                 MVPbkOperationErrorObserver& aErrorObserver);

   175 

   176         /**

   177          * Get NON-top contacts as contact view.

   178          * 

   179          * If CVPbkTopContactManager was created without giving an external

   180          * contact manager as reference, then calling GetNonTopContactsViewL()

   181          * will open the default store if it is not already open.

   182          *

   183          * @param aResultObserver The observer that gets ready contacts view.

   184          * @param aErrorObserver The observer for error notification. 

   185          */

   186         IMPORT_C MVPbkContactOperationBase* GetNonTopContactsViewL(

   187                 MVPbkOperationResultObserver<MVPbkContactViewBase*>& aResultObserver,

   188                 MVPbkOperationErrorObserver& aErrorObserver );

   189 

   190         /**

   191          * Get top contacts as contact link array.

   192          * 

   193          * @param aResultObserver The observer that gets top contact links array.

   194          * @param aErrorObserver The observer for error notification. 

   195          */        

   196         IMPORT_C MVPbkContactOperationBase* GetTopContactLinksL(

   197                 MVPbkOperationResultObserver<MVPbkContactLinkArray*>&  aResultObserver,

   198                 MVPbkOperationErrorObserver& aErrorObserver );

   199 

   200         /**

   201          * Get NON-top contacts as contact link array.

   202          * 

   203          * @param aResultObserver The observer that gets non-top contact links array.

   204          * @param aErrorObserver The observer for error notification. 

   205          */        

   206         IMPORT_C MVPbkContactOperationBase* GetNonTopContactLinksL(

   207                 MVPbkOperationResultObserver<MVPbkContactLinkArray*>&  aResultObserver,

   208                 MVPbkOperationErrorObserver& aErrorObserver );

   209         

   210         /**

   211          * Sets a contact as Top Contact. It will become the last top contact.

   212          * If a contact manager was not given during

   213          * construction, then a contact manager is created and the store which

   214          * is defined in the first link will be opened.

   215          * The stores used to create aContactLink should be loaded.

   216          * 

   217          * If the contact already is a Top Contact, then the Top order of that

   218          * contact is not modified. 

   219          * 

   220          * @param aContactLink The contact link.

   221          * @param aObserver The observer that gets the completion event.

   222          * @param aErrorObserver The observer for error notification. 

   223          */

   224         IMPORT_C MVPbkContactOperationBase* AddToTopL(

   225                 const MVPbkContactLink& aContactLink,

   226                 MVPbkOperationObserver& aObserver,

   227                 MVPbkOperationErrorObserver& aErrorObserver );

   228 

   229         /**

   230          * Sets contacts as Top Contacts.

   231          * The Top ordering will be according to the arrays order.

   232          * If a contact manager was not given during

   233          * construction, then a contact manager is created and the store which

   234          * is defined in the first link will be opened.

   235          * The store used to create aContactLinks should be loaded.

   236          * 

   237          * If the contact already is a Top Contact, then the Top order of that

   238          * contact is not modified.

   239          * 

   240          * A zero length array is valid input and produces no changes. 

   241          * aObserver will be notified asynchronously.

   242          *

   243          * @param aContactLinks The contact links.

   244          * @param aObserver The observer that gets the completion event.

   245          * @param aErrorObserver The observer for error notification. 

   246          */

   247         IMPORT_C MVPbkContactOperationBase* AddToTopL(

   248                 const MVPbkContactLinkArray& aContactLinks,

   249                 MVPbkOperationObserver& aObserver,

   250                 MVPbkOperationErrorObserver& aErrorObserver );

   251 

   252         /**

   253          * Sets contacts as Top Contacts. Accepts a packed link array.

   254          * The Top ordering will be according to the arrays order.

   255          * If a contact manager was not given during

   256          * construction, then a contact manager is created and the store which

   257          * is defined in the first link will be opened.

   258          * 

   259          * If the contact already is a Top Contact, then the Top order of that

   260          * contact is not modified.

   261          * 

   262          * A zero length array is valid input and produces no changes. 

   263          * aObserver will be notified asynchronously.

   264          *

   265          * @param aPackedLinks A contact link array in packed form.

   266          * @param aObserver The observer that gets the completion event.

   267          * @param aErrorObserver The observer for error notification. 

   268          */

   269         IMPORT_C MVPbkContactOperationBase* AddToTopL(

   270                 const TDesC8& aPackedLinks,

   271                 MVPbkOperationObserver& aObserver,

   272                 MVPbkOperationErrorObserver& aErrorObserver );

   273 

   274         /**

   275          * Removes a contact from the Top.

   276          * If a contact manager was not given during

   277          * construction, then a contact manager is created and the store which

   278          * is defined in the link will be opened.

   279          * The stores used to create aContactLink should be loaded.

   280          * 

   281          * @param aContactLink The contact link.

   282          * @param aObserver The observer that gets the completion event.

   283          * @param aErrorObserver The observer for error notification. 

   284          */

   285         IMPORT_C MVPbkContactOperationBase* RemoveFromTopL(

   286         	const MVPbkContactLink& aContactLink,

   287         	MVPbkOperationObserver& aObserver,

   288         	MVPbkOperationErrorObserver& aErrorObserver );

   289 

   290         /**

   291          * Removes contacts from the Top.¨

   292          * If a contact manager was not given during

   293          * construction, then a contact manager is created and the store which

   294          * is defined in the first link will be opened.

   295          * The store used to create aContactLinks should be loaded.

   296          * 

   297          * A zero length array is valid input and produces no changes. 

   298          * aObserver will be notified asynchronously.

   299          *

   300          * @param aContactLinks The contact links.

   301          * @param aObserver The observer that gets the completion event.

   302          * @param aErrorObserver The observer for error notification. 

   303          */

   304         IMPORT_C MVPbkContactOperationBase* RemoveFromTopL(

   305         	const MVPbkContactLinkArray& aContactLinks,

   306         	MVPbkOperationObserver& aObserver,

   307         	MVPbkOperationErrorObserver& aErrorObserver );

   308 

   309         /**

   310          * Removes contacts from the Top. Accepts a packed link array.

   311          * If a contact manager was not given during

   312          * construction, then a contact manager is created and the store which

   313          * is defined in the first link will be opened.

   314          * 

   315          * A zero length array is valid input and produces no changes. 

   316          * aObserver will be notified asynchronously.

   317          *

   318          * @param aPackedLinks A contact link array in packed form.

   319          * @param aObserver The observer that gets the completion event.

   320          * @param aErrorObserver The observer for error notification. 

   321          */

   322         IMPORT_C MVPbkContactOperationBase* RemoveFromTopL(

   323         	const TDesC8& aPackedLinks,

   324         	MVPbkOperationObserver& aObserver,

   325         	MVPbkOperationErrorObserver& aErrorObserver );

   326 

   327         /**

   328          * Sets the new order of top contacts.

   329          * Ordering is done within the subset of contacts that were given.

   330          * Ignores contacts that are not already Top.

   331          * The store used to create aContactLinks should be loaded.

   332          * 

   333          * A zero length array is valid input and produces no changes. 

   334          * aObserver will be notified asynchronously.

   335          * 

   336          * @param aContactLinks The contacts to be reordered. Order is

   337          * 		  determined by the array order, ie. first is top.

   338          * @param aObserver The observer that gets the completion event.

   339          * @param aErrorObserver The observer for error notification. 

   340          */

   341         IMPORT_C MVPbkContactOperationBase* SetTopOrderL(

   342 	    	const MVPbkContactLinkArray& aContactLinks,

   343 	    	MVPbkOperationObserver& aObserver,

   344 	    	MVPbkOperationErrorObserver& aErrorObserver );

   345 

   346     public: // helper methods related to top contacts.

   347 

   348         /**

   349          * Checks whether a contact is top contact.

   350          *

   351          * @param aContact A contact.

   352          * @return ETrue if aContact it top contact, otherwise EFalse 

   353          */

   354         IMPORT_C static TBool IsTopContact( const MVPbkBaseContact& aContact );

   355 

   356     private: // construction

   357         CVPbkTopContactManager();

   358 

   359     private: // data

   360         CVPbkTopContactManagerImpl* iImpl;

   361     };

   362 

   363 #endif //VPBKTOPCONTACTMANAGER_H

   364 //End of file