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