diff -r e1b950c65cb4 -r 837f303aceeb epoc32/include/app/MVPbkContactStore.h --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/epoc32/include/app/MVPbkContactStore.h Wed Mar 31 12:33:34 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 +#include +#include + +// 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 + ( static_cast( *this ) ); + } + MVPbkContactStore& ContactStore() const + { + return const_cast( *this ); + } + + }; + +#endif // MVPBKCONTACTSTORE_H + +// End of File