/*

* 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