/*

* 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 item data

 *

*/

#ifndef CPIMITEMDATA_H

#define CPIMITEMDATA_H

// INTERNAL INCLUDES

#include "mpimitemdata.h"

// EXTERNAL INCLUDES

#include <e32std.h>

// FORWARD DECLARATIONS

class CPIMField;

class TPIMFieldData;

/**

 *  This class representates one PIM item data. This is the actual

 *  storage class of the data values of one PIM fields. MPIMItemData

 *  is an interface which provides access to this class

 *

 *  @since S60 v3.1

 */

NONSHARABLE_CLASS(CPIMItemData) : public CBase,

        public MPIMItemData

{

public:

    /**

     * Two-phased constructor.

     *

     * @return New instance of this class.

     */

    static CPIMItemData* NewL();

    /**

     * Two-phased constructor.

     *

     * @return New instance of this class. The instance

     *         is pushed to the cleanup stack

     */

    static CPIMItemData* NewLC();

    /**

     * Destructor

     */

    virtual ~CPIMItemData();

public: // Methods from MPIMItemData

    /**

     * 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

     * @li KErrNotFound - The requested field has no value

     */

    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.

     */

    void AddValueL(const TPIMFieldData& aFieldData);

    /**

     * Fetches value from specific value index. The value is

     * capsulated inside TPIMFieldData class to ease an access

     * to different types of values within the PIM item

     *

     * @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.

     */

    const TPIMFieldData ValueL(const TPIMField aField,

                               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.

     */

    void RemoveValueL(const TPIMField aField,

                      const TInt aIndex);

    /**

     * Counts the number of values in a specific field. The values

     * are counted as indexes within this field. If there is no requested

     * field, this function returns zero

     *

     * @param aField The field values of which are to be counted.

     * @return Number of values in field \a aField.

     *         Zero if there is no values

     */

    TInt CountValues(const TPIMField aField) const;

    /**

     * Returns an array of fields that currently have more than zero values

     * The array is left to the cleanup stack

     *

     * @return Array of fields. The ownership of the array is transferred

     *         to the caller

     */

    CArrayFix< TPIMField>* FieldsLC() const;

    /**

     * Adds new label to an existing field

     *

     * @param aField Field to which the label is added

     * @param aIndex Value index of the label

     * @param aArrayIndex Array index of the label

     * @param aLabel New label

     */

    void SetLabelL(

        const TPIMField aField,

        const TInt aIndex,

        const TInt aArrayIndex,

        const TDesC& aLabel);

    /**

     * Retrieves the label from the specific field with specific

     * field and array indexes.

     *

     * @param aField Field from which the label is retrieved

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

     */

    const TPtrC LabelL(

        const TPIMField aField,

        const TInt aIndex,

        const TInt aArrayIndex) const;

    /**

     * Clears all fields from this item data.

     */

    void Reset();

    /**

     * Sets new attributes for a specific field and value index

     *

     * @param aField Field for which the attributes are to be added

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

     *

     * @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.

     */

    void SetAttributesL(

        const TPIMField aField,

        const TInt aIndex,

        TPIMAttribute aAttributes);

    /**

     * Retrieves attributes from an index within a field

     *

     * @param aField Field from which the attributes are to fetched

     * @param aIndex Value index of the field

     * @return Attributes of this value index

     *

     * @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.

     */

    TInt AttributesL(

        const TPIMField aField,

        const TInt aIndex) const;

    /**

     * Sets internal attributes to an index within a field.

     * Internal attributes are not accessible from the Java-side

     * so this function provides only access to set internal

     * attributes

     *

     * @param aField Field from which the attributes are to fetched

     * @param aIndex Value index of the field

     * @param aInternalAttributes New internal attributes. Old ones

     *        will be overwriten

     *

     * @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.

     */

    void SetInternalAttributesL(

        const TPIMField aField,

        const TInt aIndex,

        CArrayFix< TUid>* aInternalAttributes);

    /**

     * Retrieves internal attributes from an index within a field.

     * Internal attributes are not accessible from the Java-side

     * so this function provides only access to retrieve internal

     * attributes

     *

     * @param aField Field from which the attributes are to fetched

     * @param aIndex Value index of the field

     *

     * @return Internal attributes of this value index

     *

     * @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.

     */

    const CArrayFix< TUid>& InternalAttributesL(

        const TPIMField aField,

        const TInt aIndex) const;

    /**

     * FindCategory

     * Finds a category from the category list

     * If the requested category was not found, KErrNotFound is

     * returned

     *

     * @param aCategoryName Category name to find

     * @return If found, the index of the category and KErrNotFound

     *         if the category was not found

     */

    TInt FindCategory(const TDesC& aCategoryName) const;

    /**

     * AddNewCategoryL

     * Adds new category to the category list

     *

     * @param aCategoryName Category name which is to be added

     */

    void AddNewCategoryL(const TDesC& aCategoryName);

    /**

     * RemoveCategory

     * Removes a category from the category list

     * Returns ETrue if the category was found and removed

     * and EFalse if there was no such category

     *

     * @param aCategoryName Category name which is to be removed

     * @return ETrue if the category was removed, EFalse if not

     */

    TBool RemoveCategory(const TDesC& aCategoryName);

    /**

     * Categories

     * Returns a reference to the categories associeated

     * with this item data

     *

     * @return A reference to the list of categories

     */

    const CDesCArray& Categories() const;

public: // New functions

    /**

     * Check if this item data contains requested field

     * @param aField Field which is to be checked

     * @return ETrue if the field is present, EFalse if not

     */

    TBool HasField(const TPIMField aField) const;

private:

    /**

     * C++ default constructor

     */

    inline CPIMItemData();

    /**

     * Seconds phase constructor

     */

    inline void ConstructL();

private: // New functions

    /**

     * Finds index of the requested field if it is in the

     * field array

     *

     * @param aField requested field

     *

     * @return Index of the field. If not found, KErrNotFound

     *         is returned

     */

    TInt FieldIndex(const TPIMField aField) const;

private: // Data

    /** PIM field array */

    RPointerArray< CPIMField> iFields;

    /** Categories associated with this item data. Owned */

    CDesCArray* iCategories;

};

#endif // CPIMITEMDATA_H

// End of file