/*

* 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:  Access interface to PIM item common data representation.

 *

*/

#ifndef MPIMITEM_H

#define MPIMITEM_H

//  INCLUDES

#include "pimcommon.h"

#include "bamdesca.h" // For MDesCArray

#include "badesca.h" // For CDesCArray

/**

 *  Interface for manipulating item data in the Framework.

 *  The interface does

 *  as few checks as possible to provide "raw" access to the data in a

 *  list-independent manner.

 *

 *  Only CBase-derived classes may implement this interface. Deriving other

 *  M-classes from this class is \b prohibited. Deriving specialized M-classes

 *  from this class might result in a "diamond-shaped" inheritance tree,

 *  because it is intended that the common parts of the item implementation

 *  implement this interface. Specialized implementations will be derived

 *  from that common implementation and those must implement the specialized

 *  interfaces (M-classes), too. Diamond-shaped inheritance is highly

 *  discouraged in Symbian OS. The case is resolved so that the M-classes

 *  that would be derived from this class provide a \e getter method, say

 *  \c "GetItemData()", that returns a pointer to this interface. The two

 *  interfaces access the same object, thus providing an "inheritance-like"

 *  accessibility to that object.

 *

 *  When accessing data through this interface, the following things are

 *  checked:

 *  @li Field validity in accordance to the PIM type (Contact, Event, ToDo).

 *      No fields belonging to different PIM type are allowed to be manipulated

 *      through this interface.

 *  @li Field value validity in accordance to the field value type (binary,

 *      boolean, integer, ...). Value types do not mix.

 *  @li Existence of a requested value for given field and index in the value

 *      array when getting a value.

 *  @li Is a field supported by a specific list (adapter) implementation, if

 *      the item belongs to a list.

 *  @li Is an attribute valid for a specific field.

 *  @li Is an attribute supported by a specific list (adapter) implementation,

 *      if the item belongs to a list.

 *  @li Value array maximum sizes, if the item belongs to a list.

 *

 * NOTE: If you use PIM item via this interface, be sure that when modifiying

 *       non-initialized fields with huge amount if item may cause significant

 *       overhead if the data is not available.

 */

NONSHARABLE_CLASS(MPIMItem)

