/*
* Copyright (c) 2002 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: 
*     Phonebook Contact item class.
*
*/


#ifndef __CPbkContactItem_H__
#define __CPbkContactItem_H__

//  INCLUDES
#include <e32base.h>        // CBase, CArrayFixFlat
#include "MPbkFieldData.h"  // MPbkFieldDataArray
#include "PbkFields.hrh"    // TPbkFieldId
#include "TPbkContactItemField.h"

// FORWARD DECLARATIONS
class CPbkFieldsInfo;
class CPbkFieldInfo;
class CContactItemField;
class CContactItem;
class MPbkContactNameFormat;


// CLASS DECLARATION

/**
 * Array of TPbkContactItemField instances.
 */
class CPbkFieldArray : public CArrayFixFlat<TPbkContactItemField>
    {
    public:
        enum
            {
            /// Default array reallocation granularity
            KDefaultGranularity = 8
            };

        /** 
         * Constructor.
         */
        inline CPbkFieldArray() 
            : CArrayFixFlat<TPbkContactItemField>(KDefaultGranularity)
            {
            }

        /**
         * Constructor.
         * @param aGranularity  Reallocation granularity of this array.
         */
        inline CPbkFieldArray(TInt aGranurality) 
            : CArrayFixFlat<TPbkContactItemField>(aGranurality)
            {
            }
    };


/**
 * Phonebook Contact item class. Contact items can be read from the contact
 * database by using the Phonebook engine, @see CPbkContactEngine.
 * This class extends Symbian Contacts model class CContactItem capabilities 
 * to better suit Phonebook application's needs.
 */
