--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/contacts_plat/virtual_phonebook_engine_api/inc/MVPbkContactStore.h Wed Sep 01 12:29:52 2010 +0100
@@ -0,0 +1,257 @@
+/*
+* 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: Virtual Phonebook contact store interface.
+*
+*/
+
+
+#ifndef MVPBKCONTACTSTORE_H
+#define MVPBKCONTACTSTORE_H
+
+// INCLUDES
+#include <e32def.h>
+#include <MVPbkObjectHierarchy.h>
+#include <MVPbkContactOperationFactory.h>
+
+// FORWARD DECLARATIONS
+class CVPbkContactViewDefinition;
+class MVPbkContactStoreObserver;
+class MVPbkContactStoreProperties;
+class MVPbkStoreContact;
+class MVPbkContactGroup;
+class MVPbkContactView;
+class MVPbkContactLink;
+class MVPbkFieldTypeList;
+class MVPbkContactViewObserver;
+class MVPbkContactStoreInfo;
+class MVPbkSingleContactLinkOperationObserver;
+class MVPbkContactOperationBase;
+
+//Use this UID to access contact store extension 2. Used as a parameter to ContactStoreExtension() method.
+const TUid KMVPbkContactStoreExtension2Uid = { 2 };
+
+// CLASS DECLARATIONS
+
+/**
+ * A contact store interface that is implemented by all contact stores.
+ *
+ * Using this interface clients can access a single contact store. Usually
+ * it's more suitable to use CVPbkContactManager and MVPbkContactStoreList
+ * for accessing stores because multiple stores can be handled at a same
+ * time.
+ *
+ * The store is opened asynchronously and it must not be used before
+ * notification has arrived. If client opens the store it must also
+ * close the store after usage.
+ *
+ * The interface can be used for retriveing properties and information
+ * of the store and also for creating a view, a new contact or a
+ * new group (if supported).
+ *
+ */
+class MVPbkContactStore :
+ public MVPbkObjectHierarchy,
+ public MVPbkContactOperationFactory
+ {
+ public: // Destructor
+
+ /**
+ * Clients don't destroy the stores directly because they don't
+ * own them. The ownerships are managed by CVPbkContactManager.
+ */
+ virtual ~MVPbkContactStore() { }
+
+ public: // New functions
+ /**
+ * Returns fixed properties of this contact store.
+ *
+ * Fixed properties do not change when the store is open.
+ * The store must be opened before retrieving the properties.
+ *
+ * @return Store properties.
+ */
+ virtual const MVPbkContactStoreProperties& StoreProperties() const = 0;
+
+ /**
+ * Opens this contact store asynchronously.
+ *
+ * Calls back the observer when the opening completes. Notice
+ * that the same store instance can be opened by several observers.
+ *
+ * @param aObserver An observer for the store.
+ * @exception KErrInUse If another asynchronous operation
+ * is already in progress.
+ */
+ virtual void OpenL(
+ MVPbkContactStoreObserver& aObserver ) = 0;
+
+ /**
+ * Replaces an existing store and opens it asynchronously.
+ *
+ * E.g. If the database is a file then this replaces the database if
+ * it's not locked by other clients. If the store
+ * implementation can not implment replacing then this behaves
+ * like OpenL.
+ *
+ * If the store does not exist, it is created if possible.
+ * Calls back the observer when the opening completes.
+ *
+ * @param aObserver An observer for the store.
+ */
+ virtual void ReplaceL(
+ MVPbkContactStoreObserver& aObserver ) = 0;
+
+ /**
+ * Closes this contact store from a single observer.
+ *
+ * This can be always called safely even if OpenL or ReplaceL
+ * hasn't been called.
+ * If the client calls OpenL it must also call this after usage,
+ * The observer will no longer receive events from this store.
+ * If there are other observers for the store then the store
+ * will remain open for them.
+ *
+ * @param aObserver An observer that was given in OpenL or ReplaceL.
+ */
+ virtual void Close(
+ MVPbkContactStoreObserver& aObserver ) = 0;
+
+ /**
+ * Creates a new contact associated to this store.
+ *
+ * The contact can be edited and then it must be committed by
+ * calling MVPbkStoreContact::CommitL for actually saving
+ * it to the store.
+ *
+ * @return A new contact associated to this store. Caller takes
+ * ownership of the returned contact.
+ * @see MVPbkStoreContact
+ * @see MVPbkStoreContact::CommitL
+ */
+ virtual MVPbkStoreContact* CreateNewContactLC() = 0;
+
+ /**
+ * Creates a new contact group associated to this store.
+ *
+ * MVPbkContactStoreProperties::SupportsContactGroups must be
+ * true if this is used.
+ * The contact group might be saved to the store immeadiately
+ * depending on the store implementation.
+ * It is left open for editing. Use CommitL to commit
+ * the creation of the group and its content.
+ *
+ * @return A new contact group associated to this store. Caller takes
+ * the ownership of the returned contact group.
+ * @exception KErrNotSupported if the store doesn't support groups.
+ * Client should check store properties before
+ * calling this.
+ * @see MVPbkContactStoreProperties
+ * @see MVPbkContactGroup
+ * @see MVPbkStoreContact
+ * @see MVPbkStoreContact::CommitL
+ */
+ virtual MVPbkContactGroup* CreateNewContactGroupLC() = 0;
+
+ /**
+ * Creates a new contact view from the store asynchronously.
+ *
+ * Client gets the ownership of the view. The content of
+ * the view depends on the CVPbkContactViewDefinition. The
+ * client must wait the observer event before using the view.
+ *
+ * @param aViewDefinition Defines the properties of the new view.
+ * @param aObserver An observer for the view events.
+ * @param aSortOrder Field types that are used in the view contact
+ * in the same order as in this list. Notice that
+ * stores may not support all possible field types
+ * in a view contact. The implementation
+ * of the view contact must have as many fields as
+ * the sort order. If the store doesn't support the
+ * field type in a view contact then it sets empty
+ * data to the field.
+ * @return A new contact view object. Caller takes ownership of the
+ * returned contact.
+ * @see MVPbkContactView
+ * @see CVPbkContactViewDefinition
+ */
+ virtual MVPbkContactView* CreateViewLC(
+ const CVPbkContactViewDefinition& aViewDefinition,
+ MVPbkContactViewObserver& aObserver,
+ const MVPbkFieldTypeList& aSortOrder ) = 0;
+
+ /**
+ * Returns contact groups contained in this store.
+ *
+ * MVPbkContactStoreProperties::SupportsContactGroups must be
+ * true if this is used. Implementation should return an empty
+ * link array and not NULL.
+ *
+ * @return Contact group identifiers contained in this store.
+ */
+ virtual MVPbkContactLinkArray* ContactGroupsLC() const = 0;
+
+ /**
+ * Returns a contact store information. Information can vary
+ * runtime.
+ *
+ * @return Contact store information.
+ */
+ virtual const MVPbkContactStoreInfo& StoreInfo() const = 0;
+
+ /**
+ * This is part of Virtual Phonebook internal framefork and not
+ * usable for clients. Clients use CVPbkContactManager
+ * for creating links from a stream.
+ *
+ * Creates a link array from a stream. Stream contains the internals
+ * of the contact link. Internals are the contact store implementation
+ * specific part of the package format.
+ *
+ * NOTE: this must work wheter the OpenL has been called or not. This
+ * means that a link can not contain any data that would need
+ * an open store before internalizing.
+ *
+ * @param aStream A stream containing the link internals.
+ * @return A new contact link.
+ * @internal
+ */
+ virtual MVPbkContactLink* CreateLinkFromInternalsLC(
+ RReadStream& aStream ) const = 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* ContactStoreExtension(TUid /*aExtensionUid*/)
+ { return NULL; }
+
+ public: // From MVPbkObjectHierarchy
+
+ MVPbkObjectHierarchy& ParentObject() const
+ {
+ return const_cast<MVPbkObjectHierarchy&>
+ ( static_cast<const MVPbkObjectHierarchy&>( *this ) );
+ }
+ MVPbkContactStore& ContactStore() const
+ {
+ return const_cast<MVPbkContactStore&>( *this );
+ }
+
+ };
+
+#endif // MVPBKCONTACTSTORE_H
+
+// End of File