/*
* Copyright (c) 2002 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: 
*     Fixed-size cache of TPbkContactEntry instances
*
*/


#ifndef __CPbkEntryCache_H__
#define __CPbkEntryCache_H__

//  INCLUDES
#include    <TPbkContactEntry.h>
#include    <MPbkContactEntryLoader.h>

// CLASS DECLARATION

/**
 * @internal Only Phonebook internal use supported!
 *
 * Fixed-size cache of TPbkContactEntry instances.
 */
class CPbkEntryCache : 
        public CBase, public MPbkContactEntryLoader
    {
    public:
        /**
         * Creates a new instance of this class.
		 * @param aEngine reference to phonebook engine
         * @param aCapacity cache capacity
         */
        IMPORT_C static CPbkEntryCache* NewL(CPbkContactEngine& aEngine,
			TInt aCapacity);

        /**
         * Destructor.
         */
        ~CPbkEntryCache();

        /**
         * Returns this cache's capacity.
         */
        IMPORT_C TInt Capacity() const;

        /**
         * Retrieves an entry aId from this cache or loads the 
         * entry from the DB if not currently present in the cache.
         *
         * @exception KErrNotFound  if contact aId is not found in this cache
         *                          or in contact DB.
         */
        IMPORT_C const TPbkContactEntry& GetEntryL(TContactItemId aId);

        /**
         * Preloads entry aId into this cache if not already present.
         */
        IMPORT_C void PreloadL(TContactItemId aId);

        /**
         * Unloads an entry aId from this cache.
         */
        IMPORT_C void Unload(TContactItemId aId);

        /**
         * Flushes the cache completely.
         */
        IMPORT_C void Flush();

        /**
         * Sets the entry loader from aContactEntryLoader.
         */
        inline void SetEntryLoader(MPbkContactEntryLoader&
			aContactEntryLoader);

    public:  // Debug-only
        #ifdef _DEBUG
        /// Debug-only performance statistics for CPbkEntryCache
        struct TPerfStats
            {
            /// Own: hit count (debug only)
            TInt iHitCount;
            /// Own: miss count (debug only)
            TInt iMissCount;
            } iPerfStats;
        #endif

    private:  // from MPbkContactEntryLoader
        void LoadEntryL
            (TPbkContactEntry& aEntry, 
            CPbkContactEngine& aEngine, 
            TContactItemId aContactId);

    private:  // Implementation
        struct TEntry
            {
            TDblQueLink iLink;
            TPbkContactEntry iEntry;
            };
        CPbkEntryCache(CPbkContactEngine& aEngine);
        void ConstructL(TInt aCapacity);
        TPbkContactEntry* Find(TContactItemId aId);
        void Touch(TEntry& aEntry);
        TEntry* FindEntry(TContactItemId aId) const;
        const TPbkContactEntry* DebugFind(TContactItemId aId) const;
        void __DbgTestInvariant() const;

    private:  // Data
        /// Own: double queue of entries
        mutable TDblQue<TEntry> iEntryQueue;
        /// Own: memory block for all the cache entries.
        TEntry* iEntries;
        /// Own: Capacity.
        TInt iCapacity;
        /// Ref: Phonebook engine.
        CPbkContactEngine& iEngine;
        /// Ref: Contact entry loader
        MPbkContactEntryLoader* iEntryLoader;

    private:  // friend declarations
        /// For testing only
        friend class CPbkEntryCache_TestAccess;
    };


inline void CPbkEntryCache::SetEntryLoader
        (MPbkContactEntryLoader& aContactEntryLoader)
    {
    iEntryLoader = &aContactEntryLoader;
    }

#endif // __CPbkEntryCache_H__
            
// End of File