/*

* Copyright (c) 2008 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:  Helper class to map Contacts Model fields

 *

*/

#ifndef CPIMCONTACTFIELDINFO_H

#define CPIMCONTACTFIELDINFO_H

// INTERNAL INCLUDES

#include "pimcommon.h"

#include "pimcontact.h"

// EXTERNAL INCLUDES

#include <e32std.h>

#include <cntdef.hrh>

// FORWARD DECLARATIONS

class CContentType;

/**

 * Helper clas to map fields between PIM API and Contacts

 * Model fields.

 */

NONSHARABLE_CLASS(CPIMContactFieldInfo) : public CBase

{

public: // Type definitions

    /**

     * Struct for mapping PIM field to a

     * Contacts Model field

     */

    struct TPIMFieldInfo

    {

public:

        // Constructor

        TPIMFieldInfo(TInt aContactsModelField,

        TPIMContactField aPIMField) :

                iPIMField(aPIMField),

                iSubElement(EPIMFieldInvalid),

                iContactsModelField(aContactsModelField)

        {}

        // Constructor with subelement

        TPIMFieldInfo(TInt aContactsModelField,

        TPIMContactField aPIMField,

        TInt aSubElement) :

                iPIMField(aPIMField),

                iSubElement(aSubElement),

                iContactsModelField(aContactsModelField)

        {}

        // PIM field id

        TPIMContactField iPIMField;

        // Sub field. e.g array element

        TInt iSubElement;

        // Contacts Model field id

        TInt iContactsModelField;

    };

public:

    /**

     * Two phase constructor

     * Returns an instance of this class

     */

    static CPIMContactFieldInfo* NewL();

    /**

     * Two phase constructor

     * Returns an instance of this class. The instance

     * is left to the cleanup stack

     */

    static CPIMContactFieldInfo* NewLC();

    /**

     * Destructor

     */

    ~CPIMContactFieldInfo();

public: // New functions

    /**

     * MatchContactField

     * Matches a Contacts Model field type to

     * PIM item contact field type

     *

     * @param aContactsModelFieldType Contacts Model field type

     * @return Matched PIM contact field

     */

    TPIMContactField MatchContactField(

        TInt aContactsModelFieldType) const;

    /**

     * MatchPIMField

     * Matches a PIM field to a Contacts Model field. Ownership of

     * the returned array is transferred to the caller

     *

     * @param aContactField PIM field

     * @return All matched fields with this PIM contact field.

     *         In addition, one PIM field may have array elements

     *         as sub elements

     */

    CArrayFix< TInt>* MatchPIMFieldL(TPIMContactField

                                     aContactField) const;

    /**

     * MatchContactNameElement

     * Matches a Contacts Model field type to PIM contact

     * name/address element. This function should be use when

     * the actual field type is known

     *

     * @param aContactModelFieldType Contacts Model field type

     * @return Matched PIM constact name/address field array element

     */

    TInt MatchContactArrayElement(TInt aContactsModelFieldType) const;

    /**

     * FieldAttributes

     * Returns the attributes of the specific Contacts Model

     * field.

     *

     * @param aContentType Content type from which to get attributes

     * @return Attributes of the passed content type

     */

    TPIMAttribute FieldAttributes(const CContentType& aContentType) const;

    /**

     * GetFieldInternalAttributesL

     * Returns the internal attributes of the specific Contacts Model

     * field.

     *

     * @param aContentType Content type from which to get attributes

     * @param aArrayOfAttributes Attributes array which fields will be added

     * @return Attributes of the passed content type

     */

    void GetFieldInternalAttributesL(

        const CContentType& aContentType,

        CArrayFix< TUid>& aArrayOfAttributes) const;

    /**

     * Creates a content type for a specific address element.

     *

     * @param aElement PIM Address field element

     * @param aCategory     Phonebook category for the field.

     *                      Values can be EContactCategoryNone,

     *                      EContactCategoryHome,

     *                      EContactCategoryWork or

     *                      EContactCategoryOther

     *

     * @return The requested Content Type. The ownership of the object

     *      is transferred to the caller. The object is left in the

     *      cleanup stack.

     *

     * @par Leaving:

     *      This leaves if theres an error with a system wide error code

     */

    CContentType* AddressContentTypeL(

        TPIMContactAddrElement aElement,

        EContactFieldCategory aCategory) const;

    /**

     * Creates a content type for a specific name element.

     *

     * @param aElement PIM Address field element

     *

     * @return The requested Content Type. The ownership of the object

     *      is transferred to the caller.

     *

     * @par Leaving:

     *      This leaves if theres an error with a system wide error code

     */

    CContentType* NameContentTypeL(TPIMContactNameElement aElement) const;

    /**

     * Creates a content type for a specific string field

     *

     * @param aContactField Contact field which Content Type

     *        is to be created

     * @param aAttributes Attributes of this field

     * @param aCaterory Category of this field. In return, contains

     *        new category if modification is needed

     * @return The requested Content Type. The ownership is transferred

     *         to the caller

     */

    CContentType* StringFieldContentTypeL(

        const TPIMContactField aContactField,

        const TPIMAttribute aAttributes,

        EContactFieldCategory& aCategory) const;

private:

    /**

     * Default C++ constructor

     */

    inline CPIMContactFieldInfo();

    /**

     * Second phase constructor

     */

    void ConstructL();

private: // Data

    // Array holding fields info

    CArrayFix< TPIMFieldInfo>* iFieldsInfo;

};

#endif // CPIMCONTACTFIELDINFO_H

// End of file