diff -r e1b950c65cb4 -r 837f303aceeb epoc32/include/app/MVPbkStoreContact.h --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/epoc32/include/app/MVPbkStoreContact.h Wed Mar 31 12:33:34 2010 +0100 @@ -0,0 +1,256 @@ +/* +* 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 store contacts. +* +*/ + + +#ifndef MVPBKSTORECONTACT_H +#define MVPBKSTORECONTACT_H + + +// INCLUDES +#include +#include +#include + +// Includes needed for covariant return types +#include + +// FORWARD DECLARATIONS +class MVPbkContactStore; +class MVPbkContactObserver; +class MVPbkStoreContactField; +class MVPbkFieldType; +class MVPbkContactLinkArray; +class MVPbkContactGroup; +class MVPbkStoreContactProperties; + +// CONSTANTS +const TInt KVPbkStoreContactUnlimitedNumber = -1; + +//Use this UID to access contact store extension 2. +// Used as a parameter to ContactStoreExtension() method. +const TUid KMVPbkStoreContactExtension2Uid = { 2 }; +// CLASS DECLARATIONS + +/** + * An interface for store contacts. + * + * A store contact is a contact that includes all the fields of + * the contact. For this reason it usually contains more data compared + * to the corresponding view contact. It can contain all types of fields that + * are supported by the its parent store. + * + * The store contact can be edited if it's not read-only. The client must + * first lock the existing contact then edit it and finally commit the changes. + * + * @see MVPbkContactStore + * @see MVPbkViewContact + */ +class MVPbkStoreContact : public MVPbkBaseContact, + public MVPbkObjectHierarchy + { + public: // Destructor + virtual ~MVPbkStoreContact() { } + + public: // From MVPbkBaseContact (covariant return types) + const MVPbkStoreContactFieldCollection& Fields() const =0; + + public: // New functions + /** + * Pushes an item on the cleanup stack. + * + * Clients must use either this function or CleanupDeletePushL + * from e32base.h. + * + * CleanupStack::PushL(TAny*) must not be used because the virtual + * destructor of M-class won't be called. + * This function should be used to make sure that the virtual destructor + * of this object is called when popped and destroyed from the cleanup + * stack. + */ + inline void PushL(); + + /** + * Returns this contact's parent store. + * + * @return The parent store of the contact. + */ + virtual MVPbkContactStore& ParentStore() const =0; + + /** + * Returns this contact's fields (read-write). + * + * @return A collection of contact fields. + */ + virtual MVPbkStoreContactFieldCollection& Fields() =0; + + /** + * Creates a new field for this contact. + * + * The new field must be added to the contact using AddFieldL. + * + * @param aFieldType A type of the field to create. Must be found in + * ParentStore().SupportedFieldTypes(). + * @return A new field object. The returned object is left on the + * cleanup stack. + * @exception KErrNotSupported if the field type is not supported. + * @exception KErrAccessDenied if the contact can not be modified. + */ + virtual MVPbkStoreContactField* CreateFieldLC( + const MVPbkFieldType& aFieldType) const =0; + + /** + * Adds a new field to the contact. + * + * The field must be previously created with CreateFieldLC and + * it must NOT be used after adding. + * + * If the client needs the field after adding it must be retrieved + * using Fields(). + * + * @param aField A new field that was created using CreateFieldLC. + * This object takes ownership of the field. + * @precond aField must not be NULL or + * VPbkError::Panic(VPbkError::ENullContactField) is raised. + * @precond aField must be returned from this->CreateFieldLC or + * VPbkError::Panic(VPbkError::EInvalidContactField) panic is raised. + * @postcond this->Fields().FieldCount() == + * old(this->Fields().FieldCount()) + 1 + * @return The index of the new field in the field collection. + * @exception KErrAccessDenied if the contact can not be modified. + */ + virtual TInt AddFieldL(MVPbkStoreContactField* aField) =0; + + /** + * Removes a field from the contact. + * + * @param aIndex A zero-based index of the field to remove. + * @precond aIndex >= 0 && aIndex < FieldCount(). + * Panics with VPbkError::EInvalidFieldIndex. + * @precond The contact is not read-only otherwise panics with + * VPbkError::EInvalidAccessToReadOnlyContact. + * @postcond this->Fields().FieldCount() == + * old(this->Fields().FieldCount()) - 1 + */ + virtual void RemoveField(TInt aIndex) =0; + + /** + * Removes all the fields from the contact. + * + * @precond The contact is not read-only otherwise panics with + * VPbkError::EInvalidAccessToReadOnlyContact. + * @postcond this->Fields().FieldCount() == 0 + */ + virtual void RemoveAllFields() =0; + + /** + * Locks this contact for modification asynchronously. + * + * Once the observer is notified this contact is locked and cab + * be modified. + * + * @param aObserver The observer to call back when the operation + * completes. The observer will not be called if this + * function leaves. + * @exception KErrInUse If another asynchronous operation is + * already in progress. + * @exception KErrAccessDenied if the contact can not be modified. + */ + virtual void LockL(MVPbkContactObserver& aObserver) const =0; + + /** + * Saves the contact to its associated store asynchronously. + * + * LockL must have been called before commit if this is + * an existing contact. Otherwise ContactOperationFailed is called + * with KErrAccessDenied. + * + * @param aObserver The observer to call back when this operation + * completes. The observer will not be called if this + * function leaves. + * @exception KErrInUse If another asynchronous operation is already + * in progress. + * @exception KErrAccessDenied if the contact can not be modified. + */ + virtual void CommitL(MVPbkContactObserver& aObserver) const =0; + + /** + * Returns the identifiers of the groups that the contact + * belongs to. + * + * @return The groups that this contact belongs to. + */ + virtual MVPbkContactLinkArray* GroupsJoinedLC() const =0; + + /** + * Returns the group interface of the store contact if this contact + * is a group. + * If this contact is not a group, NULL is returned. + * + * @return The group interface or NULL. + */ + virtual MVPbkContactGroup* Group() =0; + + /** + * Returns the maximum amount of fields of given type that can be + * inserted to the contact. + * + * E.g. A USIM ADN contact can have 1 or more phone numbers but there + * is a limit that the store in USIM defines. + * On the other hand the contact in the Contacts Model data base + * doesn't have limits. + * + * @param aType The field type of the field + * @return The maximum amount fields of given type in the contact + * or KVPbkStoreContactUnlimitedNumber it there is no limit + * set by the store contact + */ + virtual TInt MaxNumberOfFieldL(const MVPbkFieldType& aType) 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* StoreContactExtension(TUid /*aExtensionUid*/) + { return NULL; } + + public: // from MVPbkBaseContact + /// Do not override + virtual TBool IsSame(const MVPbkBaseContact& aOtherContact) const + { + return aOtherContact.IsSame(*this); + } + + // Do not override + virtual TBool IsSame(const MVPbkViewContact& aOtherContact) const + { + return aOtherContact.IsSame(*this, &ContactStore()); + } + }; + + +// INLINE FUNCTIONS +inline void MVPbkStoreContact::PushL() + { + CleanupDeletePushL(this); + } + +#endif // MVPBKSTORECONTACT_H + +//End of file