{

public: // Destructor

    /**

     * Destructor.

     */

    virtual ~MPIMItem()

    {}

public: // New functions

    /**

     * Provides all fields that have values in the item.

     *

     * @return An array of fields. The \b ownership of the array is

     *         transferred to the caller. The order of fields is

     *         undefined.

     *

     * @par Leaving:

     * The method leaves on error.

     */

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

    /* --- Binary --- */

    /**

     * Gets specific binary value.

     * The value is Base64-encoded.

     *

     * @param aField Field constant.

     * @param aIndex Value index.

     * @return Byte array value.

     *         \b Ownership of the return value is transferred to caller.

     *

     * @par Leaving:

     * The method leaves on error. Error codes should be interpreted as

     * follows:

     * @li \c KErrArgument - \a aField is not valid for the implementing

     *     PIM item type.

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

     * @li \c KErrNotSupported - The item is associated with a list and

     *     The list does not support \a aField.

     */

    virtual CPIMByteArray* GetBinaryL(TPIMField aField, TInt aIndex) const = 0;

    /**

     * Same as GetBinaryL, but provides the value non-Base64-encoded.

     * Ownership of the return value remains.

     */

    virtual const CPIMByteArray

    & GetBinaryRawL(TPIMField aField, TInt aIndex) const = 0;

    /**

     * Adds a binary value for a binary field. The value is added as the

     * last value in that field's value array.

     * The value must be Base64-encoded.

     *

     * @param aField The field to which the value is added.

     * @param aAttributes The attributes to be set for the value.

     * @param aValue The binary value to be added to the field.

     *        \b Ownership of the value is transferred to the called

     *        object.

     *

     * @par Leaving:

     * The method leaves on error. Error codes should be interpreted as

     * follows:

     * @li \c KErrArgument - \a aField is not valid for the implementing

     *     PIM item type or \a aValue is NULL.

     * @li \c KErrTooBig - \a aValue is not valid for the field.

     * @li \c KErrNotSupported - The item is associated with a list and

     *     The list does not support \a aField.

     * @li \c KErrOverflow - The field already contains the maximum

     *     number of values it can hold.

     * @li \c KErrLocked - \a aField is read-only.

     * @li Other - The value could not be added.

     */

    virtual void AddBinaryL(TPIMField aField, TPIMAttribute aAttributes,

                            CPIMByteArray* aValue) = 0;

    /**

     * Same as AddBinaryL, but takes the value non-Base64-encoded.

     */

    virtual void AddBinaryRawL(TPIMField aField, TPIMAttribute aAttributes,

                               CPIMByteArray* aValue) = 0;

    /**

     * Sets an existing binary value, discarding the old value.

     * The value must be Base64-encoded.

     *

     * @param aField The field for which the value is set.

     * @param aIndex The index of the value in the value array.

     * @param aAttributes The attributes to be set for the value.

     * @param aValue The value to be set in the place of the old value.

     *        \b Ownership of the new value is transferred to the called

     *        object. The old value is deleted.

     *

     * @par Leaving:

     * The method leaves on error. Error codes should be interpreted as

     * follows:

     * @li \c KErrArgument - \a aField is not valid for the implementing

     *     PIM item type or \a aValue is NULL.

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

     * @li \c KErrTooBig - \a aValue is not valid for the field.

     * @li \c KErrNotSupported - The item is associated with a list and

     *     The list does not support \a aField.

     * @li \c KErrLocked - \a aField is read-only.

     * @li Other - The value could not be set.

     */

    virtual void SetBinaryL(TPIMField aField, TInt aIndex,

                            TPIMAttribute aAttributes, CPIMByteArray* aValue) = 0;

    /**

     * Same as SetBinaryL, but takes the value non-Base64-encoded.

     */

    virtual void SetBinaryRawL(TPIMField aField, TInt aIndex,

                               TPIMAttribute aAttributes, CPIMByteArray* aValue) = 0;

    /* --- Date --- */

    /**

     * Gets specific date value.

     *

     * @param aField Field constant.

     * @param aIndex Value index.

     * @return Date value.

     *

     * @par Leaving:

     * The method leaves on error. Error codes should be interpreted as

     * follows:

     * @li \c KErrArgument - \a aField is not valid for the implementing

     *     PIM item type.

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

     * @li \c KErrNotSupported - The item is associated with a list and

     *     The list does not support \a aField.

     */

    virtual const TPIMDate GetDateL(TPIMField aField, TInt aIndex) const = 0;

    /**

     * Adds a date value for a date field. The value is added as the

     * last value in that field's value array.

     *

     * @param aField The field to which the value is added.

     * @param aAttributes The attributes to be set for the value.

     * @param aValue The date value to be added to the field.

     *

     * @par Leaving:

     * The method leaves on error. Error codes should be interpreted as

     * follows:

     * @li \c KErrArgument - \a aField is not valid for the implementing

     *     PIM item type.

     * @li \c KErrTooBig - \a aValue is not valid for the field.

     * @li \c KErrNotSupported - The item is associated with a list and

     *     The list does not support \a aField.

     * @li \c KErrOverflow - The field already contains the maximum

     *     number of values it can hold.

     * @li \c KErrLocked - \a aField is read-only.

     * @li Other - The value could not be added.

     */

    virtual void AddDateL(TPIMField aField, TPIMAttribute aAttributes,

                          TPIMDate aValue) = 0;

    /**

     * Sets an existing date value, discarding the old value.

     *

     * @param aField The field for which the value is set.

     * @param aIndex The index of the value in the value array.

     * @param aAttributes The attributes to be set for the value.

     * @param aValue The value to be set in the place of the old value.

     *

     * @par Leaving:

     * The method leaves on error. Error codes should be interpreted as

     * follows:

     * @li \c KErrArgument - \a aField is not valid for the implementing

     *     PIM item type.

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

     * @li \c KErrTooBig - \a aValue is not valid for the field.

     * @li \c KErrNotSupported - The item is associated with a list and

     *     The list does not support \a aField.

     * @li \c KErrLocked - \a aField is read-only.

     * @li Other - The value could not be set.

     */

    virtual void SetDateL(TPIMField aField, TInt aIndex,

                          TPIMAttribute aAttributes, TPIMDate aValue) = 0;

    /* --- Int --- */

    /**

     * Gets specific int value.

     *

     * @param aField Field constant.

     * @param aIndex Value index.

     * @return Integer value.

     *

     * @par Leaving:

     * The method leaves on error. Error codes should be interpreted as

     * follows:

     * @li \c KErrArgument - \a aField is not valid for the implementing

     *     PIM item type.

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

     * @li \c KErrNotSupported - The item is associated with a list and

     *     The list does not support \a aField.

     */

    virtual int getInt(TPIMField aField, int aIndex) const = 0;

    /* --- String --- */

    /**

     * Gets specific string value.

     *

     * @param aField Field constant.

     * @param aIndex Value index.

     * @return String value.

     *

     * @par Leaving:

     * The method leaves on error. Error codes should be interpreted as

     * follows:

     * @li \c KErrArgument - \a aField is not valid for the implementing

     *     PIM item type.

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

     * @li \c KErrNotSupported - The item is associated with a list and

     *     The list does not support \a aField.

     */

    virtual const TDesC& GetStringL(TPIMField aField, TInt aIndex) const = 0;

    /**

     * Adds a string value for a string field. The value is added as the

     * last value in that field's value array.

     *

     * @param aField The field to which the value is added.

     * @param aAttributes The attributes to be set for the value.

     * @param aValue The string value to be added to the field.

     *        \b Ownership of the value is transferred to the called

     *        object.

     *

     * @par Leaving:

     * The method leaves on error. Error codes should be interpreted as

     * follows:

     * @li \c KErrArgument - \a aField is not valid for the implementing

     *     PIM item type or \a aValue is NULL.

     * @li \c KErrTooBig - \a aValue is not valid for the field.

     * @li \c KErrNotSupported - The item is associated with a list and

     *     The list does not support \a aField.

     * @li \c KErrOverflow - The field already contains the maximum

     *     number of values it can hold.

     * @li \c KErrLocked - \a aField is read-only.

     * @li Other - The value could not be added.

     */

    virtual void AddStringL(TPIMField aField, TPIMAttribute aAttributes,

                            HBufC* aValue) = 0;

    /**

     * Sets an existing string value, discarding the old value.

     *

     * @param aField The field for which the value is set.

     * @param aIndex The index of the value in the value array.

     * @param aAttributes The attributes to be set for the value.

     * @param aValue The value to be set in the place of the old value.

     *        \b Ownership of the value is transferred to the called

     *        object. The old value is deleted.

     *

     * @par Leaving:

     * The method leaves on error. Error codes should be interpreted as

     * follows:

     * @li \c KErrArgument - \a aField is not valid for the implementing

     *     PIM item type or \a aValue is NULL.

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

     * @li \c KErrTooBig - \a aValue is not valid for the field.

     * @li \c KErrNotSupported - The item is associated with a list and

     *     The list does not support \a aField.

     * @li \c KErrLocked - \a aField is read-only.

     * @li Other - The value could not be set.

     */

    virtual void SetStringL(TPIMField aField, TInt aIndex,

                            TPIMAttribute aAttributes, HBufC* aValue) = 0;

    /* --- Boolean --- */

    /**

     * Gets specific boolean value.

     *

     * @param aField Field constant.

     * @param aIndex Value index.

     * @return Boolean value.

     *

     * @par Leaving:

     * The method leaves on error. Error codes should be interpreted as

     * follows:

     * @li \c KErrArgument - \a aField is not valid for the implementing

     *     PIM item type.

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

     * @li \c KErrNotSupported - The item is associated with a list and

     *     The list does not support \a aField.

     */

    virtual TBool GetBooleanL(TPIMField aField, TInt aIndex) const = 0;

    /**

     * Adds a boolean value for a boolean field. The value is added as the

     * last value in that field's value array.

     *

     * @param aField The field to which the value is added.

     * @param aAttributes The attributes to be set for the value.

     * @param aValue The boolean value to be added to the field.

     *

     * @par Leaving:

     * The method leaves on error. Error codes should be interpreted as

     * follows:

     * @li \c KErrArgument - \a aField is not valid for the implementing

     *     PIM item type.

     * @li \c KErrTooBig - \a aValue is not valid for the field.

     * @li \c KErrNotSupported - The item is associated with a list and

     *     The list does not support \a aField.

     * @li \c KErrOverflow - The field already contains the maximum

     *     number of values it can hold.

     * @li \c KErrLocked - \a aField is read-only.

     * @li Other - The value could not be added.

     */

    virtual void AddBooleanL(TPIMField aField, TPIMAttribute aAttributes,

                             TBool aValue) = 0;

    /**

     * Sets an existing boolean value, discarding the old value.

     *

     * @param aField The field for which the value is set.

     * @param aIndex The index of the value in the value array.

     * @param aAttributes The attributes to be set for the value.

     * @param aValue The value to be set in the place of the old value.

     *

     * @par Leaving:

     * The method leaves on error. Error codes should be interpreted as

     * follows:

     * @li \c KErrArgument - \a aField is not valid for the implementing

     *     PIM item type.

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

     * @li \c KErrTooBig - \a aValue is not valid for the field.

     * @li \c KErrNotSupported - The item is associated with a list and

     *     The list does not support \a aField.

     * @li \c KErrLocked - \a aField is read-only.

     * @li Other - The value could not be set.

     */

    virtual void SetBooleanL(TPIMField aField, TInt aIndex,

                             TPIMAttribute aAttributes, TBool aValue) = 0;

    /* --- StringArray --- */

    /**

     * Gets specific string array value.

     * Empty string array elements are denoted with an empty string.

     *

     * @param aField Field constant.

     * @param aIndex Value index.

     * @return StringArray value.

     *

     * @par Leaving:

     * The method leaves on error. Error codes should be interpreted as

     * follows:

     * @li \c KErrArgument - \a aField is not valid for the implementing

     *     PIM item type.

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

     * @li \c KErrNotSupported - The item is associated with a list and

     *     The list does not support \a aField.

     */

    virtual const CDesCArray

    & GetStringArrayL(TPIMField aField, TInt aIndex) const = 0;

    /**

     * Adds a string array value for a string array field.

     * The value is added as the last value in that field's value array.

     * All elements of the string array must be present in their specified

     * indexes. Empty elements are denoted with an empty string.

     *

     * @param aField The field to which the value is added.

     * @param aAttributes The attributes to be set for the value.

     * @param aValue The string array value to be added to the field.

     *        \b Ownership of the value is transferred to the called

     *        object.

     *

     * @par Leaving:

     * The method leaves on error. Error codes should be interpreted as

     * follows:

     * @li \c KErrArgument - \a aField is not valid for the implementing

     *     PIM item type or \a aValue is NULL.

     * @li \c KErrTooBig - \a aValue is not valid for the field.

     * @li \c KErrNotSupported - The item is associated with a list and

     *     The list does not support \a aField.

     * @li \c KErrOverflow - The field already contains the maximum

     *     number of values it can hold.

     * @li \c KErrLocked - \a aField is read-only.

     * @li Other - The value could not be added.

     */

    virtual void AddStringArrayL(TPIMField aField, TPIMAttribute aAttributes,

                                 CDesCArray* aValue) = 0;

    /**

     * Sets an existing string array value, discarding the old value.

     * All elements of the string array must be present in their specified

     * indexes. Empty elements are denoted with an empty string.

     *

     * @param aField The field for which the value is set.

     * @param aIndex The index of the value in the value array.

     * @param aAttributes The attributes to be set for the value.

     * @param aValue The value to be set in the place of the old value.

     *        \b Ownership of the value is transferred to the called

     *        object. The old value is deleted.

     *

     * @par Leaving:

     * The method leaves on error. Error codes should be interpreted as

     * follows:

     * @li \c KErrArgument - \a aField is not valid for the implementing

     *     PIM item type or \a aValue is NULL.

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

     * @li \c KErrTooBig - \a aValue is not valid for the field.

     * @li \c KErrNotSupported - The item is associated with a list and

     *     The list does not support \a aField.

     * @li \c KErrLocked - \a aField is read-only.

     * @li Other - The value could not be set.

     */

    virtual void SetStringArrayL(TPIMField aField, TInt aIndex,

                                 TPIMAttribute aAttributes, CDesCArray* aValue) = 0;

    /**

     * Counts the number of values in a specific field.

     *

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

     *

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

     *

     * @par Leaving:

     * The method leaves on error. Error codes should be interpreted as

     * follows:

     * @li \c KErrArgument - \a aField is not valid for the implementing

     *     PIM item type.

     * @li \c KErrNotSupported - The item is associated with a list and

     *     The list does not support \a aField.

     */

    virtual TInt CountValuesL(TPIMField aField) const = 0;

    /**

     * Provides attributes of a specific value of a specific field.

     *

     * @param aField The field that has the value.

     * @param aIndex The index of the value in the value array.

     *

     * @return The attributes set for the value, orred bitwise.

     *

     * @par Leaving:

     * The method leaves on error. Error codes should be interpreted as

     * follows:

     * @li \c KErrArgument - \a aField is not valid for the implementing

     *     PIM item type.

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

     * @li \c KErrNotSupported - The item is associated with a list and

     *     The list does not support \a aField.

     */

    virtual TPIMAttribute

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

    /**

     * Adds the item to a category.

     * If the item already belongs to the category, nothing is done.

     *

     * @param aCategory The category. Category name is copied if necessary.