/*
* 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:  
:                
*
*/



#ifndef SCVPBKSTORECONTACTFIELD_H
#define SCVPBKSTORECONTACTFIELD_H


// INCLUDES
#include <e32base.h>
#include <MVPbkStoreContactField.h>
#include <MVPbkFieldType.h>

// CONSTANTS


// CLASS DECLARATIONS

/**
 * An interface for the field of the store contact.
 *
 * Client can access the contact field using this interface. The field
 * can have a label and a data.
 *
 * A new field can be created using the MVPbkStoreContact interface.
 * For looping the contact fields see MVPbkStoreContactFieldCollection.
 * The parent of the field in the object hierarchy is the store contact.
 *
 * @see CVPbkContactFieldTypeIterator
 * @see CVPbkFieldTypeSelector
 */
class CVPbkStoreContactFieldStub : public CBase,
                               public MVPbkStoreContactField,
                               public MVPbkFieldType
    {
    public:  // ctor
    	CVPbkStoreContactFieldStub(TInt aIndex);
        /**
         * Destructor
         */
        ~CVPbkStoreContactFieldStub();

    public: // From MVPbkBaseContactField
        const MVPbkContactFieldData& FieldData() const ;

    public:  // New functions
        /**
         * Returns ETrue if the field supports label. 
         * 
         * Overwrites the global setting in MVPbkContactStoreProperties. 
         * This must be confirmed before using SetFieldLabelL or 
         * MaxLabelLength.
         * 
         * @return ETrue if the field supports label. Otherwise EFalse.
         */
        TBool SupportsLabel() const ;
        
        /**
         * Returns the label of the field or KNullDesC if there is no field 
         * label.
         *
         * @return The label of the field or KNullDesC
         */
        TPtrC FieldLabel() const ;

        /**
         * Sets this field's label.
         *
         * SupportsLabel must be true for using this.
         *
         * @param aText The label for the field.
         */
        void SetFieldLabelL( const TDesC& aText ) ;
        
        /**
         * Gets the maximum length of the label. 
         *
         * SupportsLabel must be true for using this.
         * 
         * @return The maximum length of the label or KVPbkUnlimitedLabelLength
         *         if the store has no limits. Zero should be returned in other
         *         cases though this shouldn't be called if labels are 
         *         not supported.
         */
        TInt MaxLabelLength() const ;

        /**
         * Returns the data storage (read-write) of the field. 
         *
         * The data type depends on the field and it's client's responsibility
         * to check the type before casting the type.
         *
         * @return The data storage of the field.
         * @see MVPbkContactFieldTextData::Cast
         * @see MVPbkContactFieldDateTimeData::Cast
         * @see MVPbkContactFieldBinaryData::Cast
         */
        MVPbkContactFieldData& FieldData() ;

        /**
         * Clones the field. 
         * 
         * Pushes the created copy to the cleanup stack.
         *
         * @return A copy of the field.
         * @see MVPbkStoreContactFieldCollection::FieldAt
         */
        MVPbkStoreContactField* CloneLC() const ;
        
        /**
         * Creates a link representing the contact and the field.
         *
         * The field can be later retrieved using the RetrieveField of
         * MVPbkStoreContactFieldCollection interface.
         *
         * NOTE: implementations of stores are possibly using an index
         *       of the field as an identifier so clients should prefer not
         *       to save field links permanently. E.g modifying the contact
         *       can invalidate the link in some store implementations.
         *       A field link is practical in use cases where the link is
         *       created and immediately given to another component.
         *
         * @return A link representing the contact and the field or NULL
         *         if the contact doesn't exist in the store. E.g a new
         *         contact that hasn't been committed has no unique
         *         identifier yet.
         *         NULL is not put into the CleanupStack.
         */
        MVPbkContactLink* CreateLinkLC() const ;


    public:  // Interface
        /**
         * Returns the parent contact where this field is from.
         *
         * @return The parent contact where this field is from.
         */
        MVPbkBaseContact& ParentContact() const ;

        /**
         * Returns this field's type or NULL if no mapping exists
         * between the native type and phonebook type.
         *
         * @param aMatchPriority    matching priority to use.
         * @return The field type or NULL
         * @postcond !FieldType(list) || list.ContainsSame(*FieldType(list))
         */
        const MVPbkFieldType* MatchFieldType(
                TInt aMatchPriority) const ;
        
        /**
         * Returns the best matching type of the field or NULL 
         * if no mapping exists between the native type and 
         * phonebook type. This is the same as looping 
         * MatchFieldType from priority 0 and getting the first 
         * matched type.
         *
         * @return The field type or NULL
         * @postcond !FieldType(list) || list.ContainsSame(*FieldType(list))
         */
        const MVPbkFieldType* BestMatchingFieldType() const ;

        

        /**
         * Returns true if this field is the same as another field in the
         * contact instance. 
         * Doesn't work for fields from different contact instances.
         * Always use this method instead of direct pointer comparison.
         *
         * @param aOther another field inside the contact
         * @return ETrue if contact is same
         */
        TBool IsSame(const MVPbkBaseContactField& aOther) const ;

        
public:  // New functions
        /**
         * Returns the parent object of this object. For the root of the 
         * hierarchy returns self.
         * @return The parent object.
         */
        MVPbkObjectHierarchy& ParentObject() const ;
        
		/**
         * Returns the Versit properties mapped to this field type.
         *
         * @return Versit properties.
         */
        TArray<TVPbkFieldVersitProperty> VersitProperties() const ;

        /**
         * Returns the Versit parameters fields of this type should not have.
         *
         * @return Excluded parameters.
         */
        const TVPbkFieldTypeParameters& ExcludedParameters() const ;

        /**
         * Type name for field types not supported by the Versit 2.1 standard.
         *
         * @return A non-Versit type.
         */
        TVPbkNonVersitFieldType NonVersitType() const ;

        /**
         * Returns true if this field type is the same as aOtherType.
         *
         * @param aOtherType The type to compare.
         * @return ETrue if the field types are the same.
         */
        TBool IsSame(
                const MVPbkFieldType& aOtherType ) const ;

        /**
         * Returns true if this field type matches a Versit property.
         *
         * @param aMatchProperty A versit property to match against.
         * @param aMatchPriority A matching priority. Priorities start
         *                       from zero which is the highest priority.
         *                       Priority is also a direct index to
         *                       VersitProperties() array.
         * @return ETrue if this field type matches aMatchProperty at
         *         aMatchPriority. Returns always false if 
         *         aMatchPriority >= VersitProperties().Count().
         */
        TBool Matches(
                const TVPbkFieldVersitProperty& aMatchProperty,
                TInt aMatchPriority ) const ;

        /**
         * Returns the field type resource id from VPbkEng.rsg
         * that be used to identify a type.
         *
         * @return A field type resource id.
         */
        TInt FieldTypeResId() const ;   
        
	private:
		TInt iIndex ;
        
    };

#endif  // SCVPBKSTORECONTACTFIELD_H
        
// End of file