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