/*

 * 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