/*

* Copyright (c) 2002-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:  Defines an internal class CAknsAppSkinInstanceCacheEntry which

*                encapsulates a single skin instance cache entry.

*

*/

#ifndef AKNSASICACHEENTRY_H

#define AKNSASICACHEENTRY_H

//  INCLUDES

#include <AknsItemData.h>

// CLASS DECLARATION

/**

* Item data cache entry used by CAknsAppSkinInstance.

* CAknsAppSkinInstanceCacheEntry encapsulates single cache item. It provides

* explicit reference counting, but the caller is responsible of calling

* appropriate methods and also destructing the cache entry when it is no longer

* referenced.

*

* This is an internal class that contains no exported functions.

* The class is not intended for derivation outside the library.

*

* @since 2.0

*

* @internal

*/

NONSHARABLE_CLASS(CAknsAppSkinInstanceCacheEntry) : public CBase

    {

    public: // Construction and destruction

        /**

        * C++ constructor.

        *

        * @param aID Item ID of the new cache item.

        *

        * @param aData Pointer to item data. Ownership is transferred to

        *   CAknsAppSkinInstanceCacheEntry instance. @c NULL value is valid.

        *

        * @internal

        */

        CAknsAppSkinInstanceCacheEntry( const TAknsItemID& aID,

            CAknsItemData* aData );

        /**

        * Two-phased constructor.

        *

        * @param aID Item ID of the new cache item.

        *

        * @param aData Pointer to item data. Ownership is transferred to

        *   CAknsAppSkinInstanceCacheEntry instance. @c NULL value is valid.

        *

        * @return Newly constructed CAknsAppSkinInstanceCacheEntry object.

        *

        * @par Exceptions:

        *   If construction fails, leaves with an error code.

        *

        * @internal

        */

        static CAknsAppSkinInstanceCacheEntry* NewL(

            const TAknsItemID& aID, CAknsItemData* aData );

        /**

        * Destructor.

        * Deletes iData member.

        *

        * @internal

        */

        virtual ~CAknsAppSkinInstanceCacheEntry();

    public: // New functions

        /**

        * Returns the item ID of this cache entry.

        *

        * @return Item ID.

        *

        * @internal

        */

        inline TAknsItemID ID() const;

        /**

        * Returns item data associated with this cache entry.

        *

        * @return Pointer to item data. CAknsAppSkinInstanceCacheEntry still

        *   owns the item data object and controls its lifetime.

        *

        * @internal

        */

        inline CAknsItemData* Data();

        /**

        * Destroys the old item data (if any) and sets a new one.

        *

        * @param aData New item data to be associated with this cache entry.

        *   Ownership of item data is transferred to

        *   CAknsAppSkinInstanceCacheEntry instance.

        *

        * @internal

        */

        inline void DestroyAndSetData( CAknsItemData* aData );

        /**

        * Increases reference counter by one.

        *

        * @internal

        */

        void IncreaseRefCount();

        /**

        * Decreases reference counter by one.

        * Caller is resposible of deleting the cache item when reference count

        * drops to zero. This can be checked by calling

        * CAknsAppSkinInstanceCacheEntry::IsReferenced().

        *

        * @par Exceptions:

        *   While this function may not leave and does not delete object, it

        *   may panic if reference count becomes negative.

        *

        * @internal

        */

        void DecreaseRefCount();

        /**

        * Tells whether the cache item is referenced.

        *

        * @return ETrue if reference count is positive, EFalse otherwise.

        *

        * @internal

        */

        TBool IsReferenced() const;

        /**

        * Determines the order of two CAknsAppSkinInstanceCacheEntry objects.

        * Order is determined based on the item ID of the object, as described

        * in TAknsItemID::LinearOrder().

        *

        * @param aFirst First object to be compared.

        *

        * @param aSecond Second object to be compared.

        *

        * @return 0 if the two objects are equal, negative value if the first

        *   object is less than the second and positive value if the first

        *   object is greater than the second.

        *

        * @internal

        */

        static TInt LinearOrder(

            const CAknsAppSkinInstanceCacheEntry& aFirst,

            const CAknsAppSkinInstanceCacheEntry& aSecond );

    private: // Data members

        TAknsItemID iID;        //!< Item ID.

        TInt iRefCount;         //!< Reference counter.

        CAknsItemData* iData;   //!< Pointer to item data.

    };

// INLINED MEMBERS

#include "AknsASICacheEntry.inl"

#endif      // AKNSASICACHEENTRY_H

// End of File