williamr@4: /* williamr@4: * Copyright (c) 2004-2007 Nokia Corporation and/or its subsidiary(-ies). williamr@4: * All rights reserved. williamr@4: * This component and the accompanying materials are made available williamr@4: * under the terms of "Eclipse Public License v1.0" williamr@4: * which accompanies this distribution, and is available williamr@4: * at the URL "http://www.eclipse.org/legal/epl-v10.html". williamr@4: * williamr@4: * Initial Contributors: williamr@4: * Nokia Corporation - initial contribution. williamr@4: * williamr@4: * Contributors: williamr@4: * williamr@4: * Description: An interface for contact views. williamr@4: * williamr@4: */ williamr@4: williamr@4: williamr@4: #ifndef MVPBKCONTACTVIEWBASE_H williamr@4: #define MVPBKCONTACTVIEWBASE_H williamr@4: williamr@4: // INCLUDES williamr@4: #include williamr@4: #include williamr@4: #include williamr@4: williamr@4: // FORWARD DECLARATIONS williamr@4: class MVPbkContactViewObserver; williamr@4: class MVPbkViewContact; williamr@4: class MVPbkContactLink; williamr@4: class MVPbkFieldTypeList; williamr@4: class MVPbkContactBookmark; williamr@4: class MVPbkContactViewFiltering; williamr@4: williamr@4: // CLASS DECLARATIONS williamr@4: williamr@4: /** williamr@4: * An common interface for different contact views. williamr@4: * williamr@4: * The contact view interface has many implementations. It can be a view from williamr@4: * a single contact store or it can be a composite of contact/group views from williamr@4: * different stores. It's also possible that it contains folding items that williamr@4: * are not from any store. The client defines the view structure. williamr@4: * williamr@4: * The most common usage is that client uses CVPbkContactManager williamr@4: * for creating a contact view and defines the structure of the view. williamr@4: * @see CVPbkContactManager::CreateContactViewLC williamr@4: */ williamr@4: class MVPbkContactViewBase williamr@4: { williamr@4: public: // Destructor williamr@4: williamr@4: /** williamr@4: * Destructor. williamr@4: */ williamr@4: virtual ~MVPbkContactViewBase() { } williamr@4: williamr@4: public: // New functions williamr@4: williamr@4: /** williamr@4: * Returns type of this contact view. williamr@4: * williamr@4: * @return A contact view type. williamr@4: */ williamr@4: virtual TVPbkContactViewType Type() const = 0; williamr@4: williamr@4: /** williamr@4: * Changes sort order of the view asynchronously. williamr@4: * williamr@4: * Clients of this view will get an event via MVPbkContactViewObserver williamr@4: * interface when the order has been updated. The leaf view sends williamr@4: * a pair of events. First it sends ContactViewUnavailable and then williamr@4: * after the order has been changed ContactViewReady. However if williamr@4: * the view is of type EVPbkCompositeView the client doesn't necessary williamr@4: * receive ContactViewUnavailable at all because it might be that williamr@4: * there is always some subview ready in the composite. williamr@4: * williamr@4: * @param aSortOrder A new sort order for this view. williamr@4: * @exception KErrArgument Possible reasons: a client tries to change williamr@4: * a sort order of platform defined shared williamr@4: * view against the platform setting. williamr@4: * @see CVPbkSortOrder williamr@4: */ williamr@4: virtual void ChangeSortOrderL( williamr@4: const MVPbkFieldTypeList& aSortOrder ) = 0; williamr@4: williamr@4: /** williamr@4: * Returns the current sort order of the view. williamr@4: * williamr@4: * The sort order is a sub set of master field types from williamr@4: * CVPbkContactManager. williamr@4: * williamr@4: * @return The sort order of the view. williamr@4: */ williamr@4: virtual const MVPbkFieldTypeList& SortOrder() const = 0; williamr@4: williamr@4: /** williamr@4: * Refreshes the view contents asynchronously. williamr@4: * williamr@4: * All handles to this view's contacts are invalidated. williamr@4: * Clients of this view will get an event via MVPbkContactViewObserver williamr@4: * interface when the view has been refreshed. williamr@4: */ williamr@4: virtual void RefreshL() = 0; williamr@4: williamr@4: /** williamr@4: * Returns the number of contacts in this view. williamr@4: * williamr@4: * @return The number of contacts. williamr@4: */ williamr@4: virtual TInt ContactCountL() const = 0; williamr@4: williamr@4: /** williamr@4: * Returns a contact in this view. williamr@4: * williamr@4: * The returned reference may be invalidated when this williamr@4: * function is called again. For that reason clients should prefer williamr@4: * not to save references to the contacts retrieved from this function. williamr@4: * williamr@4: * @param aIndex An index of the contact in this view. williamr@4: * @return A reference to a contact in this view at aIndex. williamr@4: * @precond aIndex >= 0 williamr@4: * VPbkError::Panic(VPbkError::EInvalidContactIndex) williamr@4: * is raised if the precondition does not hold. williamr@4: * @exception KErrArgument if aIndex >= ContactCountL() williamr@4: */ williamr@4: virtual const MVPbkViewContact& ContactAtL( williamr@4: TInt aIndex ) const = 0; williamr@4: williamr@4: /** williamr@4: * Creates and returns a link that points to contact at aIndex. williamr@4: * williamr@4: * NOTE: If the view contact is not from any store it can return williamr@4: * also NULL. E.g. if the view contact is a folding williamr@4: * contact view that it's not saved to any store. williamr@4: * The NULL is not pushed onto the cleanup stack. williamr@4: * williamr@4: * @param aIndex An index of the contact for which the link williamr@4: * is created. williamr@4: * @return A new link object pointing to contact at aIndex or NULL if williamr@4: * the link can't be created (e.g. a folder). williamr@4: * @precond aIndex >= 0 williamr@4: * VPbkError::Panic(VPbkError::EInvalidContactIndex) williamr@4: * is raised if the precondition does not hold. williamr@4: * @exception KErrArgument if aIndex >= ContactCountL() williamr@4: */ williamr@4: virtual MVPbkContactLink* CreateLinkLC( williamr@4: TInt aIndex ) const = 0; williamr@4: williamr@4: /** williamr@4: * Returns The index of the aContactLink in this view. williamr@4: * williamr@4: * If the identifier is not found from the view then williamr@4: * KErrNotFound is returned. If the view is not from williamr@4: * any store (e.g. a folding view) then it will also williamr@4: * return KErrNotFound. williamr@4: * williamr@4: * NOTE: the implementation of this function probably williamr@4: * must loop the view which means that calling williamr@4: * this function frequently or in a loop can williamr@4: * be slow when there are lots of contacts. williamr@4: * williamr@4: * @param aContactLink A link whose index is searched for. williamr@4: * @return The index of the link or KErrNotFound. williamr@4: */ williamr@4: virtual TInt IndexOfLinkL( williamr@4: const MVPbkContactLink& aContactLink ) const = 0; williamr@4: williamr@4: /** williamr@4: * Adds an observer to this contact view asynchronously. williamr@4: * williamr@4: * The observer will be notified after it has been added williamr@4: * to the view. williamr@4: * williamr@4: * @param aObserver A new observer for the view. williamr@4: */ williamr@4: virtual void AddObserverL( williamr@4: MVPbkContactViewObserver& aObserver ) = 0; williamr@4: williamr@4: /** williamr@4: * Removes an observer from this contact view. williamr@4: * williamr@4: * This method can be called even if aObserver has not been williamr@4: * previously added. In that case, no observers are removed. williamr@4: * williamr@4: * @param aObserver The observer to be removed. williamr@4: */ williamr@4: virtual void RemoveObserver( williamr@4: MVPbkContactViewObserver& aObserver ) = 0; williamr@4: williamr@4: /** williamr@4: * Returns ETrue if this view is from a store identified williamr@4: * by aContactStoreUri. williamr@4: * williamr@4: * @param aContactStoreUri The whole URI of the contact store. williamr@4: * @return ETrue if the view was from the given store. williamr@4: * williamr@4: * @see TVPbkContactStoreUriPtr::UriDes williamr@4: */ williamr@4: virtual TBool MatchContactStore( williamr@4: const TDesC& aContactStoreUri ) const = 0; williamr@4: williamr@4: /** williamr@4: * Returns ETrue if this view is from a store domain identified williamr@4: * by aContactStoreDomain. williamr@4: * williamr@4: * @param aContactStoreDomain The domain part of the contact store URI. williamr@4: * The domain can be retrieved from the williamr@4: * whole contact store URI using class williamr@4: * TVPbkContactStoreUriPtr and williamr@4: * EContactStoreUriStoreType. williamr@4: * An implementation compares the williamr@4: * EContactStoreUriStoreType part of williamr@4: * its own URI to aContactStoreDomain. williamr@4: * williamr@4: * @return ETrue if the view was from the same store domain. williamr@4: * @see TVPbkContactStoreUriPtr williamr@4: */ williamr@4: virtual TBool MatchContactStoreDomain( williamr@4: const TDesC& aContactStoreDomain ) const = 0; williamr@4: williamr@4: /** williamr@4: * Creates and returns a bookmark that points to the williamr@4: * view contact at aIndex. williamr@4: * williamr@4: * @param aIndex An index of the contact in the view. williamr@4: * @return A new bookmark to the view item. williamr@4: * @precond aIndex >= 0 williamr@4: * VPbkError::Panic(VPbkError::EInvalidContactIndex) williamr@4: * is raised if the precondition does not hold. williamr@4: */ williamr@4: virtual MVPbkContactBookmark* CreateBookmarkLC( williamr@4: TInt aIndex ) const = 0; williamr@4: williamr@4: /** williamr@4: * Returns an index of the contact in the view. williamr@4: * williamr@4: * If the identifier is not found from the view then williamr@4: * KErrNotFound is returned. williamr@4: * williamr@4: * NOTE: the implementation of this function probably williamr@4: * must loop the view which means that calling williamr@4: * this function frequently or in a loop can williamr@4: * be slow when there are lots of contacts. williamr@4: * williamr@4: * @param aContactBookmark A bookmark that identifies williamr@4: * a contact in the view. williamr@4: * @return An index of the contact in the view or KErrNotFound. williamr@4: */ williamr@4: virtual TInt IndexOfBookmarkL( williamr@4: const MVPbkContactBookmark& aContactBookmark ) const = 0; williamr@4: williamr@4: /** williamr@4: * Returns an interface for text based contact filtering support. williamr@4: * williamr@4: * If the view doesn't support filtering then this returns NULL. williamr@4: * Filtering must be supported in all views created from a contact williamr@4: * store. However, it's possible to implement a view that doesn't williamr@4: * need a filtering support and therefore clients must always check williamr@4: * the returned pointer. williamr@4: * williamr@4: * @return A filtering interface or NULL williamr@4: */ williamr@4: virtual MVPbkContactViewFiltering* ViewFiltering() = 0; williamr@4: williamr@4: /** williamr@4: * Returns an extension point for this interface or NULL. williamr@4: * williamr@4: * @param aExtensionUid no extensions defined currently. williamr@4: * @return an extension point for this interface or NULL. williamr@4: */ williamr@4: virtual TAny* ContactViewBaseExtension(TUid /*aExtensionUid*/) williamr@4: { return NULL; } williamr@4: }; williamr@4: williamr@4: williamr@4: #endif // MVPBKCONTACTVIEWBASE_H williamr@4: williamr@4: // End of File