class CPbkContactItem : 
        public CBase, public MPbkFieldDataArray
    {
    public:  // Constructor and destructor
        /**
         * Creates an instance of this class.
         *
         * @param aItem         Contact item this object wraps. This object 
         *                      takes ownership of aItem. If this function 
         *                      leaves, ownership is not taken.
         * @param aFieldsInfo   Collection of Phonebook field types.
         * @param aNameFormat   Contact name formatter.
         * @return  A new instance of this class.
         */
        IMPORT_C static CPbkContactItem* NewL(
                CContactItem* aItem, 
                const CPbkFieldsInfo& aFieldsInfo, 
                MPbkContactNameFormat& aNameFormat);

        /**
         * Destructor.
         */
        ~CPbkContactItem();

    public: // CContactItem functions
        /**
         * Returns this contact item's id.
         * @see CContactItem::Id()
         */
        IMPORT_C TContactItemId Id() const;
        
        /**
         * Returns type of this contact item. The contact types are documented in
         * the Symbian Contacts model CContactItem::Type().
         * @return Contact type.
         * @see CContactItem::Type()
         */
        IMPORT_C TUid Type() const;

        /**
         * Gets the groups this contact belongs to.
         * @return Array of group ids. Caller owns the array.
         * @see CContactItem::GroupsJoinedLC()
         */
        IMPORT_C CContactIdArray* GroupsJoinedLC() const;

        /**
         * Converts this object to a CContactItem. Use only if this class's API
         * is not enough.
         * @return  The underlying Symbian Contacts model contact item object.
         */
        IMPORT_C CContactItem& ContactItem();

        /**
         * Converts this object to a const CContactItem. Use only if this 
         * class's API is not enough.
         * @return  The underlying Symbian Contacts model contact item object.
         */
        IMPORT_C const CContactItem& ContactItem() const;

    public:  // Field set operations
        /**
         * Returns the field set of this contact item.
         * @return  Field array of this contact item.
         */
        IMPORT_C CPbkFieldArray& CardFields() const;

        /**
         * Creates a new field based on aFieldInfo and adds it to this contact.
         *
         * @param aFieldInfo    Type of field to create.
         * @return The created field.
         */
      	IMPORT_C TPbkContactItemField& AddFieldL(CPbkFieldInfo& aFieldInfo);

        /**
         * Returns ETrue if data of type aFieldInfo can be added to this 
         * contact.
         * @param aFieldInfo    The field type that we are trying to add.
         * @return  ETrue if the contact can accept this type of data, EFalse
         *          otherwise.
         */
        IMPORT_C TBool CanAcceptDataOfType(CPbkFieldInfo& aFieldInfo) const;

        /**
         * Finds an unused or creates a new field based on aFieldInfo. An 
         * unused field is a field that is in the contact template, but
         * doesnt contain any data, in other words it is empty. So a unused 
         * field is preferred ad the next field to add user data before 
         * adding a new field to the contact.
         *
         * @param aFieldInfo    Type of field to search or create.
         * @return  Pointer to the found or created field. NULL only if<br>
         *          field exists AND <br>
         *          field is nonempty AND <br>
         *          aFieldInfo.Multiplicity()==EPbkFieldMultiplicityOne.
         */
      	IMPORT_C TPbkContactItemField* AddOrReturnUnusedFieldL
            (CPbkFieldInfo& aFieldInfo);

        /**
         * Deletes field at aIndex.
         * @param aIndex    Field index to delete from the contact item.
         */
        IMPORT_C void RemoveField(TInt aIndex);

        /**
         * Updates this contacts field set to match the field set of
         * the owned CContactItem. No need to call unless contact item's
         * field set has been manipulated directly. In other words 
         * remaps the field types of this contact item from the underlying
         * Symbian Contacts model contact item.
         * @param aFieldsInfo   The new fields set for this contact.
         */
        IMPORT_C void UpdateFieldSetL(const CPbkFieldsInfo& aFieldsInfo);

    public:  // Field searching
        /**
         * Returns first field matching aFieldId.
         *
         * @param aFieldId  Field id to search.
         * @return First field matching aFieldId, NULL if none found.
         */
        IMPORT_C TPbkContactItemField* FindField(TPbkFieldId aFieldId) const;

        /**
         * Returns first field matching aFieldId starting from aIndex.
         *
         * @param aFieldId  Field id to search.
         * @param aIndex    Input: field index where to start the search from,
         *                  output: index of the found field or -1 if not found.
         * @return Field matching aFieldId, NULL if none found.
         */
        IMPORT_C TPbkContactItemField* FindField
            (TPbkFieldId aFieldId, TInt& aIndex) const;

        /**
         * Returns first field matching aFieldInfo.
         *
         * @param aFieldInfo    Field type to find from the contact.
         * @return First field matching aFieldInfo, NULL if none found.
         */
        IMPORT_C TPbkContactItemField* FindField(const CPbkFieldInfo& aFieldInfo) const;

        /**
         * Returns first field matching aFieldInfo starting from aIndex.
         *
         * @param aFieldInfo    Field type to find from the contact.
         * @param aIndex    Input: field index where to start the search from,
         *                  output: index of the found field or -1 if not found.
         * @return Field matching aFieldInfo, NULL if none found.
         */
        IMPORT_C TPbkContactItemField* FindField
            (const CPbkFieldInfo& aFieldInfo, TInt& aIndex) const;

        /**
         * Returns aField's index from this contact item.
         *
         * @param aField    Field to search for. Field is matched with 
         *                  TPbkContactItemField::IsSame -function.
         * @return  Index of aField in this contact item's field set, 
         *          KErrNotFound if not found.
         * @see TPbkContactItemField::IsSame
         */
        IMPORT_C TInt FindFieldIndex(const TPbkContactItemField& aField) const;

        /**
         * Returns aField's index from ContactItem()'s CardFields() or 
         * KErrNotFound if not found.
         * @param aField    The field which index we are querying.
         * @return The fields index in this contact item, KErrNotFound is not found.
         */
        IMPORT_C TInt FindContactItemFieldIndex(const CContactItemField& aField) const;

        /**
         * Searches phone number fields of this contact for a match.
         * Uses PbkEngUtils::ContainSameDigits to perform the matching.
         *
         * @param aNumber   Phone number to match to.
         * @param aNumberOfDigits   Number of digits to compare from the end 
         *                          of the phone numbers. Full comparison
         *                          performed if 0.
         * @param aIndex    Input: field index where to start the search from,
         *                  output: index of the found field or KErrNotFound if not found.
         * @return The matching field, NULL if not found.
         * @see PbkEngUtils::ContainSameDigits
         */
        IMPORT_C TPbkContactItemField* FindNextFieldWithPhoneNumber
            (const TDesC& aNumber,
            TInt aNumberOfDigits,
            TInt &aIndex) const;

        /**
         * Searches for a text in this contact's fields. Uses TDesC::FindF()
         * search the text from the fields.
         *
         * @param aIndex    Input: field index from where to start the search,
         *                  Output: index of the found field or KErrNotFound 
         *                  if not found.
         * @return The matching field, NULL if not found.
         * @see TDesC::FindF
         */
        IMPORT_C TPbkContactItemField* FindNextFieldWithText
            (const TDesC& aText,
            TInt& aIndex) const;

        /**
         * Returns field matching aField from this contact item's field set, NULL if
         * not found.
         * @param aField    The field that we a mathing.
         * @return  Matching field or NULL if not found.
         * @postcond !FindSameField(field) || FindSameField(field)->IsSame(field)
         */
        IMPORT_C TPbkContactItemField* FindSameField
            (const TPbkContactItemField& aField) const;

    public: // Contact presentation
        /**
         * Gets a title text for this contact or localized unnamed text.
         *
         * @return  A buffer containing the title or localized unnamed text if no
         *          title can be generated. Caller is responsible for deleting 
         *          the returned buffer.
         */
        IMPORT_C HBufC* GetContactTitleL() const;

        /**
         * Gets a title text for this contact.
         *
         * @return  A buffer containing the title text, NULL if title is empty.
         *          Caller is responsible for deleting the returned buffer.
         */
        IMPORT_C HBufC* GetContactTitleOrNullL() const;

        /**
         * Returns an Phonebook icon id for a contact. This icon id is the icon
         * of the field that is set as the default number to call.
         *
         * @return  Icon index for this contact, EPbkNullIconId for no icon.
         */
        IMPORT_C TPbkIconId ContactIconIdL() const;

    public:  // Defaults
        /**
         * Returns the default phone number field of this contact.
         *
         * @return  Default phone number field of this contact, 
         *          NULL if no default set.
         */
        IMPORT_C TPbkContactItemField* DefaultPhoneNumberField() const;

        /**
         * Sets this contact's default phone number field to aField.
         *
         * @param aField    Field to set as default, if NULL phone number
         *                  default is removed. Guaranteed not to leave if
         *                  aField is NULL.
         * @exception KErrNotFound  If aField is not this contact's field.
         * @exception KErrNotSupported  If aField is not a phone number field.
         */
        IMPORT_C void SetDefaultPhoneNumberFieldL
            (TPbkContactItemField* aField);

        /**
         * Removes phone number default from this contact.
         *
         * @postcond DefaultPhoneNumberField()==NULL.
         */
        IMPORT_C void RemoveDefaultPhoneNumberField();

        /**
         * Returns the default video number field of this contact.
         *
         * @return  Default video number field of this contact, 
         *          NULL if no default set.
         */
        IMPORT_C TPbkContactItemField* DefaultVideoNumberField() const;

        /**
         * Sets this contact's default video number field to aField.
         *
         * @param aField    Field to set as default, if NULL video number
         *                  default is removed. Guaranteed not to leave if
         *                  aField is NULL.
         * @exception KErrNotFound  if aField is not this contact's field.
         * @exception KErrNotSupported  if aField is not a phone number field.
         */
        IMPORT_C void SetDefaultVideoNumberFieldL
            (TPbkContactItemField* aField);

        /**
         * Removes video number default from this contact.
         *
         * @postcond DefaultVideoNumberField()==NULL.
         */
        IMPORT_C void RemoveDefaultVideoNumberField();

        /**
         * Returns the default SMS field of this contact.
         *
         * @return  Default SMS field of this contact, 
         *          NULL if no default set.
         */
        IMPORT_C TPbkContactItemField* DefaultSmsField() const;

        /**
         * Sets this contact's default SMS field to aField.
         *
         * @param aField    Field to set as default, if NULL SMS
         *                  default is removed. Guaranteed not to leave if
         *                  aField is NULL.
         * @exception KErrNotFound  if aField is not this contact's field.
         * @exception KErrNotSupported  if aField is not a phone number field.
         */
        IMPORT_C void SetDefaultSmsFieldL(TPbkContactItemField* aField);

        /**
         * Removes SMS field default from this contact.
         *
         * @postcond DefaultSmsField()==NULL.
         */
        IMPORT_C void RemoveDefaultSmsField();

        /**
         * Returns the default email field of this contact.
         *
         * @return  Default email field of this contact, 
         *          NULL if no default set.
         */
        IMPORT_C TPbkContactItemField* DefaultEmailField() const;

        /**
         * Sets this contact's default email address field to aField.
         *
         * @param aField    Field to set as default, if NULL email 
         *                  default is removed. Guaranteed not to leave if
         *                  aField is NULL.
         * @exception KErrNotFound  If aField is not this contact's field.
         * @exception KErrNotSupported  If aField is not an email field.
         */
        IMPORT_C void SetDefaultEmailFieldL(TPbkContactItemField* aField);

        /**
         * Removes email field default from this contact.
         *
         * @postcond DefaultEmailField()==NULL.
         */
        IMPORT_C void RemoveDefaultEmailField();

        /**
         * Returns the default Mms field of this contact.
         *
         * @return  Default Mms field of this contact, 
         *          NULL if no default set.
         */
        IMPORT_C TPbkContactItemField* DefaultMmsField() const;

        /**
         * Sets this contact's default MMS address field to aField.
         *
         * @param aField    Field to set as default, if NULL MMS 
         *                  default is removed. Guaranteed not to leave if
         *                  aField is NULL.
         * @exception KErrNotFound  If aField is not this contact's field.
         * @exception KErrNotSupported  If aField is not an email field.
         */
        IMPORT_C void SetDefaultMmsFieldL(TPbkContactItemField* aField);

        /**
         * Removes MMS field default from this contact.
         *
         * @postcond DefaultMmsField()==NULL.
         */
        IMPORT_C void RemoveDefaultMmsField();

        /**
         * Returns the default Poc field of this contact.
         *
         * @return  Default Poc field of this contact, 
         *          NULL if no default set.
         */
        IMPORT_C TPbkContactItemField* DefaultPocField() const;

        /**
         * Sets this contact's default POC address field to aField.
         *
         * @param aField    Field to set as default, if NULL POC 
         *                  default is removed. Guaranteed not to leave if
         *                  aField is NULL.
         * @exception KErrNotFound  If aField is not this contact's field.
         * @exception KErrNotSupported  If aField is not an email field.
         */
        IMPORT_C void SetDefaultPocFieldL(TPbkContactItemField* aField);

        /**
         * Removes POC field default from this contact.
         *
         * @postcond DefaultPocField()==NULL.
         */
        IMPORT_C void RemoveDefaultPocField();
        
        /**
         * Returns the default VOIP field of this contact.
         *
         * @return  Default VOIP field of this contact, 
         *          NULL if no default set.
         */
        IMPORT_C TPbkContactItemField* DefaultVoipField() const;

        /**
         * Sets this contact's default VOIP address field to aField.
         *
         * @param aField    Field to set as default, if NULL VOIP 
         *                  default is removed. Guaranteed not to leave if
         *                  aField is NULL.
         * @exception KErrNotFound  If aField is not this contact's field.
         * @exception KErrNotSupported  If aField is not an email field.
         */
        IMPORT_C void SetDefaultVoipFieldL(TPbkContactItemField* aField);

        /**
         * Removes VOIP field default from this contact.
         *
         * @postcond DefaultVoipField()==NULL.
         */
        IMPORT_C void RemoveDefaultVoipField();
        
        /**
         * Returns the default EmailOverSms field of this contact.
         *
         * @return  Default EmailOverSms field of this contact, 
         *          NULL if no default set.
         */
        IMPORT_C TPbkContactItemField* DefaultEmailOverSmsField() const;
        
        /**
         * Sets this contact's default Sms With Email address field to aField.
         *
         * @param aField    Field to set as default, if NULL Sms With Email 
         *                  default is removed. Guaranteed not to leave if
         *                  aField is NULL.
         * @exception KErrNotFound  If aField is not this contact's field.
         * @exception KErrNotSupported  If aField is not an email field.
         */
        IMPORT_C void SetDefaultEmailOverSmsFieldL(TPbkContactItemField* aField);
        
        /**
         * Removes EmailOverSms field default from this contact.
         *
         * @postcond DefaultEmailOverSmsField()==NULL.
         */
        IMPORT_C void RemoveDefaultEmailOverSmsField();

    public:  // Voice tags
        /**
         * Returns the voice tag field of this contact.
         * NOTE: If this function is unable to make a connection to 
         * the voice tag handling system for some reason, this function will 
         * return null.
         *
         * @return  Voice tag field of this contact, 
         *          NULL if no voice tag set.
         * @deprecated
         */
        IMPORT_C TPbkContactItemField* VoiceTagField() const;

        /**
         * Sets this contact's voice tag field to aField.
         *
         * @param aField    Field to set as default, if NULL voice tag mark
         *                  is removed. Guaranteed not to leave if
         *                  aField is NULL.
         * @exception KErrNotFound  If aField is not this contact's field.
         * @exception KErrNotSupported  If aField is not a phone number field.
         * @postcond (aField && VoiceTagField()->IsSame(*aField)) || (!aField && !VoiceTagField())
         * @deprecated
         */
        IMPORT_C void SetVoiceTagFieldL(TPbkContactItemField* aField);

        /**
         * Removes any voice tag mark from this contact.
         *
         * @postcond VoiceTagField()==NULL.
         * @deprecated
         */
        IMPORT_C void RemoveVoiceTagField();

    public:  // from MPbkFieldDataArray
        TInt PbkFieldCount() const;
        MPbkFieldData& PbkFieldAt(TInt aIndex);
        const MPbkFieldData& PbkFieldAt(TInt aIndex) const;

    public: // Phonebook internal functions, do not call
        /**
         * @internal
         * Prepares this contact for saving into the contact database.
         * @see PrepareAfterLoad
         * @deprecated
         */
        void PrepareForSaveL();

        /**
         * @internal
         * Prepares this contact after loading it from the contact database.
         * @see PrepareForSaveL
         * @deprecated
         */
        void PrepareAfterLoadL();
        
    private: // Implementation
        CPbkContactItem(MPbkContactNameFormat& aNameFormat);
        void ConstructL(CContactItem* aItem, const CPbkFieldsInfo& aFieldsInfo);
        void CreateFieldArrayL(CContactItem& aContactItem, const CPbkFieldsInfo& aFieldsInfo);
        TInt InsertionPos(const TPbkContactItemField& aField) const;
        __DECLARE_TEST;
        typedef CPbkContactItem SelfType;

    private:    // Data
        /// Own: Embedded contact item.
        CContactItem* iItem;
        /// Own: array of phonebook contact item fields
        CPbkFieldArray iFields;
        /// Ref: Contact name formatting API
        MPbkContactNameFormat& iNameFormat;

    private:  // Friend declarations
        friend IMPORT_C TBool operator==
            (const CPbkContactItem& aLeft, const CPbkContactItem& aRight);
    };


// FUNCTION DECLARATIONS

/**
 * Returns ETrue if aLeft and aRight contents are the same.
 */
IMPORT_C TBool operator==
    (const CPbkContactItem& aLeft, const CPbkContactItem& aRight);

/**
 * Returns ETrue if aLeft and aRight contents differ.
 */
inline TBool operator!=
    (const CPbkContactItem& aLeft, const CPbkContactItem& aRight)
    {
    return !(aLeft==aRight);
    }


#endif // __CPbkContactItem_H__
            
// End of File