1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/epoc32/include/app/CVPbkTopContactManager.h Wed Mar 31 12:33:34 2010 +0100
1.3 @@ -0,0 +1,349 @@
1.4 +/*
1.5 +* Copyright (c) 2005-2007 Nokia Corporation and/or its subsidiary(-ies).
1.6 +* All rights reserved.
1.7 +* This component and the accompanying materials are made available
1.8 +* under the terms of "Eclipse Public License v1.0"
1.9 +* which accompanies this distribution, and is available
1.10 +* at the URL "http://www.eclipse.org/legal/epl-v10.html".
1.11 +*
1.12 +* Initial Contributors:
1.13 +* Nokia Corporation - initial contribution.
1.14 +*
1.15 +* Contributors:
1.16 +*
1.17 +* Description: Top Contact manager
1.18 +*
1.19 +*/
1.20 +
1.21 +
1.22 +#ifndef VPBKTOPCONTACTMANAGER_H
1.23 +#define VPBKTOPCONTACTMANAGER_H
1.24 +
1.25 +// INCLUDES
1.26 +#include <e32base.h>
1.27 +
1.28 +// FORWARD DECLARATIONS
1.29 +class MVPbkContactLink;
1.30 +class MVPbkContactLinkArray;
1.31 +class CVPbkContactLinkArray;
1.32 +class CVPbkContactManager;
1.33 +class MVPbkContactViewBase;
1.34 +class MVPbkContactOperationBase;
1.35 +class MVPbkBaseContact;
1.36 +class MVPbkOperationObserver;
1.37 +template<typename T>
1.38 +class MVPbkOperationResultObserver;
1.39 +class MVPbkOperationErrorObserver;
1.40 +
1.41 +class CVPbkTopContactManagerImpl;
1.42 +
1.43 +// CLASS DECLARATION
1.44 +
1.45 +/**
1.46 + * A class for managing Top Contact properties of contacts.
1.47 + * All main operations are asynchronous and accept two observers.
1.48 + * One used to signal completion and return result if necessary.
1.49 + * Another one used to signal an error if operation fails.
1.50 + *
1.51 + * @example
1.52 + * A client that re-orders the existing top contacts in the phone
1.53 + *
1.54 + * class CTopContactManagerClient :
1.55 + * public CActive,
1.56 + * public MVPbkOperationObserver,
1.57 + * public MVPbkOperationErrorObserver,
1.58 + * public MVPbkOperationResultObserver<MVPbkContactViewBase*>
1.59 + * ...
1.60 + *
1.61 + * // MVPbkOperationObserver
1.62 + * void CTopContactManagerClient::VPbkOperationCompleted(
1.63 + * MVPbkContactOperationBase*)
1.64 + * {
1.65 + * FinishCommand( KErrNone );
1.66 + * }
1.67 + *
1.68 + * //From MVPbkOperationErrorObserver
1.69 + * void CTopContactManagerClient::VPbkOperationFailed(
1.70 + * MVPbkContactOperationBase*,
1.71 + * TInt aError )
1.72 + * {
1.73 + * FinishCommand( aError );
1.74 + * }
1.75 + *
1.76 + * // From MVPbkOperationResultObserver
1.77 + * void CTopContactManagerClient::VPbkOperationResultCompleted(
1.78 + * MVPbkContactOperationBase*,
1.79 + * MVPbkContactViewBase* aView )
1.80 + * {
1.81 + * iView = aView;
1.82 + * delete iTopContactOperation;
1.83 + * iTopContactOperation = NULL;
1.84 + * IssueRequest(EShowMoveDlg);
1.85 + * }
1.86 + * // --------------------------------------------------------------------------
1.87 + * // CTopContactManagerClient::RunL
1.88 + * // State Machine using TopContactManager
1.89 + * // --------------------------------------------------------------------------
1.90 + * //
1.91 + * void CTopContactManagerClient::RunL()
1.92 + * {
1.93 + * switch(iState)
1.94 + * {
1.95 + * case ELoadingTopContacts:
1.96 + * {
1.97 + * // This async call will fall into VPbkOperationResultCompleted on success with
1.98 + * // MVPbkContactOperationBase object as a result
1.99 + * // Otherwise, it will fall into VPbkOperationFailed callback
1.100 + * iTopContactOperation = iVPbkTopContactManager->GetTopContactsViewL(
1.101 + * *this,
1.102 + * *this );
1.103 + * break;
1.104 + * }
1.105 + * case EShowMoveDlg:
1.106 + * {
1.107 + * ShowDlgL(); // confirm re-ordering top contacts with user
1.108 + * break;
1.109 + * }
1.110 + * case ESavingTopContacts:
1.111 + * {
1.112 + * // Do re-ordering via Top Manager
1.113 + * // This async call will fall into VPbkOperationResultCompleted on success with
1.114 + * // MVPbkContactOperationBase object as a result
1.115 + * // Otherwise, it will fall into VPbkOperationFailed callback
1.116 + * iTopContactOperation = iVPbkTopContactManager->SetTopOrderL(
1.117 + * *iTopContacts,
1.118 + * *this,
1.119 + * *this );
1.120 + * CleanupStack::PopAndDestroy(); //topContacts
1.121 + * break;
1.122 + * }
1.123 + *
1.124 + * ...
1.125 + * }
1.126 + * }
1.127 + *
1.128 +*/
1.129 +NONSHARABLE_CLASS( CVPbkTopContactManager ) : public CBase
1.130 + {
1.131 + public:
1.132 +
1.133 + /**
1.134 + * Creates the top contact manager.
1.135 + * @param aContactManager Contact manager which already has its stores opened.
1.136 + */
1.137 + IMPORT_C static CVPbkTopContactManager* NewL( CVPbkContactManager& aContactManager );
1.138 +
1.139 + /**
1.140 + * Creates the top contact manager.
1.141 + * Holds its own CVPbkContactManager instance.
1.142 + *
1.143 + */
1.144 + IMPORT_C static CVPbkTopContactManager* NewL();
1.145 +
1.146 + IMPORT_C ~CVPbkTopContactManager();
1.147 +
1.148 + public:
1.149 +
1.150 + /**
1.151 + * Get top contacts as contact view.
1.152 + *
1.153 + * If CVPbkTopContactManager was created without giving an external
1.154 + * contact manager as reference, then calling GetTopContactsViewL()
1.155 + * will open the default store if it is not already open.
1.156 + *
1.157 + * @param aResultObserver The observer that gets ready contacts view.
1.158 + * @param aErrorObserver The observer for error notification.
1.159 + */
1.160 + IMPORT_C MVPbkContactOperationBase* GetTopContactsViewL(
1.161 + MVPbkOperationResultObserver<MVPbkContactViewBase*>& aResultObserver,
1.162 + MVPbkOperationErrorObserver& aErrorObserver);
1.163 +
1.164 + /**
1.165 + * Get NON-top contacts as contact view.
1.166 + *
1.167 + * If CVPbkTopContactManager was created without giving an external
1.168 + * contact manager as reference, then calling GetNonTopContactsViewL()
1.169 + * will open the default store if it is not already open.
1.170 + *
1.171 + * @param aResultObserver The observer that gets ready contacts view.
1.172 + * @param aErrorObserver The observer for error notification.
1.173 + */
1.174 + IMPORT_C MVPbkContactOperationBase* GetNonTopContactsViewL(
1.175 + MVPbkOperationResultObserver<MVPbkContactViewBase*>& aResultObserver,
1.176 + MVPbkOperationErrorObserver& aErrorObserver );
1.177 +
1.178 + /**
1.179 + * Get top contacts as contact link array.
1.180 + *
1.181 + * @param aResultObserver The observer that gets top contact links array.
1.182 + * @param aErrorObserver The observer for error notification.
1.183 + */
1.184 + IMPORT_C MVPbkContactOperationBase* GetTopContactLinksL(
1.185 + MVPbkOperationResultObserver<MVPbkContactLinkArray*>& aResultObserver,
1.186 + MVPbkOperationErrorObserver& aErrorObserver );
1.187 +
1.188 + /**
1.189 + * Get NON-top contacts as contact link array.
1.190 + *
1.191 + * @param aResultObserver The observer that gets non-top contact links array.
1.192 + * @param aErrorObserver The observer for error notification.
1.193 + */
1.194 + IMPORT_C MVPbkContactOperationBase* GetNonTopContactLinksL(
1.195 + MVPbkOperationResultObserver<MVPbkContactLinkArray*>& aResultObserver,
1.196 + MVPbkOperationErrorObserver& aErrorObserver );
1.197 +
1.198 + /**
1.199 + * Sets a contact as Top Contact. It will become the last top contact.
1.200 + * If a contact manager was not given during
1.201 + * construction, then a contact manager is created and the store which
1.202 + * is defined in the first link will be opened.
1.203 + * The stores used to create aContactLink should be loaded.
1.204 + *
1.205 + * If the contact already is a Top Contact, then the Top order of that
1.206 + * contact is not modified.
1.207 + *
1.208 + * @param aContactLink The contact link.
1.209 + * @param aObserver The observer that gets the completion event.
1.210 + * @param aErrorObserver The observer for error notification.
1.211 + */
1.212 + IMPORT_C MVPbkContactOperationBase* AddToTopL(
1.213 + const MVPbkContactLink& aContactLink,
1.214 + MVPbkOperationObserver& aObserver,
1.215 + MVPbkOperationErrorObserver& aErrorObserver );
1.216 +
1.217 + /**
1.218 + * Sets contacts as Top Contacts.
1.219 + * The Top ordering will be according to the arrays order.
1.220 + * If a contact manager was not given during
1.221 + * construction, then a contact manager is created and the store which
1.222 + * is defined in the first link will be opened.
1.223 + * The store used to create aContactLinks should be loaded.
1.224 + *
1.225 + * If the contact already is a Top Contact, then the Top order of that
1.226 + * contact is not modified.
1.227 + *
1.228 + * A zero length array is valid input and produces no changes.
1.229 + * aObserver will be notified asynchronously.
1.230 + *
1.231 + * @param aContactLinks The contact links.
1.232 + * @param aObserver The observer that gets the completion event.
1.233 + * @param aErrorObserver The observer for error notification.
1.234 + */
1.235 + IMPORT_C MVPbkContactOperationBase* AddToTopL(
1.236 + const MVPbkContactLinkArray& aContactLinks,
1.237 + MVPbkOperationObserver& aObserver,
1.238 + MVPbkOperationErrorObserver& aErrorObserver );
1.239 +
1.240 + /**
1.241 + * Sets contacts as Top Contacts. Accepts a packed link array.
1.242 + * The Top ordering will be according to the arrays order.
1.243 + * If a contact manager was not given during
1.244 + * construction, then a contact manager is created and the store which
1.245 + * is defined in the first link will be opened.
1.246 + *
1.247 + * If the contact already is a Top Contact, then the Top order of that
1.248 + * contact is not modified.
1.249 + *
1.250 + * A zero length array is valid input and produces no changes.
1.251 + * aObserver will be notified asynchronously.
1.252 + *
1.253 + * @param aPackedLinks A contact link array in packed form.
1.254 + * @param aObserver The observer that gets the completion event.
1.255 + * @param aErrorObserver The observer for error notification.
1.256 + */
1.257 + IMPORT_C MVPbkContactOperationBase* AddToTopL(
1.258 + const TDesC8& aPackedLinks,
1.259 + MVPbkOperationObserver& aObserver,
1.260 + MVPbkOperationErrorObserver& aErrorObserver );
1.261 +
1.262 + /**
1.263 + * Removes a contact from the Top.
1.264 + * If a contact manager was not given during
1.265 + * construction, then a contact manager is created and the store which
1.266 + * is defined in the link will be opened.
1.267 + * The stores used to create aContactLink should be loaded.
1.268 + *
1.269 + * @param aContactLink The contact link.
1.270 + * @param aObserver The observer that gets the completion event.
1.271 + * @param aErrorObserver The observer for error notification.
1.272 + */
1.273 + IMPORT_C MVPbkContactOperationBase* RemoveFromTopL(
1.274 + const MVPbkContactLink& aContactLink,
1.275 + MVPbkOperationObserver& aObserver,
1.276 + MVPbkOperationErrorObserver& aErrorObserver );
1.277 +
1.278 + /**
1.279 + * Removes contacts from the Top.¨
1.280 + * If a contact manager was not given during
1.281 + * construction, then a contact manager is created and the store which
1.282 + * is defined in the first link will be opened.
1.283 + * The store used to create aContactLinks should be loaded.
1.284 + *
1.285 + * A zero length array is valid input and produces no changes.
1.286 + * aObserver will be notified asynchronously.
1.287 + *
1.288 + * @param aContactLinks The contact links.
1.289 + * @param aObserver The observer that gets the completion event.
1.290 + * @param aErrorObserver The observer for error notification.
1.291 + */
1.292 + IMPORT_C MVPbkContactOperationBase* RemoveFromTopL(
1.293 + const MVPbkContactLinkArray& aContactLinks,
1.294 + MVPbkOperationObserver& aObserver,
1.295 + MVPbkOperationErrorObserver& aErrorObserver );
1.296 +
1.297 + /**
1.298 + * Removes contacts from the Top. Accepts a packed link array.
1.299 + * If a contact manager was not given during
1.300 + * construction, then a contact manager is created and the store which
1.301 + * is defined in the first link will be opened.
1.302 + *
1.303 + * A zero length array is valid input and produces no changes.
1.304 + * aObserver will be notified asynchronously.
1.305 + *
1.306 + * @param aPackedLinks A contact link array in packed form.
1.307 + * @param aObserver The observer that gets the completion event.
1.308 + * @param aErrorObserver The observer for error notification.
1.309 + */
1.310 + IMPORT_C MVPbkContactOperationBase* RemoveFromTopL(
1.311 + const TDesC8& aPackedLinks,
1.312 + MVPbkOperationObserver& aObserver,
1.313 + MVPbkOperationErrorObserver& aErrorObserver );
1.314 +
1.315 + /**
1.316 + * Sets the new order of top contacts.
1.317 + * Ordering is done within the subset of contacts that were given.
1.318 + * Ignores contacts that are not already Top.
1.319 + * The store used to create aContactLinks should be loaded.
1.320 + *
1.321 + * A zero length array is valid input and produces no changes.
1.322 + * aObserver will be notified asynchronously.
1.323 + *
1.324 + * @param aContactLinks The contacts to be reordered. Order is
1.325 + * determined by the array order, ie. first is top.
1.326 + * @param aObserver The observer that gets the completion event.
1.327 + * @param aErrorObserver The observer for error notification.
1.328 + */
1.329 + IMPORT_C MVPbkContactOperationBase* SetTopOrderL(
1.330 + const MVPbkContactLinkArray& aContactLinks,
1.331 + MVPbkOperationObserver& aObserver,
1.332 + MVPbkOperationErrorObserver& aErrorObserver );
1.333 +
1.334 + public: // helper methods related to top contacts.
1.335 +
1.336 + /**
1.337 + * Checks whether a contact is top contact.
1.338 + *
1.339 + * @param aContact A contact.
1.340 + * @return ETrue if aContact it top contact, otherwise EFalse
1.341 + */
1.342 + IMPORT_C static TBool IsTopContact( const MVPbkBaseContact& aContact );
1.343 +
1.344 + private: // construction
1.345 + CVPbkTopContactManager();
1.346 +
1.347 + private: // data
1.348 + CVPbkTopContactManagerImpl* iImpl;
1.349 + };
1.350 +
1.351 +#endif //VPBKTOPCONTACTMANAGER_H
1.352 +//End of file