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 <e32base.h>
williamr@4: #include <mvpbkbasecontact.h>
williamr@4: #include <mvpbkviewcontact.h>
williamr@4: 
williamr@4: // Includes needed for covariant return types
williamr@4: #include <mvpbkstorecontactfieldcollection.h>
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