/*

* 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:  Native-originated external change data.

 *

*/

#ifndef PIMEXTERNALCHANGES_H

#define PIMEXTERNALCHANGES_H

/** @file

 * This file contains definitions and helper classes for passing external

 * changes from the adapters to the Framework.

 */

#include <e32base.h>

#include "pimcommon.h"

#include "pimpanics.h"

/**

 * External change types.

 */

typedef enum

{

    EPIMExternalChangeNew,

    EPIMExternalChangeModified,

    EPIMExternalChangeRemoved

} TPIMExternalChangeType;

/**

 * Simple class for passing external modifications to entries (items) in

 * a native database. The class encapsulates Item ID and type of change for

 * single item. Adapters produce these objects and Framework consumes them.

 */

NONSHARABLE_CLASS(CPIMItemStateChange) : public CBase

{

public: // Constructors and destructor

    /**

     * Constructor.

     * Object data is explicitly set with this constructor. No default

     * constructor is provided.

     * @param aItemID ID of the item this change applies to. The ownership

     *        of the value is transferred to this class

     * @param aChangeType Type of change for the associated item.

     */

    CPIMItemStateChange(

        HBufC8* aItemID,

        TPIMExternalChangeType aChangeType)

            :

            iItemID(aItemID),

            iChangeType(aChangeType)

    {

        __ASSERT_DEBUG(iItemID || *iItemID != KPIMNullItemID,

        User::Panic(KPIMPanicCategory,

        EPIMPanicExternalChangeInit));

    }

    /**

     * Destructor.

     */

    ~CPIMItemStateChange()

    {

        delete iItemID;

    }

    /**

     * Provides ID of the changed item.

     * @return Item ID.

     */

    TPIMItemID ItemID() const

    {

        return *iItemID;

    }

    /**

     * Provides type of change for the associated item.

     * @return Change type.

     */

    TPIMExternalChangeType ChangeType() const

    {

        return iChangeType;

    }

private: // Prohibited operations

    // Prohibit default constructor

    CPIMItemStateChange()

    {}

private: // Data

    HBufC8* iItemID; // Owned

    TPIMExternalChangeType iChangeType;

};

/**

 * Simple class for passing external modifications to categories in

 * a native database. The class encapsulates category name and type of change

 * for single item. Adapters produce these objects and Framework consumes

 * them. \b Note that the object contains heap-allocated data.

 */

NONSHARABLE_CLASS(CPIMCategoryStateChange) : public CBase

{

public:

    //@{

    /**

     * Constructors.

     * Object data is explicitly set with this constructor. No default

     * constructor is provided.

     * @param aCategory Name of the category this change applies to.

     *        The object takes the ownership of the argument. The

     *        argument must not be NULL; otherwise a panic is raised.

     * @param aNewCategory Name of the new category if \a aChangeType

     *        is EPIMExternalChangeModified, in which case it must not

     *        be NULL; otherwise it must be NULL.

     * @param aChangeType Type of change for the associated item.

     */

    CPIMCategoryStateChange(

        HBufC* aCategory,

        TPIMExternalChangeType aChangeType)

            :

            iCategory(aCategory),

            iChangeType(aChangeType)

            // iNewCategoryName is left NULL

    {

        __ASSERT_DEBUG(iCategory,

        User::Panic(KPIMPanicCategory,

        EPIMPanicExternalChangeInit));

    }

    CPIMCategoryStateChange(

        HBufC* aCategory,

        TPIMExternalChangeType aChangeType,

        HBufC* aNewCategoryName)

            :

            iCategory(aCategory),

            iChangeType(aChangeType),

            iNewCategoryName(aNewCategoryName)

    {

        __ASSERT_DEBUG(iCategory,

                       User::Panic(KPIMPanicCategory,

                                   EPIMPanicExternalChangeInit));

#if _DEBUG

        if (aChangeType == EPIMExternalChangeModified)

        {

            __ASSERT_DEBUG(

                iNewCategoryName,

                User::Panic(KPIMPanicCategory,

                            EPIMPanicExternalChangeInit));

        }

        else

        {

            __ASSERT_DEBUG(

                !iNewCategoryName,

                User::Panic(KPIMPanicCategory,

                            EPIMPanicExternalChangeInit));

        }

#endif // _DEBUG

    }

    //@}

    /**

     * Destructor. Deletes the owned category name and new name

     * of that category, if present.

     */

    ~CPIMCategoryStateChange()

    {

        delete iCategory;

        delete iNewCategoryName;

    }

    /**

     * Provides name of the changed category.

     * @return Category name.

     */

    const TDesC& Category() const

    {

        return *iCategory;

    }

    /**

     * Provides the new name of a renamed category.

     *

     * @return New name of a renamed category if change type is

     *         EPIMExternalChangeModified.

     *

     * @par Leaving:

     * @li \c KErrGeneral - Change type is not

     *     EPIMExternalChangeModified.

     */

    const TDesC& NewCategoryNameL() const

    {

        if (!iNewCategoryName)

        {

            User::Leave(KErrGeneral);

        }

        return *iNewCategoryName;

    }

    /**

     * Provides type of change for the associated item.

     * @return Change type.

     */

    TPIMExternalChangeType ChangeType() const

    {

        return iChangeType;

    }

private: // Prohibited operations

    // Prohibit default constructor

    CPIMCategoryStateChange()

    {}

private: // Data

    HBufC* iCategory; // owned

    TPIMExternalChangeType iChangeType;

    HBufC* iNewCategoryName; // owned

};

#endif // PIMEXTERNALCHANGES_H

// End of File