/*

* 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,