/*

* 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:  Converts properties vCard <-> PIM API

 *

*/

#ifndef CPIMCARDPROPERTYCONVERTER_H

#define CPIMCARDPROPERTYCONVERTER_H

//  INCLUDES

#include <e32base.h> // CBase

#include <badesca.h> // CDesCArray

#include "pimcontact.h" // TPIMContactField

#include "pimcommon.h" // TPIMAttribute

// CLASS DECLARATION

class CPIMItem;

class CPIMContactItem;

class CParserVCard;

class CParserParam;

class CPIMParserProperty;

class CParserProperty;

class CPIMContactValidator;

class CPIMVCardParserParamArray;

class CParserPropertyValue;

/**

 *  Converts Properties from versit objects to fields in PIM Contact items.

 */

NONSHARABLE_CLASS(CPIMCardPropertyConverter): public CBase

{

public: // Constructors and destructor

    /**

     * Two-phased constructor.

     */

    static CPIMCardPropertyConverter* NewL(

        const CPIMContactValidator& aValidator);

    /**

     * Destructor

     */

    virtual ~CPIMCardPropertyConverter();

public: // New functions

    /**

     * Inserts a Field from a PIM Contact Item to CParserVCard as

     * a property.

     *

     * @param aItem item to read the field from

     * @param aParser parser to insert the property to.

     * @param aField field to convert

     *

     */

    void ConvertFieldL(

        const CPIMItem& aItem,

        CParserVCard& aParser,

        TPIMContactField aField);

    /**

     * Inserts a property from a vCard to a PIM Contact Item as a field.

     * If the property contains another vCard, that vCard is returned.

     * Otherwise NULL is returned.

     *

     * @param aProperty property to convert

     * @param aItem item to write the field to

     * @param aItemArray Array where agent field items are stored

     *

     * @return contained vCard, or NULL.

     */

    CParserVCard* ConvertPropertyL(

        const CParserProperty& aProperty,

        CPIMContactItem& aItem);

private:

    /**

     * C++ default constructor.

     */

    CPIMCardPropertyConverter(const CPIMContactValidator& aValidator);

    /**

     * Converts an agent property. The contained vCard is returned.

     *

     * @param aProperty property to convert

     *

     * @return contained vCard.

     */

    CParserVCard* ConvertAgentPropertyL(

        const CPIMParserProperty& aProperty);

    /**

     * Adds parameters "HOME" and "WORK" to an array of property

     * parameters if needed. Ownership of the new parameter objects

     * is transferred to the caller.

     *

     * @param aAttributes Checked, if contains EPIMContactAttrHome or

     *        EPIMContactAttrWork, the parameter is added.

     *

     * @param aParamArray Property parameter array to add the parameters

     *        to.

     */

    void AddParamHomeAndWorkL(TPIMAttribute aAttributes,

                              CPIMVCardParserParamArray& aParamArray);

    /**

     * Converts an address field from a PIM Contact Item to CParserVCard.

     * The field is stored in the parser as a property.

     *

     * @param aItem item to read the field from

     * @param aParser parser to insert the property 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 ConvertAddressFieldL(

        const CPIMItem& aItem,

        CParserVCard& aParser,

        TPIMContactField aField,

        TInt aIndex);

    /**

     * Converts a name field from a PIM Contact Item to CParserVCard.

     * The field is stored in the parser as a property.

     *

     * @param aItem item to read the field from

     * @param aParser parser to insert the property 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 CPIMItem& aItem,

        CParserVCard& aParser,

        TPIMContactField aField,

        TInt aIndex);

    /**

     * Converts name and address arrays from a vCard to a PIM Contact Item.

     *

     * @param aProperty property to convert

     * @param aItem item to write the field to

     *

     */

    void ConvertCDesCArrayPropertyL(

        const CPIMParserProperty& aProperty,

        CPIMContactItem& aItem);

    /**

     * Converts a date field from a PIM Contact Item to a CParserVCard.

     * The field is stored in the parser as a property.

     *

     * @param aItem item to read the field from

     * @param aParser parser to insert the property 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 ConvertDateFieldL(

        const CPIMItem& aItem,

        CParserVCard& aParser,

        TPIMContactField aField,

        TInt aIndex);

    /**

     * Converts a birthday field from a vCard to a PIM Contact Item.

     *

     * @param aProperty property to convert

     * @param aItem item to write the field to

     *

     */

    void ConvertDatePropertyL(

        const CPIMParserProperty& aProperty,

        CPIMContactItem& aItem);

    /**

     * Adds new parser parameter to the parameter array

     *

     * @param aArrayOfParams Parameter array

     * @param aParamName The name of the parameter which will be added

     */

    void AddParserParameterL(

        CPIMVCardParserParamArray& aArrayOfParams,

        const TPtrC8 aParamName);

    /**

     * Converts a string field from a PIM Contact Item to a CParserVCard.

     * The field is stored in the parser as a property.

     *

     * @param aItem item to read the field from

     * @param aParser parser to insert the property 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 CPIMItem& aItem,

        CParserVCard& aParser,

        TPIMContactField aField,

        TInt aIndex);

    /**

     * Converts a string field from a vCard to a PIM Contact Item.

     *

     * @param aProperty property to convert

     * @param aItem item to write the field to

     *

     */

    void ConvertStringPropertyL(

        const CPIMParserProperty& aProperty,

        CPIMContactItem& aItem);

    /**

     * Converts a photo field from a PIM Contact Item to a CParserVCard.

     * The field is stored in the parser as a property.

     *

     * @param aItem item to read the field from

     * @param aParser parser to insert the property 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 ConvertPhotoFieldL(

        const CPIMItem& aItem,

        CParserVCard& aParser,

        TPIMContactField aField,

        TInt aIndex);

    /**

     * Inserts a PHOTO property from a vCard to a PIM Contact Item as a

     * binary field

     *

     * @param aProperty property to convert

     * @param aItem item to write the field to

     *

     */

    void ConvertPhotoPropertyL(

        const CPIMParserProperty& aProperty,

        CPIMContactItem& aItem);

    /**

     * Converts a class field from a PIM Contact Item to a CParserVCard.

     * The field is stored in the parser as a property.

     *

     * @param aItem item to read the field from

     * @param aParser parser to insert the property 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 ConvertClassFieldL(

        const CPIMItem& aItem,

        CParserVCard& aParser,

        TPIMContactField aField,

        TInt aIndex);

    /**

     * Inserts a CLASS property from a vCard to a PIM Contact Item as a

     * integer field

     *

     * @param aProperty property to convert

     * @param aItem item to write the field to

     *

     */

    void ConvertClassPropertyL(

        const CPIMParserProperty& aProperty,

        CPIMContactItem& aItem);

    /**

     * Converts organisational fields from a PIM Contact Item to a

     * CParserVCard. The field is stored in the parser as a property.

     *

     * @param aItem item to read the field from

     * @param aParser parser to insert the property 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 ConvertOrganisationalFieldsL(

        const CPIMItem& aItem,

        CParserVCard& aParser,

        TPIMContactField aField,

        TInt aIndex);

    /**

     * Converts vCard name readings to a PIM item name array elements

     *

     * @param aProperty vCard property value

     * @param aItem Contact List item

     * @param aNameArrayElementIndex Index of this element

     */

    void ConvertNameReadingFieldL(

        const CPIMParserProperty& aProperty,

        CPIMContactItem& aItem);

    /**

     * Adds a new property to the vCard parser

     * Note that property value and array of params are popped

     * from the cleanup stack inside this function

     *

     * @param aPropertyValue Property value for the vCard property

     *        This needs not to be pushed to the cleanup stack before

     *        this function call since it is done straight from the start

     *        of this function

     * @param aPropertyName Name of the property

     * @param aArrayOfParams Parameter array. This can be NULL and must be

     *        pushed to the cleanup stack before this function call

     * @param aParser VCard parser into which the new property is pushed

     */

    void AddPropertyToParserL(

        CParserPropertyValue* aPropertyValue,

        const TDesC8& aPropertyName,

        CPIMVCardParserParamArray* aArrayOfParams,

        CParserVCard& aParser);

private: // data

    // Validates contacts

    const CPIMContactValidator& iContactValidator;

};

#endif // CPIMCARDPROPERTYCONVERTER_H

// End of file