--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/contacts_plat/virtual_phonebook_engine_api/inc/MVPbkContactViewBase.h Tue Feb 02 10:12:17 2010 +0200
@@ -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 <e32cmn.h>
+#include <vpbkcontactview.hrh>
+#include <bamdesca.h>
+
+// 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