/*

* 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:  Interface class to access framework item data

 *

*/

#ifndef MPIMITEMDATA_H

#define MPIMITEMDATA_H

// INTERNAL INCLUDES

#include "tpimfielddata.h"

// EXTERNAL INCLUDES

#include <e32std.h>

/**

 * This class representates one PIM item data type which

 * can be used through this interface. This interface had

 * to be represented due to the need for a raw access to

 * PIM item data. So, this interface is used by list adapters

 * to fill an item without doing extra checks for the data

 * (it must be expected that adapters now what data they are adding)

 *

 * @since S60 v3.1

 */

NONSHARABLE_CLASS(MPIMItemData)

{

public:

    /**

     * 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

     */

    virtual void SetValueL(const TPIMFieldData& aFieldData) = 0;

    /**

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

     */

    virtual void AddValueL(const TPIMFieldData& aFieldData) = 0;

    /**

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

     */

    virtual const TPIMFieldData ValueL(const TPIMField aField,

                                       const TInt aIndex) const = 0;

    /**

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

     */

    virtual void RemoveValueL(const TPIMField aField, const TInt aIndex) = 0;

    /**

     * 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

     */

    virtual TInt CountValues(const TPIMField aField) const = 0;

    /**

     * 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

     */

    virtual CArrayFix<TPIMField>* FieldsLC() const = 0;

    /**

     * 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

     */

    virtual void SetLabelL(const TPIMField aField, const TInt aIndex,

                           const TInt aArrayIndex, const TDesC& aLabel) = 0;

    /**

     * 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

     */

    virtual const TPtrC LabelL(const TPIMField aField, const TInt aIndex,

                               const TInt aArrayIndex) const = 0;

    /**

     * Clears all fields from this item data.

     */

    virtual void Reset() = 0;

    /**

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

     */

    virtual void SetAttributesL(const TPIMField aField, const TInt aIndex,

                                TPIMAttribute aAttributes) = 0;

    /**

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

     */

    virtual TInt

    AttributesL(const TPIMField aField, const TInt aIndex) const = 0;

    /**

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

     */

    virtual void SetInternalAttributesL(const TPIMField aField,

                                        const TInt aIndex, CArrayFix<TUid>* aInternalAttributes) = 0;

    /**

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

     */

    virtual const CArrayFix<TUid>& InternalAttributesL(const TPIMField aField,

            const TInt aIndex) const = 0;

    /**

     * 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

     */

    virtual TInt FindCategory(const TDesC& aCategoryName) const = 0;

    /**

     * AddNewCategoryL

     * Adds new category to the category list

     *

     * @param aCategoryName Category name which is to be added

     */

    virtual void AddNewCategoryL(const TDesC& aCategoryName) = 0;

    /**

     * 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

     */

    virtual TBool RemoveCategory(const TDesC& aCategoryName) = 0;

    /**

     * Categories

     * Returns a reference to the categories associeated

     * with this item data

     *

     * @return A reference to the list of categories

     */

    virtual const CDesCArray& Categories() const = 0;

protected:

    // Prohibit destruction using this interface

    virtual ~MPIMItemData()

    {}

}

;

#endif // MPIMITEMDATA_H

// End of file