/*
* Copyright (c) 2007 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: Generic collection cache
*
*/
#ifndef MPXCOLLECTIONCACHE_H
#define MPXCOLLECTIONCACHE_H
// INCLUDES
#include <e32std.h>
#include <e32base.h>
#include <mpxitemid.h>
// CLASS FORWARDS
class CMPXMedia;
class CMPXCollectionPath;
class TMPXAttribute;
class CMPXCollectionCacheNode;
/**
* The collection cache stores information already retrieved by clients so it can be
* returned immediately if requested again. The information is stored in a tree
* structure, where each tree node corresponds to a path node. When information is
* requested, the path is mapped against the tree and if a corresponding node exists the
* results are returned from cache.
*
* The cache can be limited in size, if the client defines a maximum size, lower priority
* nodes are discarded to make room for new information. The criteria considered when
* discarding nodes include: priority value (specified by the client), path level and
* time of addition.
*
* @lib mpxcollectionengine.lib (not exported)
*/
NONSHARABLE_CLASS(CMPXCollectionCache) :
public CBase
{
public:
/**
* Two-phased constructor.
* @param aMaximumSizeRatio maximum cache size in percentage ratio
* If not specified the cache does not have a limit
* @return Constructed object
*/
static CMPXCollectionCache* NewL(TInt aMaximumSizeRatio = -1);
/**
* Destructor
*/
virtual ~CMPXCollectionCache();
public:
/**
* Cache entry priority values. Entries with lower priority will be discarded
* sooner than the ones with higher priority.
*/
enum TCachePriority
{
EPriorityLow,
EPriorityNormal,
EPriorityHigh
};
public:
/**
* Adds a result set to the cache.
* @param aPath path defining the context of the results.
* @param aAttrs attributes requested by the client application and included in
* the result set.
* @param aResults result set corresponding to the path. Not owned.
* @param aNotCacheableAttrs attributes that are not cacheable
* @param aMediaFromOpenL whether or not this media was from an OpenL
* @param aPriority result set priority
* @return CMPXMedia object in the cache or the original object if add failed
*/
CMPXMedia* AddL(
const CMPXCollectionPath& aPath,
const TArray<TMPXAttribute>& aAttrs,
CMPXMedia& aResults,
TBool aMediaFromOpenL = EFalse,
TCachePriority aPriority = EPriorityNormal );
/**
* Returns the information corresponding to the specified path and attribute set
* if available in the cache.
* @param aPath path defining the information context.
* @param aAttrs attribute set requested by the client.
* @return Valid results or NULL if the path/attribute set specified cannot be
* found in the cache.
*/
CMPXMedia* GetL(
const CMPXCollectionPath& aPath,
const TArray<TMPXAttribute>& aAttrs,
TBool aMediaFromOpenL = EFalse );
/**
* Removes the specified path and all its children from the cache.
* @param aPath path defining the context to be removed.
*/
void RemoveL(const CMPXCollectionPath& aPath);
/**
* Resets cache and removes all nodes
*/
void Reset();
/**
* Handle some change from the collection
* @param aCollectionId collectoin that the change is comming from
* @param aChangeItemId item ID of the changed event
*/
void HandleChangeL( TUid aCollectionId, TMPXItemId aChangeItemId );
private:
/**
* C++ constructor
* @param aMaximumSizeKb maximum cache size in percentage ratio.
*/
CMPXCollectionCache(TInt aMaximumSizeRatio);
/**
* 2nd phase contructor
*/
void ConstructL();
/**
* Returns the cache node corresponding to the specified path.
* @param aPath path to be looked up in the cache.
* @param aCreateNodes if ETrue all the missing nodes for the specified
* path will be created if they do not already exist. If EFalse
* the method returns NULL if corresponding node is not found.
* @return valid cache node if found or created, NULL if not found.
*/
CMPXCollectionCacheNode* NodeFromPathL(const CMPXCollectionPath& aPath,
TBool aCreateNodes = EFalse);
/**
* Removes a specified node and all its children from the cache.
* @param aNode node to be removed. Ownership is transferred.
*/
void RemoveNode(CMPXCollectionCacheNode* aNode);
/**
* Checks the memory condition and clears cache to free some memory
* maximum percentage ratio specified in the constructor is used to detect
* low memory condition
* @return EFalse if low memory condition detected, ETrue otherwise
*/
TBool ManageCacheSizeL();
#ifdef _DEBUG
/**
* Prints the cache tree.
*/
void PrintTree( TBool aPrintAtts = EFalse );
#endif
private:
/**
* Root node for the cache tree, created when the cache is created.
*/
CMPXCollectionCacheNode* iRoot;
/**
* Maximum size of the cache in percentage ratio, specified by the client.
*/
TInt iMaximumSizeRatio;
};
#endif // MPXCOLLECTIONCACHE_H