/*

* 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:  PIM item base implementation.

 *

*/

#ifndef CPIMITEM_H

#define CPIMITEM_H

// INTERNAL INCLUDES

#include "pimcommon.h"

#include "pimbaseitem.h"

#include "mpimitem.h"

// EXTERNAL INCLUDES

#include <e32base.h>

#include <badesca.h>

// FORWARD DECLARATIONS

class MPIMAdapterManager;

class MPIMListAdapter;

class CPIMValidator;

class CPIMItemData;

// CLASS DECLARATION

/**

 *  PIM item base implementation. The class is derivable, but not instantiable.

 *  The class acts as a container for cached PIM item data.

 */

NONSHARABLE_CLASS(CPIMItem): public CBase,

        public MPIMItem,

        public pimbaseitem

{

public: // Destructor

    /**

     * Destructor.

     */

    virtual ~CPIMItem();

public: // New abstract functions

    /**

     * Determines the list type to which the item can be associated to;

     * i.e. also the type of the item.

     */

    virtual TPIMListType ItemType() const = 0;

    /**

     * Persists the item in the native database. The modification

     * status of the item is cleared on success.

     *

     * @par Leaving:

     * @li \c KErrNotFound - The item was persisted earlier, but

     *     has probably been removed since that.

     * @li \c KErrDisconnected - The associated list is closed.

     * @li \c KErrDismounted - The item does not belong to a list.

     * @li Other - Internal error.

     */

    virtual void commit() = 0;

public: // New functions

    /**

     * Determines field data type.

     *

     * @param aField A field constant.

     *

     * @return Field data type or \ref EPIMFieldInvalid if the field is

     * not supported by the derived class.

     */

    TPIMFieldDataType fieldDataType(

        const TPIMField& aField) const;

    /**

     * Provides a complete set of valid attributes for a derived class.

     * The attribute set can be used for masking invalid attributes off

     * from a some set of attributes.

     */

    TPIMAttribute ValidAttributes() const;

    /**

     * Checks whether given boolean value is valid for given field.

     * Default implementation just consults the validator.

     *

     * @return \c EFalse, if the value is known to be invalid, \c ETrue

     *         otherwise.

     */

    virtual TBool IsValidBooleanValue(

        const TPIMField& aField,

        const TBool& aValue) const;

    /**

     * Checks whether given date value is valid for given field.

     * Default implementation just consults the validator.

     *

     * @return \c EFalse, if the value is known to be invalid, \c ETrue

     *         otherwise.

     */

    virtual TBool IsValidDateValue(

        const TPIMField& aField,

        const TPIMDate& aValue) const;

    /**

     * Checks whether given integer value is valid for given field.

     * Default implementation just consults the validator.

     *

     * @return \c EFalse, if the value is known to be invalid, \c ETrue

     *         otherwise.

     */

    virtual TBool IsValidIntegerValue(

        const TPIMField& aField,

        const TInt& aValue) const;

    /**

     * Checks whether given binary value is valid for given field.

     * Default implementation just consults the validator.

     *

     * @return \c EFalse, if the value is known to be invalid, \c ETrue

     *         otherwise.

     */

    virtual TBool IsValidBinaryValue(

        const TPIMField& aField,

        const CPIMByteArray& aValue) const;

    /**

     * Checks whether given string value is valid for given field.

     * Default implementation just consults the validator.

     *

     * @return \c EFalse, if the value is known to be invalid, \c ETrue

     *         otherwise.

     */

    virtual TBool IsValidStringValue(

        const TPIMField& aField,

        const HBufC& aValue) const;

    /**

     * Checks whether given string array value is valid for given field.

     * Default implementation just consults the validator.

     *

     * @return \c EFalse, if the value is known to be invalid, \c ETrue

     *         otherwise.

     */

    virtual TBool IsValidStringArrayValue(

        const TPIMField& aField,

        const CDesCArray& aValue) const;

    //@{

    /**

     * Sets the modification status of this item.

     * Defaults to true.

     */

    void SetModified();

    void SetModified(TBool aIsModified);

    //@}

    /**

     * Informs the item that the associated list has been closed.

     * From this point the adapter manager association is still valid

     * but the list adapter association is invalid.

     */

    virtual void ListClosed();

    /**

     * Informs the item that the name of a category has changed.

     * If the item holds the name of the category, the name must be

     * changed.

     */

    void CategoryRenamedL(

        const TDesC& aOldName,

        const TDesC& aNewName);

    /**

     * Informs the item that a category has been deleted.

     * If the item holds the name of the category, the name must be

     * deleted.

     *

     * @return \c ETrue if the item was assigned to \a aCategory and thus

     *         removed from it; \c EFalse otherwise.

     */

    TBool CategoryDeleted(const TDesC& aCategory);

    /**

     * Removes the adapter associations.

     * Performs any housekeeping related to removing the adapter

     * associations, if necessary.

     */

    virtual void RemoveAdapterAssociation();

    /**

     * Loads full item from the list adapter. This function

     * should be overwriten in the base class if it supports

     * partial data initialization

     */

    virtual void DoLoadFullItemL();

    /**

     * Loads a specific field from the list adapter. This function

     * should be overwriten in the base class if it supports

     * partial data initialization

     *

     * @param aField The field which is to be loaded from

     *        the associated list adapter

     */

    virtual void DoLoadFieldL(const TPIMField aField);

    /**

     * Updates the single value in UID string field from the Item ID.

     * This method is used by the derived classes.

     *

     * @par aUidField The UID string field applicable to the derived class.

     * @par aItemId The Item ID.

     *

     * Behavior:

     * @li If the Item ID is \ref KPIMNullItemID, the UID field is cleared.

     * @li If the Item ID is not \ref KPIMNullItemID, the UID field is

     *     set to have single value - the string representation of the

     *     Item ID.

     *

     * @par Leaving:

     * @li \c KErrCorrupt - The UID field is not in a valid state.

     * @li Any - internal error.

     */

    void UpdateUidFieldL(

        const TPIMField& aUidStringField,

        const TPIMItemID& aItemId);

    /**

     * Updates the single value in REVISION string field.

     * This method is used by the derived classes.

     *

     * @par aRevisionField The valid revision field for this class.

     * @par aLastModified The last modified date/time.

     */

    void UpdateRevisionFieldL(

        TPIMField aRevisionField,

        TPIMDate aLastModified);

public: // Functions from MPIMItem

    /**

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

     */

    CArrayFix< TPIMField>* GetFieldsL() const;

    jintArray callGetFields(JNIEnv* aJniEnv/*,jintArray aJavaFields*/);

    /**

     * Checks whether the contents of the item have been modified since

     * it was last retrieved or committed to the native database.

     *

     * @return ETrue if the item has been modified after last retrieval or

     *         commit, EFalse otherwise.

     */

    bool isModified() const;

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

     */

    CPIMByteArray* GetBinaryL(

        TPIMField aField,

        TInt aIndex) const;

    jbyteArray callGetBinary(

        TPIMField aField,

        int aIndex,

        JNIEnv* aJniEnv,

        jintArray aError);

    /**

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

     * Ownership of the return value remains.

     */

    const CPIMByteArray& GetBinaryRawL(

        TPIMField aField,

        TInt aIndex) const;

    /**

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

     */

    void AddBinaryL(

        TPIMField aField,

        TPIMAttribute aAttributes,

        CPIMByteArray* aValue);

    void callAddBinary(

        TPIMField aField,

        TPIMAttribute aAttributes,

        unsigned char* aValue,

        int aOffset,

        int aLength);

    /**

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

     */

    void AddBinaryRawL(

        TPIMField aField,

        TPIMAttribute aAttributes,

        CPIMByteArray* aValue);

    /**

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

     */

    void SetBinaryL(

        TPIMField aField,

        TInt aIndex,

        TPIMAttribute aAttributes,

        CPIMByteArray* aValue);

    void callSetBinary(

        TPIMField aField,

        int aIndex,

        TPIMAttribute aAttributes,

        unsigned char* aValue,

        int aOffset,

        int aLength);

    /**

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

     */

    void SetBinaryRawL(

        TPIMField aField,

        TInt aIndex,

        TPIMAttribute aAttributes,

        CPIMByteArray* aValue);

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

     */

    const TPIMDate GetDateL(

        TPIMField aField,

        TInt aIndex) const;

    jlong callGetDate(

        TPIMField aField,

        int aIndex);

    /**

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

     */

    void AddDateL(TPIMField aField,

                  TPIMAttribute aAttributes,

                  TPIMDate aValue);

    void callAddDate(

        TPIMField aField,

        TPIMAttribute aAttributes,

        jlong aValue);

    /**

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

     */

    void SetDateL(TPIMField aField,

                  TInt aIndex,

                  TPIMAttribute aAttributes,

                  TPIMDate aValue);

    void callSetDate(

        TPIMField aField,

        int aIndex,

        TPIMAttribute aAttributes,

        jlong aValue);

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

     */

    int getInt(TPIMField aField, int aIndex) const;

    /**

     * Adds a int value for a int 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 int 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 Other - The value could not be added.

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