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