1 /*

     2 * Copyright (c) 2007 Nokia Corporation and/or its subsidiary(-ies).

     3 * All rights reserved.

     4 * This component and the accompanying materials are made available

     5 * under the terms of "Eclipse Public License v1.0"

     6 * which accompanies this distribution, and is available

     7 * at the URL "http://www.eclipse.org/legal/epl-v10.html".

     8 *

     9 * Initial Contributors:

    10 * Nokia Corporation - initial contribution.

    11 *

    12 * Contributors:

    13 *

    14 * Description:  Generic collection cache

    15 *

    16 */

    17 

    18 

    19 #ifndef MPXCOLLECTIONCACHE_H

    20 #define MPXCOLLECTIONCACHE_H

    21 

    22 // INCLUDES

    23 #include <e32std.h>

    24 #include <e32base.h>

    25 #include <mpxitemid.h>

    26 

    27 // CLASS FORWARDS

    28 class CMPXMedia;

    29 class CMPXCollectionPath;

    30 class TMPXAttribute;

    31 class CMPXCollectionCacheNode;

    32 

    33 /**

    34 *  The collection cache stores information already retrieved by clients so it can be

    35 *  returned immediately if requested again. The information is stored in a tree

    36 *  structure, where each tree node corresponds to a path node. When information is

    37 *  requested, the path is mapped against the tree and if a corresponding node exists the

    38 *  results are returned from cache.

    39 *

    40 *  The cache can be limited in size, if the client defines a maximum size, lower priority

    41 *  nodes are discarded to make room for new information. The criteria considered when

    42 *  discarding nodes include: priority value (specified by the client), path level and

    43 *  time of addition.

    44 *

    45 *  @lib mpxcollectionengine.lib (not exported)

    46 */

    47 NONSHARABLE_CLASS(CMPXCollectionCache) :

    48     public CBase

    49     {

    50 public:

    51     /**

    52     *  Two-phased constructor.

    53     *  @param aMaximumSizeRatio maximum cache size in percentage ratio

    54     *         If not specified the cache does not have a limit

    55     *  @return Constructed object

    56     */

    57     static CMPXCollectionCache* NewL(TInt aMaximumSizeRatio = -1);

    58 

    59     /**

    60     *  Destructor

    61     */

    62     virtual ~CMPXCollectionCache();

    63 

    64 public:

    65     /**

    66     *  Cache entry priority values. Entries with lower priority will be discarded

    67     *  sooner than the ones with higher priority.

    68     */

    69     enum TCachePriority

    70         {

    71         EPriorityLow,

    72         EPriorityNormal,

    73         EPriorityHigh

    74         };

    75 

    76 public:

    77     /**

    78     *  Adds a result set to the cache.

    79     *  @param aPath path defining the context of the results.

    80     *  @param aAttrs attributes requested by the client application and included in

    81     *         the result set.

    82     *  @param aResults result set corresponding to the path.  Not owned.

    83     *  @param aNotCacheableAttrs attributes that are not cacheable

    84     *  @param aMediaFromOpenL whether or not this media was from an OpenL

    85     *  @param aPriority result set priority

    86     *  @return CMPXMedia object in the cache or the original object if add failed

    87     */

    88     CMPXMedia* AddL(

    89         const CMPXCollectionPath& aPath, 

    90         const TArray<TMPXAttribute>& aAttrs,

    91         CMPXMedia& aResults, 

    92         TBool aMediaFromOpenL = EFalse,

    93         TCachePriority aPriority = EPriorityNormal );

    94 

    95     /**

    96     *  Returns the information corresponding to the specified path and attribute set

    97     *  if available in the cache.

    98     *  @param aPath path defining the information context.

    99     *  @param aAttrs attribute set requested by the client.

   100     *  @return Valid results or NULL if the path/attribute set specified cannot be

   101     *          found in the cache.

   102     */

   103     CMPXMedia* GetL(

   104         const CMPXCollectionPath& aPath,

   105         const TArray<TMPXAttribute>& aAttrs,

   106         TBool aMediaFromOpenL = EFalse );

   107 

   108     /**

   109     *  Removes the specified path and all its children from the cache.

   110     *  @param aPath path defining the context to be removed.

   111     */

   112     void RemoveL(const CMPXCollectionPath& aPath);

   113 

   114     /**

   115     * Resets cache and removes all nodes

   116     */

   117     void Reset();

   118 

   119     /**

   120     * Handle some change from the collection

   121     * @param aCollectionId collectoin that the change is comming from

   122     * @param aChangeItemId item ID of the changed event

   123     */

   124     void HandleChangeL( TUid aCollectionId, TMPXItemId aChangeItemId );

   125     

   126 private:

   127 

   128     /**

   129     *  C++ constructor

   130     *  @param aMaximumSizeKb maximum cache size in percentage ratio.

   131     */

   132     CMPXCollectionCache(TInt aMaximumSizeRatio);

   133 

   134     /**

   135     *  2nd phase contructor

   136     */

   137     void ConstructL();

   138 

   139     /**

   140     *  Returns the cache node corresponding to the specified path.

   141     *  @param aPath path to be looked up in the cache.

   142     *  @param aCreateNodes if ETrue all the missing nodes for the specified

   143     *         path will be created if they do not already exist. If EFalse

   144     *         the method returns NULL if corresponding node is not found.

   145     *  @return valid cache node if found or created, NULL if not found.

   146     */

   147     CMPXCollectionCacheNode* NodeFromPathL(const CMPXCollectionPath& aPath,

   148         TBool aCreateNodes = EFalse);

   149         

   150     /**

   151     *  Removes a specified node and all its children from the cache.

   152     *  @param aNode node to be removed.  Ownership is transferred.

   153     */

   154     void RemoveNode(CMPXCollectionCacheNode* aNode);

   155     

   156     /**

   157     *  Checks the memory condition and clears cache to free some memory

   158     *  maximum percentage ratio specified in the constructor is used to detect

   159     *  low memory condition

   160     *  @return EFalse if low memory condition detected, ETrue otherwise 

   161     */

   162     TBool ManageCacheSizeL();

   163 

   164 #ifdef _DEBUG

   165     /**

   166     *  Prints the cache tree.

   167     */

   168     void PrintTree( TBool aPrintAtts = EFalse );

   169 #endif

   170     

   171 private:

   172     /**

   173     *  Root node for the cache tree, created when the cache is created.

   174     */

   175     CMPXCollectionCacheNode* iRoot;

   176 

   177     /**

   178     *  Maximum size of the cache in percentage ratio, specified by the client.

   179     */

   180     TInt iMaximumSizeRatio;

   181     };

   182 

   183 #endif // MPXCOLLECTIONCACHE_H

   184