/*
* 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:  Handles conversion between PIM API Contact Items and Contacts
 *                Model Contact Cards.
 *
*/


#ifndef CPIMCONTACTITEMADAPTER_H
#define CPIMCONTACTITEMADAPTER_H

// INTERNAL INCLUDES
#include "pimcommon.h"
#include "pimcontact.h"

// EXTERNAL INCLUDES
#include <e32base.h>
#include <badesca.h>
#include <cntdef.h>

// CONSTANTS

/** Maximum lengths of address elements in S60 */
const TInt KContactAddrElemMaxLengths[EPIMContactAddrNumElements] =
{
    20, // P.O.Box
    50, // Extra/Extension
    50, // Street
    50, // City
    50, // State/Region
    20, // Postal code
    50 // Country
};

/** Maximum lengths of name elements in S60 */
const TInt KContactNameElemMaxLengths[EPIMContactNameNumElements] =
{
    50, // Family/surname
    50, // Given/First name
    50, // Other
    10, // Prefix
    10, // Suffix
    50, // Family name reading
    50 // Given name reading
};

/**
 * Maximum lengths of standard string field values in S60.
 * An offset to the table is found by substracting
 * KContactStringMaxLengthsOffset from a field id.
 */
const TInt KContactStringMaxLengths[] =
{
    KErrNotFound, // EPIMContactAddr
    KErrNotFound, // EPIMContactBirthday
    KErrNotFound, // EPIMContactClass
    150, // EPIMContactEmail
    KErrNotSupported, // EPIMContactFormattedAddr
    KErrNotSupported, // EPIMContactFormattedName
    KErrNotFound, // EPIMContactName
    50, // EPIMContactNickname
    1000, // EPIMContactNote
    50, // EPIMContactOrg
    KErrNotFound, // EPIMContactPhoto
    KErrNotFound, // EPIMContactPhotoUrl
    KErrNotSupported, // EPIMContactPublicKey
    KErrNotSupported, // EPIMContactPublicKeyString
    KErrNotFound, // EPIMContactRevision
    48, // EPIMContactTel
    50, // EPIMContactTitle
    KErrNotFound, // EPIMContactUid
    1000 // EPIMContactUrl
};

const TInt KContactStringMaxLengthsOffset = 100;
const TInt KContactStringMaxLengthsLen = sizeof(KContactStringMaxLengths)
        / sizeof(TInt);

/**
 * Maximum lengths of extended string field values in S60.
 */
const TInt KContactExtStringMaxLengths[] =
{
    50, // Extended WV user ID
    100, // Extended SIP
    60, // Extended DTFM
    50, // Extended Department
    50, // Extended Assistant name
    50, // Extended Children
    50, // Extended Spouse
    KErrNotFound, // Extended Anniversary
    100, // Extended VOIP
    100, // Extended PTT
    100 // Extended SWIS
};

const TInt KContactExtStringMaxLengthOffset = 0x1005001;
const TInt KContactExtStringMaxLengthsLen = sizeof(KContactExtStringMaxLengths)
        / sizeof(TInt);

// FORWARD DECLARATIONS
class CPIMContactCategoryManager;
class CContactCard;
class CViewContact;
class RContactViewSortOrder;
class MPIMContactItem;
class MPIMItemData;
class CContentType;
class CContactItemField;
class CPIMImageScaler;
class CPIMContactFieldInfo;

// CLASS DECLARATION

/**
 * Contact Item Adapter
 * Converts Contact Items from PIM representation to Contacts Model
 * representation and vice versa.
 */
