/*
* 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 field types collection class
*
*/



#ifndef __CPbkFieldsInfo_H__
#define __CPbkFieldsInfo_H__

//  INCLUDES
#include <e32base.h>
// This include is not absolutely needed,  but this class is very rarely used 
// without class CPbkFieldInfo.
#include "CPbkFieldInfo.h"

//  FORWARD DECLARATIONS
class CContactItem;
class CContactItemField;
class CContactItemViewDef;
class RResourceFile;
class CPbkUidMap;
class CPbkFieldInfo;
class CPbkFieldInfoGroup;
class MPbkVcardProperty;
class TPbkMatchPriorityLevel;


//  CLASS DECLARATION 

/**
 * Phonebook field types collection class. The collection contains 
 * CPbkFieldInfo objects that contain Phonebook specific field type
 * information. Each field Phonebook recognizes is associated with 
 * field info object. The field info objects are references to elements
 * in this array.
 */
class CPbkFieldsInfo : 
        public CBase
	{
	public: // interface
        /**
         * Creates and returns an instance of this class intialised from 
         * resources.
         * 
         * @param aPbkResFile       Phonebook's resource file.
         * @param aCntModelResFile  Contact Model's resource file.
         */
        static CPbkFieldsInfo* NewL
            (RResourceFile& aPbkResFile, RResourceFile& aCntModelResFile);

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

        /**
         * Search field info by Phonebook field id.
         *
         * @param aFieldId  Phonebook field id to search from the array
         * @return  The <it>first</it> (there may be several that match) field 
         *          info object in the field UI presentation order matching 
         *          aFieldId. Returns NULL if no match is found.
         */
        IMPORT_C CPbkFieldInfo* Find(TPbkFieldId aFieldId) const;

        /**
         * Search field info by Phonebook field id and location
         *
         * @param aFieldId   Phonebook field id to search from the array
         * @param aLocation  Field location (home/work/none) to search from the array
         * @return  The field info object (there should be only one) matching 
         *          aFieldId and aLocation. NULL if no match found.
         */
        IMPORT_C CPbkFieldInfo* Find
			(TPbkFieldId aFieldId, TPbkFieldLocation aLocation) const;

        /**
         * Search a field info matching contact model field.
         *
         * @param aContactItemField Contact item field whose match is searched
         *                          from all field info objects.
         * @return  The field info object matching aContactItemField. NULL if 
         *          no match is found.
         */
        IMPORT_C CPbkFieldInfo* Find
			(const CContactItemField& aContactItemField) const;

        /**
         * @internal Only Phonebook internal use is supported!
         * Creates and returns an initialized matching priority level object.
         * @deprecated
         */
        IMPORT_C TPbkMatchPriorityLevel CreateMatchPriority() const;

        /**
         * @internal Only Phonebook internal use is supported!
         * Searches a match for a contact model field.
         *
         * @param aContactItemField Contact item field whose match is searched
         *                          from all field info objects.
         * @param aMatchPriority    Priority to match against. Only import
         *                          types of this priority are checked.
         * @return  A match information object.
         * @deprecated
         */
        CPbkFieldInfo* Match
            (const CContactItemField& aContactItemField,
            const TPbkMatchPriorityLevel& aMatchPriority) const;

        /**
         * @internal Only Phonebook internal use is supported!
         * Searches a match for a vCard property.
         *
         * @param aVcardProperty    vCard property to search for a match from 
         *                          all field info objects.
         * @param aMatchPriority    Priority to match against. Only import
         *                          types of this priority are checked.
         * @return  A match information object.
         * @deprecated
         */
        IMPORT_C CPbkFieldInfo* Match
            (const MPbkVcardProperty& aVcardProperty,
            const TPbkMatchPriorityLevel& aMatchPriority) const;
        
        /**
         * Returns the count of field infos.
         * @return The count of field information elements in this container.
         */
        IMPORT_C TInt Count() const;

        /**
         * Returns the aIndex:th field info. Field info objects are sorted by
         * the field presentation ordering.
         * @param aIndex    The indexed element in this array.
         * @return The element in the indexed position in the array.
         */
        IMPORT_C CPbkFieldInfo* operator[](TInt aIndex) const;

        /**
         * Returns the count of field info groups.
         * @return The count of field info groups.
         */
        IMPORT_C TInt GroupCount() const;

        /**
         * Returns the field info group at aIndex.
         * @return The field info group at aIndex.
         */
        IMPORT_C const CPbkFieldInfoGroup& GroupAt(TInt aIndex) const;

        /**
         * Creates a contact item view definition from an array of Phonebook 
         * field ids.
         *
         * @param aFieldTypes   Array of Phonebook field types.
         * @return A new contact item view definition.
         */
        IMPORT_C CContactItemViewDef* CreateContactItemViewDefLC
            (const CPbkFieldIdArray& aFieldTypes) const;

        /**
         * Creates contact item field definition from an array of Phonebook 
         * field ids.
         *
         * @param aFieldTypes   Phonebook field types to add into the returned
         *                      array. If NULL an array matching all fields is
         *                      returned.
         * @return  A field def array matching <it>at least fields</it> in 
         *          aFieldTypes. Please note that the returned field definition
         *          may also match other fields than those specified.
         */
        IMPORT_C CContactItemFieldDef* CreateContactItemFieldDefLC
            (const CPbkFieldIdArray* aFieldTypes) const;

        /**
         * Adds fields from resource readers. Doesn't read or link group
         * information.
         * @param aPbkResReader Initialized resource buffer 
         *                      to PHONEBOOK_FIELD_ARRAY
         * @param aCntModelResReader Initialized resource buffer to 
         *                           ARRAY or FIELDs
         * @param aAddedFieldTypes  If not null the field types that were 
         *                          added are appended to this array. The field
         *                          types are in the order they were defined in
         *                          resources.
         */
        void AddFieldTypesFromResourceL
            (TResourceReader& aPbkResReader, 
            TResourceReader& aCntModelResReader,
            RArray<const CPbkFieldInfo*>* aAddedFieldTypes);

    private:  // Implementation
        CPbkFieldsInfo();
        CPbkFieldInfoGroup* FindGroup(TPbkFieldGroupId aGroupId);
        void LinkGroupsL();
        void ReadGroupsInfoL(RResourceFile& aResFile);
        void ConstructFromResourceL
            (RResourceFile& aPbkResFile, RResourceFile& aCntModelResFile);
        void ReadFieldInfoParamsL();

    private: // data
        /// Own: array of field infos
        RPointerArray<CPbkFieldInfo> iEntries;
        /// Own: field info groups
        RPointerArray<CPbkFieldInfoGroup> iGroups;
        /// Own: UID map for field content type matching
        CPbkUidMap* iTypeUidMap;
        /// Own: highest field matching priority level
        TInt iHighestMatchPriorityLevel;
        /// Own: configuration data for field infos
        CPbkFieldInfo::TPbkFieldInfoParams* iPbkFieldInfoParams;
    };

#endif // __CPbkFieldsInfo_H__

// End of File