/*

* 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:  Class for holding PIM field data

 *

*/

#ifndef CPIMFIELD_H

#define CPIMFIELD_H

// INTERNAL INCLUDES

#include "tpimfielddata.h"

// EXTERNAL INCLUDES

#include <e32std.h>

// FORWARD DECLARATIONS

class CPIMValueBase;

/**

 * Class for holding PIM field data. This class

 * stores value indexes to an array.

 * @since S60 v3.1

 */

NONSHARABLE_CLASS(CPIMField) : public CBase

{

public:

    /**

     * Two-phased constructor.

     *

     * @return New instance of this class.

     */

    static CPIMField* NewL(const TPIMFieldData& aFieldData);

    /**

     * Two-phased constructor.

     *

     * @return New instance of this class. The instance

     *         is pushed to the cleanup stack

     */

    static CPIMField* NewLC(const TPIMFieldData& aFieldData);

    /**

     * Destructor

     */

    virtual ~CPIMField();

public: // New methods

    /**

     * Sets PIM field data with certain index

     *

     * This function is used to set all types of PIM

     * data. The TPIMFieldData class encapsulates all

     * possible data about one field so we don't need

     * separate functions for each PIM field type

     *

     * @param aFieldData Reference to data class which

     *        all needed information about the new value

     *

     * @par Leaving:

     * The method leaves on error. Error codes are interpreted as follows:

     * @li \c KErrNotFound - There is not value for given \a aIndex.

     * @li Other - The value could not be removed cleanly. This probably

     *     means that the value array has gone corrupt or OOM situation

     *     has occured

     */

    void SetValueL(const TPIMFieldData& aFieldData);

    /**

     * Adds new PIM field data to certain field

     *

     * This function is used to add all types of PIM

     * data. The TPIMFieldData class encapsulates all

     * possible data about one field so we don't need

     * separate functions for each PIM field type

     *

     * NOTE: The index value in the argument class is ignored

     *

     * @param aFieldData Reference to data class which

     *        all needed information about the new value

     *

     * @par Leaving:

     * The method leaves on error. Error codes are interpreted as follows:

     * @li \c KErrNotFound - There is not value for given \a aIndex.

     * @li Other - The value could not be removed cleanly. This probably

     *     means that the value array has gone corrupt or OOM situation

     *     has occured

     */

    void AddValueL(const TPIMFieldData& aFieldData);

    /**

     * Fetches value from specific value index.

     *

     * @param aIndex Index of the value in this specific field

     * @return A class holding requested information

     *

     * @par Leaving:

     * The method leaves on error. Error codes are interpreted as follows:

     * @li \c KErrNotFound - There is not value for given \a aIndex.

     * @li Other - The value could not be removed cleanly. This probably

     *     means that the value array has gone corrupt or OOM situation

     *     has occured

     */

    const TPIMFieldData ValueL(const TInt aIndex) const;

    /**

     * Removes a specific value of a specific field.

     *

     * @param aIndex Index of the value that is to be removed.

     *

     * @par Leaving:

     * The method leaves on error. Error codes are interpreted as follows:

     * @li \c KErrNotFound - There is not value for given \a aIndex.

     * @li Other - The value could not be removed cleanly. This probably

     *     means that the value array has gone corrupt or OOM situation

     *     has occured

     */

    void RemoveValueL(const TInt aIndex);

    /**

     * Count values currently in this PIM field

     *

     * @return Number of values in this field

     */

    TInt CountValues() const;

    /**

     * Adds new label to an existing field

     *

     * @param aIndex Value index of the label

     * @param aArrayIndex Array index of the label

     * @param aLabel New label

     *

     * @par Leaving:

     * The method leaves on error. Error codes are interpreted as follows:

     * @li \c KErrNotFound - There is not value for given \a aIndex.

     * @li Other - The value could not be removed cleanly. This probably

     *     means that the value array has gone corrupt or OOM situation

     *     has occured

     */

    void SetLabelL(

        const TInt aIndex,

        const TInt aArrayIndex,

        const TDesC& aLabel);

    /**

     * Retrieves the label from the specific field with specific

     * field and array indexes.

     *

     * @param aIndex Index of the field's value

     * @param aArrayIndex Index of the array index if this is a string

     *        array field

     *

     * @return Label name. NULL if there is no label for this array

     *         index or the labels have not been allocated yet

     */

    const TPtrC Label(

        const TInt aIndex,

        const TInt aArrayIndex) const;

    /**

     * DataType

     * Returns the data type of this PIM field

     *

     * @return Data type of this field

     */

    TPIMFieldDataType DataType() const;

    /**

     * FieldType

     * Returns the type of this field

     *

     * @return The type of this field

     */

    TPIMField FieldType() const;

    /**

     * SetAttributesL

     * Sets new attributes for a specific value

     *

     * @param aIndex Index of the value

     * @param aAttributes New attributes

     *

     * @par Leaving:

     * The method leaves on error. Error codes are interpreted as follows:

     * @li \c KErrNotFound - There is not value for given \a aIndex.

     * @li Other - The value could not be removed cleanly. This probably

     *     means that the value array has gone corrupt or OOM situation

     *     has occured

     */

    void SetAttributesL(const TInt aIndex, TPIMAttribute aAttributes);

    /**

     * AttributesL

     * Returns attributes from the specific value

     *

     * @param aIndex Index of the value

     * @return Attributes of the value

     *

     * @par Leaving:

     * The method leaves on error. Error codes are interpreted as follows:

     * @li \c KErrNotFound - There is not value for given \a aIndex.

     * @li Other - The value could not be removed cleanly. This probably

     *     means that the value array has gone corrupt or OOM situation

     *     has occured

     */

    TPIMAttribute AttributesL(const TInt aIndex) const;

    /**

     * SetInternalAttributesL

     * Sets new internal attributes for a specific value. NOTE:

     * Internal attributes are not accessible from the Java-side

     * They only store information which must be preserved when item

     * is loaded from the native database and modified before storing

     *

     * @param aIndex Index of the value

     * @param aAttributes New attributes

     *

     * @par Leaving:

     * The method leaves on error. Error codes are interpreted as follows:

     * @li \c KErrNotFound - There is not value for given \a aIndex.

     * @li Other - The value could not be removed cleanly. This probably

     *     means that the value array has gone corrupt or OOM situation

     *     has occured

     */

    void SetInternalAttributesL(

        const TInt aIndex,

        CArrayFix< TUid>* aInternalAttributes);

    /**

     * InternalAttributesL

     * Returns internal attributes from the specific value. NOTE:

     * Internal attributes are not accessible from the Java-side

     * They only store information which must be preserved when item

     * is loaded from the native database and modified before storing

     *

     * @param aIndex Index of the value

     * @return Attributes of the value

     *

     * @par Leaving:

     * The method leaves on error. Error codes are interpreted as follows:

     * @li \c KErrNotFound - There is not value for given \a aIndex.

     * @li Other - The value could not be removed cleanly. This probably

     *     means that the value array has gone corrupt or OOM situation

     *     has occured

     */

    const CArrayFix< TUid>& InternalAttributesL(const TInt aIndex) const;

private: // New methods

    /**

     * Checks that the given index is in the value

     * range.

     *

     * @param aIndex Index which is to be checked

     * @return ETrue if the index is in range, EFalse if not

     */

    TBool IsInRange(const TInt aIndex) const;

private:

    /**

     * C++ default constructor

     */

    inline CPIMField(const TPIMFieldData& aFieldData);

private: // Data

    /** Type of this field */

    TPIMField iField;

    /** Data type of this field */

    TPIMFieldDataType iFieldDataType;

    /** PIM value array */

    RPointerArray< CPIMValueBase> iValues;

};

#endif // CPIMFIELD_H

// End of file