NONSHARABLE_CLASS(CPIMContactItemAdapter): public CBase
{
public: // Constructor and destructor
    /**
     * Two-phased constructor.
     */
    static CPIMContactItemAdapter* NewL(
        CPIMContactCategoryManager& aCategoryManager);

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

public: // new methods
    /**
     * Converts from a PIM item data to a Contacts Model contact card.
     *
     * @param aItem The item to convert
     *
     * @return A contact card with the same information as given in
     *         the parameter item. The \b ownership of the card is
     *         transferred to the caller.
     *
     * @par Leaving:
     * This leaves on an error with system wide error codes.
     * @par NOTE!
     * The debug version of this method panics if the item contains
     * unsupported fields!
     */
    CContactCard* CardL(const MPIMContactItem& aItem);

    /**
     * Converts from a Contacts Model contact card to the PIM
     * representation.
     *
     * @param aItem Item data container to fill with the data
     * @param aCard Contact card to convert
     *
     * @par Leaving:
     *  - KErrNotFound: The contact belongs to a group which either does not
     *                  exist, or does not have a label. In other words, the
     *                  database has been corrupted.
     *  - This method may also leave with other system wide error codes.
     */
    void FillItemL(MPIMContactItem& aItem, const CContactCard& aCard);


    /**
     * Updates the data in the Contacts Model contact card to match
     * the data in the PIM item data container.
     *
     * @param aItem Item from which the data is read
     * @param aCard The card which is updated
     *
     * @par Leaving:
     * This leaves on an error with system wide error codes.
     * @par NOTE!
     * The debug version of this method panics if the item contains
     * unsupported fields!
     */
    void UpdateCardL(const MPIMContactItem& aItem,
                     CContactCard& aCard);

    /**
     * Updates the category information in the database.
     *
     * @param aItem Item which contains the category information which
     *              is used in the update.
     * @param aCard the card which is updated.
     *
     * @par Leaving:
     *  - KErrNotFound: There is something fishy about the groups in the
     *                  database.
     */
    void UpdateCategoriesL(const MPIMContactItem& aItem,
                           const CContactCard& aCard);

    /**
     * Returns Contacts model field which is mapped to the PIM contact
     * field. Ownership of the returned array is transferred to the caller
     *
     * @return Mapped Contacts Model fields
     */
    CArrayFix< TInt>* ContactsModelFieldTypeL(
        TPIMContactField aContactField) const;

private:
    /**
     * C++ constructor.
     */
    CPIMContactItemAdapter(CPIMContactCategoryManager& aCategoryManager);

    /**
     * Symbian 2nd phase constructor.
     */
    void ConstructL();

    /**
     * Deletes all the supported fields from the contact card.
     * Those fields which are not supported are left as is.
     *
     * @param aCard The card which is cleaned
     *
     */
    void CleanCard(CContactCard& aCard);

    /**
     * Checks if we support this particular contact field.
     *
     * @param aField The field which is checked
     *
     * @return ETrue if the field is supported, EFalse otherwise
     *
     */
    TBool IsSupportedField(CContactItemField& aField);

    /**
     * Converts a field from a PIM Item to a Contact Card.
     *
     * @param aItem item to read the field from
     * @param aCard card to write the field to
     * @param aField field to convert
     *
     * @par Leaving:
     * This method leaves on error with system wide error codes.
     * @par NOTE!
     * The debug version of this method panics if the field is unsupported!
     */
    void ConvertFieldL(const MPIMContactItem& aItem,
                       CContactCard& aCard,
                       TPIMContactField aField);

    /**
     * Converts a field from a Contact Card to a PIM Item
     *
     * @param aField field to read the data from
     * @param aItem item to write the data to
     *
     * @par Leaving:
     * This method leaves on an error with system wide error codes.
     */
    void ConvertFieldL(const CContactItemField& aField,
                       MPIMContactItem& aItem);

    /**
     * Converts a text field from a Contact Card to a PIM Item
     *
     * @param aField field to read the data from
     * @param aItem item to write the data to
     *
     * @par Leaving:
     * This method leaves on error with system wide error codes
     */
    void ConvertTextFieldL(const CContactItemField& aField,
                           MPIMContactItem& aItem);

    /**
     * Adds a string field to the item, and optionally sets the
     * fields label.
     *
     * @param aItem item to which the string field is added
     * @param aField field type
     * @param aAttributes attributes of the field to be added
     * @param aInternalAttributes Internal attributes of the field
     * @param aValue value to be added. Ownership gets transferred
     *        to the item.
     * @param aLabel label to be set. NULL if default label is to
     * be used. Ownership gets transferred.
     */
    void AddStringFieldWithLabelL(
        MPIMItemData& aItem,
        TPIMField aField,
        TPIMAttribute aAttributes,
        CArrayFix< TUid>* aInternalAttributes,
        const TPtrC aValue,
        const TPtrC aLabel);

    /**
     * Converts a date field from a Contact Card to a PIM Item
     *
     * @param aField field to read the data from
     * @param aItem item to write the data to
     *
     * @par Leaving:
     * This method leaves on error with system wide error codes
     */
    void ConvertDateFieldL(const CContactItemField& aField,
                           MPIMContactItem& aItem);

    /**
     * Converts a store field from a Contact Card to a PIM Item
     *
     * @param aField field to read the data from
     * @param aItem item to write the data to
     *
     * @par Leaving:
     * This method leaves on error with system wide error codes
     */
    void ConvertStoreFieldL(const CContactItemField& aField,
                            MPIMContactItem& aItem);

    /**
     * Adds a name field to a PIM Item
     *
     * @param aText text to add
     * @param aItem item to add the field to
     * @param aElement element which is added
     * @param aLabel lable to be set
     *
     * @par Leaving:
     * This method leaves on an error with system wide error codes.
     */
    void AddNameFieldToItemL(
        TPtrC aText,
        MPIMContactItem& aItem,
        TPIMContactNameElement aElement,
        TPtrC aLabel);

    /**
     * Adds an addres field to a PIM Item
     *
     * @param aText text to add
     * @param aItem item to add the field to
     * @param aElement element which is added
     * @param aAttributes attributes of the address field
     * @param aLabel label to be set
     *
     * @par Leaving:
     * This method leaves on an error with system wide error codes.
     */
    void AddAddressFieldToItemL(
        TPtrC aText,
        MPIMContactItem& aItem,
        TPIMContactAddrElement aElement,
        TPIMAttribute aAttributes,
        TPtrC aLabel);

    /**
     * Converts an address field from a PIM Item to a Contact Card.
     *
     * @param aItem item to read the field from
     * @param aCard card to write the field to
     * @param aField field to convert
     * @param aIndex index to the field to convert
     * @param aAttributes attributes of the field to convert
     *
     * @par Leaving:
     * This method leaves on an error with system wide error codes.
     */
    void ConvertAddressFieldL(
        const MPIMItemData& aItem,
        CContactCard& aCard,
        TPIMContactField aField,
        TInt aIndex,
        TPIMAttribute aAttributes);

    /**
     * Converts a name field from a PIM Item to a Contact Card.
     *
     * @param aItem item to read the field from
     * @param aCard card to write the field to
     * @param aField field to convert
     * @param aIndex index to the field to convert
     *
     * @par Leaving:
     * This method leaves on an error with system wide error codes.
     */
    void ConvertNameFieldL(
        const MPIMItemData& aItem,
        CContactCard& aCard,
        TPIMContactField aField,
        TInt aIndex);

    /**
     * Converts a date field from a PIM Item to a Contact Card.
     *
     * @param aItem item to read the field from
     * @param aCard card to write the field to
     * @param aField field to convert
     * @param aIndex index to the field to convert
     *
     * @par Leaving:
     * This method leaves on an error with system wide error codes.
     * @par NOTE!
     * The debug version of this method panics if the date is not a birthday!
     */
    void ConvertDateFieldL(
        const MPIMItemData& aItem,
        CContactCard& aCard,
        TPIMContactField aField,
        TInt aIndex);

    /**
     * Converts a string field from a PIM Item to a Contact Card.
     *
     * @param aItem item to read the field from
     * @param aCard card to write the field to
     * @param aField field to convert
     * @param aIndex index to the field to convert
     *
     * @par Leaving:
     * This method leaves on an error with system wide error codes.
     */
    void ConvertStringFieldL(
        const MPIMItemData& aItem,
        CContactCard& aCard,
        TPIMContactField aField,
        TInt aIndex);

    /**
     * Converts a photo field from a PIM Item to a Contact Card.
     *
     * @param aItem item to read the field from
     * @param aCard card to write the field to
     * @param aField field to convert
     * @param aIndex index to the field to convert
     *
     * @par Leaving:
     * This method may leave.
     */
    void ConvertPhotoFieldL(
        const MPIMItemData& aItem,
        CContactCard& aCard,
        TPIMContactField aField,
        TInt aIndex);

    /**
     * Converts a class field from a PIM Item to a Contact Card.
     *
     * @param aItemData item to read the field from
     * @param aCard card to write the field to
     * @param aField field to convert
     * @param aIndex index to the field to convert
     *
     * @par Leaving:
     * This method may leave.
     */
    void ConvertClassFieldL(
        const MPIMItemData& aItemData,
        CContactCard& aCard,
        TPIMContactField aField,
        TInt aIndex);

    /**
     * Converts a class field from a Contact Card to PIM item
     *
     * @param aItemData Item to add the field
     * @param aClassDesValue Pointer descriptor to the native value
     * @param aLabel Label for the field
     *
     * @par Leaving
     * This method may leve
     */
    void AddClassFieldToItemL(
        MPIMItemData& aItemData,
        TPtrC& aClassDesValue,
        TPtrC aLabel);

    /**
     * Checks the attributes in the address values in the given
     * item, and finds out optimal values for address index
     * members.
     * @param aItem item which is checked
     * @param aPlainAddressIndex the index of address without
     * attributes is placed here
     * @param aHomeAddressIndex the index of address with home
     * attribute is placed here
     * @param aWorkAddressIndex the index of address with work
     * attribute is placed here
     */
    void AddressAttributesL(const MPIMItemData& aItem,
                            TInt& aPlainAddressIndex,
                            TInt& aHomeAddressIndex,
                            TInt& aWorkAddressIndex);

    /**
     * Checks that given string value does not exceed the limit
     * specified for the given field.
     */
    void EnsureValidStringValueLengthL(
        TPIMContactField aField,
        const TDesC& aValue);

    /**
     * Checks that given address array element does not exceed
     * a predefined length limit.
     */
    void EnsureValidAddrElemLengthL(
        TPIMContactAddrElement aElemIndex,
        const TDesC& aElemValue);

    /**
     * Checks that given name array element does not exceed
     * a predefined length limit.
     */
    void EnsureValidNameElemLengthL(
        TPIMContactNameElement aElemIndex,
        const TDesC& aElemValue);

private: // members

    // Handles categories
    CPIMContactCategoryManager& iCategoryManager;

    // Scales bitmaps, owned.
    CPIMImageScaler* iImageScaler;

    // Matches Contacts Model fields to PIM contact fields
    CPIMContactFieldInfo* iFieldInfo;

};

#endif // CPIMCONTACTITEMADAPTER_H
// End of file