epoc32/include/app/CVPbkTopContactManager.h
author William Roberts <williamr@symbian.org>
Wed, 31 Mar 2010 12:33:34 +0100
branchSymbian3
changeset 4 837f303aceeb
permissions -rw-r--r--
Current Symbian^3 public API header files (from PDK 3.0.h)
This is the epoc32/include tree with the "platform" subtrees removed, and
all but a selected few mbg and rsg files removed.
     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.
   138          * Holds its own CVPbkContactManager instance.
   139          * 
   140          */
   141         IMPORT_C static CVPbkTopContactManager* NewL();
   142         
   143         IMPORT_C ~CVPbkTopContactManager();
   144 
   145     public:
   146         
   147         /**
   148          * Get top contacts as contact view.
   149          * 
   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.
   153          *
   154          * @param aResultObserver The observer that gets ready contacts view.
   155          * @param aErrorObserver The observer for error notification. 
   156          */
   157         IMPORT_C MVPbkContactOperationBase* GetTopContactsViewL(
   158                 MVPbkOperationResultObserver<MVPbkContactViewBase*>& aResultObserver,
   159                 MVPbkOperationErrorObserver& aErrorObserver);
   160 
   161         /**
   162          * Get NON-top contacts as contact view.
   163          * 
   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.
   167          *
   168          * @param aResultObserver The observer that gets ready contacts view.
   169          * @param aErrorObserver The observer for error notification. 
   170          */
   171         IMPORT_C MVPbkContactOperationBase* GetNonTopContactsViewL(
   172                 MVPbkOperationResultObserver<MVPbkContactViewBase*>& aResultObserver,
   173                 MVPbkOperationErrorObserver& aErrorObserver );
   174 
   175         /**
   176          * Get top contacts as contact link array.
   177          * 
   178          * @param aResultObserver The observer that gets top contact links array.
   179          * @param aErrorObserver The observer for error notification. 
   180          */        
   181         IMPORT_C MVPbkContactOperationBase* GetTopContactLinksL(
   182                 MVPbkOperationResultObserver<MVPbkContactLinkArray*>&  aResultObserver,
   183                 MVPbkOperationErrorObserver& aErrorObserver );
   184 
   185         /**
   186          * Get NON-top contacts as contact link array.
   187          * 
   188          * @param aResultObserver The observer that gets non-top contact links array.
   189          * @param aErrorObserver The observer for error notification. 
   190          */        
   191         IMPORT_C MVPbkContactOperationBase* GetNonTopContactLinksL(
   192                 MVPbkOperationResultObserver<MVPbkContactLinkArray*>&  aResultObserver,
   193                 MVPbkOperationErrorObserver& aErrorObserver );
   194         
   195         /**
   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.
   201          * 
   202          * If the contact already is a Top Contact, then the Top order of that
   203          * contact is not modified. 
   204          * 
   205          * @param aContactLink The contact link.
   206          * @param aObserver The observer that gets the completion event.
   207          * @param aErrorObserver The observer for error notification. 
   208          */
   209         IMPORT_C MVPbkContactOperationBase* AddToTopL(
   210                 const MVPbkContactLink& aContactLink,
   211                 MVPbkOperationObserver& aObserver,
   212                 MVPbkOperationErrorObserver& aErrorObserver );
   213 
   214         /**
   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.
   221          * 
   222          * If the contact already is a Top Contact, then the Top order of that
   223          * contact is not modified.
   224          * 
   225          * A zero length array is valid input and produces no changes. 
   226          * aObserver will be notified asynchronously.
   227          *
   228          * @param aContactLinks The contact links.
   229          * @param aObserver The observer that gets the completion event.
   230          * @param aErrorObserver The observer for error notification. 
   231          */
   232         IMPORT_C MVPbkContactOperationBase* AddToTopL(
   233                 const MVPbkContactLinkArray& aContactLinks,
   234                 MVPbkOperationObserver& aObserver,
   235                 MVPbkOperationErrorObserver& aErrorObserver );
   236 
   237         /**
   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.
   243          * 
   244          * If the contact already is a Top Contact, then the Top order of that
   245          * contact is not modified.
   246          * 
   247          * A zero length array is valid input and produces no changes. 
   248          * aObserver will be notified asynchronously.
   249          *
   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. 
   253          */
   254         IMPORT_C MVPbkContactOperationBase* AddToTopL(
   255                 const TDesC8& aPackedLinks,
   256                 MVPbkOperationObserver& aObserver,
   257                 MVPbkOperationErrorObserver& aErrorObserver );
   258 
   259         /**
   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.
   265          * 
   266          * @param aContactLink The contact link.
   267          * @param aObserver The observer that gets the completion event.
   268          * @param aErrorObserver The observer for error notification. 
   269          */
   270         IMPORT_C MVPbkContactOperationBase* RemoveFromTopL(
   271         	const MVPbkContactLink& aContactLink,
   272         	MVPbkOperationObserver& aObserver,
   273         	MVPbkOperationErrorObserver& aErrorObserver );
   274 
   275         /**
   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.
   281          * 
   282          * A zero length array is valid input and produces no changes. 
   283          * aObserver will be notified asynchronously.
   284          *
   285          * @param aContactLinks The contact links.
   286          * @param aObserver The observer that gets the completion event.
   287          * @param aErrorObserver The observer for error notification. 
   288          */
   289         IMPORT_C MVPbkContactOperationBase* RemoveFromTopL(
   290         	const MVPbkContactLinkArray& aContactLinks,
   291         	MVPbkOperationObserver& aObserver,
   292         	MVPbkOperationErrorObserver& aErrorObserver );
   293 
   294         /**
   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.
   299          * 
   300          * A zero length array is valid input and produces no changes. 
   301          * aObserver will be notified asynchronously.
   302          *
   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. 
   306          */
   307         IMPORT_C MVPbkContactOperationBase* RemoveFromTopL(
   308         	const TDesC8& aPackedLinks,
   309         	MVPbkOperationObserver& aObserver,
   310         	MVPbkOperationErrorObserver& aErrorObserver );
   311 
   312         /**
   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.
   317          * 
   318          * A zero length array is valid input and produces no changes. 
   319          * aObserver will be notified asynchronously.
   320          * 
   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. 
   325          */
   326         IMPORT_C MVPbkContactOperationBase* SetTopOrderL(
   327 	    	const MVPbkContactLinkArray& aContactLinks,
   328 	    	MVPbkOperationObserver& aObserver,
   329 	    	MVPbkOperationErrorObserver& aErrorObserver );
   330 
   331     public: // helper methods related to top contacts.
   332 
   333         /**
   334          * Checks whether a contact is top contact.
   335          *
   336          * @param aContact A contact.
   337          * @return ETrue if aContact it top contact, otherwise EFalse 
   338          */
   339         IMPORT_C static TBool IsTopContact( const MVPbkBaseContact& aContact );
   340 
   341     private: // construction
   342         CVPbkTopContactManager();
   343 
   344     private: // data
   345         CVPbkTopContactManagerImpl* iImpl;
   346     };
   347 
   348 #endif //VPBKTOPCONTACTMANAGER_H
   349 //End of file