1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/epoc32/include/app/MVPbkContactViewBase.h Wed Mar 31 12:33:34 2010 +0100
1.3 @@ -0,0 +1,279 @@
1.4 +/*
1.5 +* Copyright (c) 2004-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: An interface for contact views.
1.18 +*
1.19 +*/
1.20 +
1.21 +
1.22 +#ifndef MVPBKCONTACTVIEWBASE_H
1.23 +#define MVPBKCONTACTVIEWBASE_H
1.24 +
1.25 +// INCLUDES
1.26 +#include <e32cmn.h>
1.27 +#include <vpbkcontactview.hrh>
1.28 +#include <bamdesca.h>
1.29 +
1.30 +// FORWARD DECLARATIONS
1.31 +class MVPbkContactViewObserver;
1.32 +class MVPbkViewContact;
1.33 +class MVPbkContactLink;
1.34 +class MVPbkFieldTypeList;
1.35 +class MVPbkContactBookmark;
1.36 +class MVPbkContactViewFiltering;
1.37 +
1.38 +// CLASS DECLARATIONS
1.39 +
1.40 +/**
1.41 + * An common interface for different contact views.
1.42 + *
1.43 + * The contact view interface has many implementations. It can be a view from
1.44 + * a single contact store or it can be a composite of contact/group views from
1.45 + * different stores. It's also possible that it contains folding items that
1.46 + * are not from any store. The client defines the view structure.
1.47 + *
1.48 + * The most common usage is that client uses CVPbkContactManager
1.49 + * for creating a contact view and defines the structure of the view.
1.50 + * @see CVPbkContactManager::CreateContactViewLC
1.51 + */
1.52 +class MVPbkContactViewBase
1.53 + {
1.54 + public: // Destructor
1.55 +
1.56 + /**
1.57 + * Destructor.
1.58 + */
1.59 + virtual ~MVPbkContactViewBase() { }
1.60 +
1.61 + public: // New functions
1.62 +
1.63 + /**
1.64 + * Returns type of this contact view.
1.65 + *
1.66 + * @return A contact view type.
1.67 + */
1.68 + virtual TVPbkContactViewType Type() const = 0;
1.69 +
1.70 + /**
1.71 + * Changes sort order of the view asynchronously.
1.72 + *
1.73 + * Clients of this view will get an event via MVPbkContactViewObserver
1.74 + * interface when the order has been updated. The leaf view sends
1.75 + * a pair of events. First it sends ContactViewUnavailable and then
1.76 + * after the order has been changed ContactViewReady. However if
1.77 + * the view is of type EVPbkCompositeView the client doesn't necessary
1.78 + * receive ContactViewUnavailable at all because it might be that
1.79 + * there is always some subview ready in the composite.
1.80 + *
1.81 + * @param aSortOrder A new sort order for this view.
1.82 + * @exception KErrArgument Possible reasons: a client tries to change
1.83 + * a sort order of platform defined shared
1.84 + * view against the platform setting.
1.85 + * @see CVPbkSortOrder
1.86 + */
1.87 + virtual void ChangeSortOrderL(
1.88 + const MVPbkFieldTypeList& aSortOrder ) = 0;
1.89 +
1.90 + /**
1.91 + * Returns the current sort order of the view.
1.92 + *
1.93 + * The sort order is a sub set of master field types from
1.94 + * CVPbkContactManager.
1.95 + *
1.96 + * @return The sort order of the view.
1.97 + */
1.98 + virtual const MVPbkFieldTypeList& SortOrder() const = 0;
1.99 +
1.100 + /**
1.101 + * Refreshes the view contents asynchronously.
1.102 + *
1.103 + * All handles to this view's contacts are invalidated.
1.104 + * Clients of this view will get an event via MVPbkContactViewObserver
1.105 + * interface when the view has been refreshed.
1.106 + */
1.107 + virtual void RefreshL() = 0;
1.108 +
1.109 + /**
1.110 + * Returns the number of contacts in this view.
1.111 + *
1.112 + * @return The number of contacts.
1.113 + */
1.114 + virtual TInt ContactCountL() const = 0;
1.115 +
1.116 + /**
1.117 + * Returns a contact in this view.
1.118 + *
1.119 + * The returned reference may be invalidated when this
1.120 + * function is called again. For that reason clients should prefer
1.121 + * not to save references to the contacts retrieved from this function.
1.122 + *
1.123 + * @param aIndex An index of the contact in this view.
1.124 + * @return A reference to a contact in this view at aIndex.
1.125 + * @precond aIndex >= 0
1.126 + * VPbkError::Panic(VPbkError::EInvalidContactIndex)
1.127 + * is raised if the precondition does not hold.
1.128 + * @exception KErrArgument if aIndex >= ContactCountL()
1.129 + */
1.130 + virtual const MVPbkViewContact& ContactAtL(
1.131 + TInt aIndex ) const = 0;
1.132 +
1.133 + /**
1.134 + * Creates and returns a link that points to contact at aIndex.
1.135 + *
1.136 + * NOTE: If the view contact is not from any store it can return
1.137 + * also NULL. E.g. if the view contact is a folding
1.138 + * contact view that it's not saved to any store.
1.139 + * The NULL is not pushed onto the cleanup stack.
1.140 + *
1.141 + * @param aIndex An index of the contact for which the link
1.142 + * is created.
1.143 + * @return A new link object pointing to contact at aIndex or NULL if
1.144 + * the link can't be created (e.g. a folder).
1.145 + * @precond aIndex >= 0
1.146 + * VPbkError::Panic(VPbkError::EInvalidContactIndex)
1.147 + * is raised if the precondition does not hold.
1.148 + * @exception KErrArgument if aIndex >= ContactCountL()
1.149 + */
1.150 + virtual MVPbkContactLink* CreateLinkLC(
1.151 + TInt aIndex ) const = 0;
1.152 +
1.153 + /**
1.154 + * Returns The index of the aContactLink in this view.
1.155 + *
1.156 + * If the identifier is not found from the view then
1.157 + * KErrNotFound is returned. If the view is not from
1.158 + * any store (e.g. a folding view) then it will also
1.159 + * return KErrNotFound.
1.160 + *
1.161 + * NOTE: the implementation of this function probably
1.162 + * must loop the view which means that calling
1.163 + * this function frequently or in a loop can
1.164 + * be slow when there are lots of contacts.
1.165 + *
1.166 + * @param aContactLink A link whose index is searched for.
1.167 + * @return The index of the link or KErrNotFound.
1.168 + */
1.169 + virtual TInt IndexOfLinkL(
1.170 + const MVPbkContactLink& aContactLink ) const = 0;
1.171 +
1.172 + /**
1.173 + * Adds an observer to this contact view asynchronously.
1.174 + *
1.175 + * The observer will be notified after it has been added
1.176 + * to the view.
1.177 + *
1.178 + * @param aObserver A new observer for the view.
1.179 + */
1.180 + virtual void AddObserverL(
1.181 + MVPbkContactViewObserver& aObserver ) = 0;
1.182 +
1.183 + /**
1.184 + * Removes an observer from this contact view.
1.185 + *
1.186 + * This method can be called even if aObserver has not been
1.187 + * previously added. In that case, no observers are removed.
1.188 + *
1.189 + * @param aObserver The observer to be removed.
1.190 + */
1.191 + virtual void RemoveObserver(
1.192 + MVPbkContactViewObserver& aObserver ) = 0;
1.193 +
1.194 + /**
1.195 + * Returns ETrue if this view is from a store identified
1.196 + * by aContactStoreUri.
1.197 + *
1.198 + * @param aContactStoreUri The whole URI of the contact store.
1.199 + * @return ETrue if the view was from the given store.
1.200 + *
1.201 + * @see TVPbkContactStoreUriPtr::UriDes
1.202 + */
1.203 + virtual TBool MatchContactStore(
1.204 + const TDesC& aContactStoreUri ) const = 0;
1.205 +
1.206 + /**
1.207 + * Returns ETrue if this view is from a store domain identified
1.208 + * by aContactStoreDomain.
1.209 + *
1.210 + * @param aContactStoreDomain The domain part of the contact store URI.
1.211 + * The domain can be retrieved from the
1.212 + * whole contact store URI using class
1.213 + * TVPbkContactStoreUriPtr and
1.214 + * EContactStoreUriStoreType.
1.215 + * An implementation compares the
1.216 + * EContactStoreUriStoreType part of
1.217 + * its own URI to aContactStoreDomain.
1.218 + *
1.219 + * @return ETrue if the view was from the same store domain.
1.220 + * @see TVPbkContactStoreUriPtr
1.221 + */
1.222 + virtual TBool MatchContactStoreDomain(
1.223 + const TDesC& aContactStoreDomain ) const = 0;
1.224 +
1.225 + /**
1.226 + * Creates and returns a bookmark that points to the
1.227 + * view contact at aIndex.
1.228 + *
1.229 + * @param aIndex An index of the contact in the view.
1.230 + * @return A new bookmark to the view item.
1.231 + * @precond aIndex >= 0
1.232 + * VPbkError::Panic(VPbkError::EInvalidContactIndex)
1.233 + * is raised if the precondition does not hold.
1.234 + */
1.235 + virtual MVPbkContactBookmark* CreateBookmarkLC(
1.236 + TInt aIndex ) const = 0;
1.237 +
1.238 + /**
1.239 + * Returns an index of the contact in the view.
1.240 + *
1.241 + * If the identifier is not found from the view then
1.242 + * KErrNotFound is returned.
1.243 + *
1.244 + * NOTE: the implementation of this function probably
1.245 + * must loop the view which means that calling
1.246 + * this function frequently or in a loop can
1.247 + * be slow when there are lots of contacts.
1.248 + *
1.249 + * @param aContactBookmark A bookmark that identifies
1.250 + * a contact in the view.
1.251 + * @return An index of the contact in the view or KErrNotFound.
1.252 + */
1.253 + virtual TInt IndexOfBookmarkL(
1.254 + const MVPbkContactBookmark& aContactBookmark ) const = 0;
1.255 +
1.256 + /**
1.257 + * Returns an interface for text based contact filtering support.
1.258 + *
1.259 + * If the view doesn't support filtering then this returns NULL.
1.260 + * Filtering must be supported in all views created from a contact
1.261 + * store. However, it's possible to implement a view that doesn't
1.262 + * need a filtering support and therefore clients must always check
1.263 + * the returned pointer.
1.264 + *
1.265 + * @return A filtering interface or NULL
1.266 + */
1.267 + virtual MVPbkContactViewFiltering* ViewFiltering() = 0;
1.268 +
1.269 + /**
1.270 + * Returns an extension point for this interface or NULL.
1.271 + *
1.272 + * @param aExtensionUid no extensions defined currently.
1.273 + * @return an extension point for this interface or NULL.
1.274 + */
1.275 + virtual TAny* ContactViewBaseExtension(TUid /*aExtensionUid*/)
1.276 + { return NULL; }
1.277 + };
1.278 +
1.279 +
1.280 +#endif // MVPBKCONTACTVIEWBASE_H
1.281 +
1.282 +// End of File