epoc32/include/app/cacheman.h
branchSymbian2
changeset 3 e1b950c65cb4
parent 2 2fe1408b6811
child 4 837f303aceeb
     1.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
     1.2 +++ b/epoc32/include/app/cacheman.h	Wed Mar 31 12:27:01 2010 +0100
     1.3 @@ -0,0 +1,295 @@
     1.4 +// Copyright (c) 1999-2009 Nokia Corporation and/or its subsidiary(-ies).
     1.5 +// All rights reserved.
     1.6 +// This component and the accompanying materials are made available
     1.7 +// under the terms of the License "Symbian Foundation License v1.0" to Symbian Foundation members and "Symbian Foundation End User License Agreement v1.0" to non-members
     1.8 +// which accompanies this distribution, and is available
     1.9 +// at the URL "http://www.symbianfoundation.org/legal/licencesv10.html".
    1.10 +//
    1.11 +// Initial Contributors:
    1.12 +// Nokia Corporation - initial contribution.
    1.13 +//
    1.14 +// Contributors:
    1.15 +//
    1.16 +// Description:
    1.17 +//
    1.18 +
    1.19 +#if !defined (__CACHEMAN_H__)
    1.20 +#define __CACHEMAN_H__
    1.21 +
    1.22 +#include <mentact.h>
    1.23 +#include <msvstd.h>
    1.24 +#include <msvapi.h>
    1.25 +
    1.26 +_LIT(KMiutWildCard, "*.*");
    1.27 +
    1.28 +class CImFinder : public CMsgActive
    1.29 +/**
    1.30 +@internalComponent
    1.31 +@released
    1.32 +*/
    1.33 +	{
    1.34 +public:
    1.35 +	IMPORT_C void FindFirstL(TMsvId aRootEntry, TRequestStatus &aStatus);
    1.36 +	IMPORT_C ~CImFinder();
    1.37 +	IMPORT_C virtual void FindNextL(TRequestStatus &aStatus);
    1.38 +	void FindFirstL(const CMsvEntrySelection& aInitialSelection, TRequestStatus &aStatus);
    1.39 +
    1.40 +	class CImEntryStack : public CBase
    1.41 +		{
    1.42 +	public:
    1.43 +		static CImEntryStack* NewL();
    1.44 +		~CImEntryStack();
    1.45 +		inline void PushL(TMsvId aId);
    1.46 +		inline TMsvId PopL();
    1.47 +		inline TBool Empty() const;
    1.48 +		inline void Reset();
    1.49 +
    1.50 +	private:
    1.51 +		void ConstructL();
    1.52 +
    1.53 +		CMsvEntrySelection* iFolders;
    1.54 +		};
    1.55 +
    1.56 +protected:
    1.57 +	void ConstructL();
    1.58 +	CImFinder(CMsvEntry& aEntry);
    1.59 +
    1.60 +private:
    1.61 +	void DoRunL();
    1.62 +
    1.63 +	virtual void AddChildEntriesL() = 0;
    1.64 +	virtual TBool IsRequiredEntryType(TUid aEntryType) const = 0;
    1.65 +
    1.66 +protected:
    1.67 +	CImEntryStack* iEntryStack;
    1.68 +	CMsvEntry& iCurrentEntry;
    1.69 +
    1.70 +private:
    1.71 +	enum TImmfState
    1.72 +		{
    1.73 +		EImmfEntryFound,
    1.74 +		EImmfFindingEntry,
    1.75 +		EImmfNothingFound
    1.76 +		};
    1.77 +
    1.78 +	TImmfState iState;
    1.79 +	};
    1.80 +
    1.81 +
    1.82 +class CImMessageFinder : public CImFinder
    1.83 +/**
    1.84 +@internalComponent
    1.85 +@released
    1.86 +*/
    1.87 +	{
    1.88 +public:
    1.89 +	IMPORT_C static CImMessageFinder* NewL(CMsvEntry& aEntry);
    1.90 +	IMPORT_C static CImMessageFinder* NewLC(CMsvEntry& aEntry);
    1.91 +	
    1.92 +protected:
    1.93 +	virtual void AddChildEntriesL();
    1.94 +	virtual TBool IsRequiredEntryType(TUid aEntryType) const;
    1.95 +
    1.96 +	CImMessageFinder(CMsvEntry& aEntry);
    1.97 +	};
    1.98 +
    1.99 +
   1.100 +class CImEntryFinder : public CImFinder
   1.101 +/**
   1.102 +@internalComponent
   1.103 +@released
   1.104 +*/
   1.105 +	{
   1.106 +public:
   1.107 +	IMPORT_C static CImEntryFinder* NewL(CMsvEntry& aEntry);
   1.108 +	IMPORT_C static CImEntryFinder* NewLC(CMsvEntry& aEntry);
   1.109 +	
   1.110 +protected:
   1.111 +	virtual void AddChildEntriesL();
   1.112 +	virtual TBool IsRequiredEntryType(TUid aEntryType) const;
   1.113 +
   1.114 +	CImEntryFinder(CMsvEntry& aEntry);
   1.115 +	};
   1.116 +
   1.117 +
   1.118 +class CImMessageCounter : public CImFinder
   1.119 +/**
   1.120 +@internalComponent
   1.121 +@released
   1.122 +*/
   1.123 +	{
   1.124 +public:
   1.125 +	IMPORT_C static CImMessageCounter* NewL(CMsvEntry& aEntry);
   1.126 +	IMPORT_C static CImMessageCounter* NewLC(CMsvEntry& aEntry);
   1.127 +	IMPORT_C TInt Count();
   1.128 +	
   1.129 +protected:
   1.130 +	virtual void AddChildEntriesL();
   1.131 +	virtual TBool IsRequiredEntryType(TUid aEntryType) const;
   1.132 +
   1.133 +	CImMessageCounter(CMsvEntry& aEntry);
   1.134 +
   1.135 +private:
   1.136 +	TInt iCount;
   1.137 +	};
   1.138 +
   1.139 +
   1.140 +class CImPruneMessage : public CMsgActive
   1.141 +/** Deletes the body text and attachment data from an individually specified message. 
   1.142 +
   1.143 +Example uses of this class are:
   1.144 +
   1.145 +1. to cleanup after a populating operation has failed
   1.146 +
   1.147 +2. to remove body text and attachment data from remote messages, while preserving 
   1.148 +the message structure 
   1.149 +@publishedPartner 
   1.150 +@released
   1.151 +*/
   1.152 +	{
   1.153 +public:
   1.154 +	IMPORT_C static CImPruneMessage* NewL(CMsvEntry& aEntry, RFs& aFs);
   1.155 +	IMPORT_C static CImPruneMessage* NewLC(CMsvEntry& aEntry, RFs& aFs);
   1.156 +
   1.157 +	IMPORT_C void StartL(TMsvId aMessageEntry, TRequestStatus &aStatus);
   1.158 +	~CImPruneMessage();
   1.159 +	
   1.160 +private:
   1.161 +	CImPruneMessage(CMsvEntry& aEntry, RFs& aFs);
   1.162 +	void ConstructL();
   1.163 +	void DoRunL();
   1.164 +	void DoComplete(TInt& );
   1.165 +	void DoCancel();
   1.166 +	void PruneEntryL();
   1.167 +	void ResetStoreL();
   1.168 +
   1.169 +private:
   1.170 +	enum TImPruningState
   1.171 +		{
   1.172 +		EImPruneUpdatingEntry,
   1.173 +		EImPruneUpdatingFirstEntry,
   1.174 +		EImPruneFindingEntry,
   1.175 +		EImPruneFindFirstEntry,
   1.176 +		EImPruneFindNextEntry
   1.177 +		};
   1.178 +
   1.179 +	TImPruningState iState;
   1.180 +
   1.181 +	CMsvEntry& iCurrentEntry;
   1.182 +	RFs& iFs;
   1.183 +	CImEntryFinder* iEntryFinder;
   1.184 +	CFileMan* iFileManager;
   1.185 +	TMsvId iRootEntryId;
   1.186 +	CMsvOperation* iChangeOperation;
   1.187 +	CMsvStore* iStore;
   1.188 +	};
   1.189 +
   1.190 +struct TImCacheManagerProgress
   1.191 +/** Holds progress of a cache management cleanup operation.
   1.192 +
   1.193 +@see CImCacheManager::ProgressL() 
   1.194 +@publishedAll
   1.195 +@released
   1.196 +*/
   1.197 +	{
   1.198 +public:
   1.199 +	/** Total number of messages to process.
   1.200 +	
   1.201 +	Note that, immediately after a CImCacheManager object is started, the progress 
   1.202 +	operation may return 1 for iTotalMessages and 0 for iMessagesProcessed, regardless 
   1.203 +	of the total number of messages. This is because the counter for the iTotalMessages 
   1.204 +	operates asynchronously and may not have counted all of the messages at that 
   1.205 +	time. */
   1.206 +	TInt iTotalMessages;
   1.207 +	/** Number of messages processed so far. */
   1.208 +	TInt iMessagesProcessed;
   1.209 +	};
   1.210 +
   1.211 +class CImCacheManager : public CMsvOperation
   1.212 +/** Provides management of the local cache of messages in remote mailboxes.
   1.213 +
   1.214 +A mailbox that is being used in disconnected mode allows the user access to 
   1.215 +message data by opening the message directly from the remote mailbox. If the 
   1.216 +required message has been downloaded previously, then it will not necessarily 
   1.217 +need to be downloaded again. This functionality is achieved by preserving 
   1.218 +the message data locally, under the remote service entry. The preserved message 
   1.219 +data acts as a cache to allow the user access to the message without the need 
   1.220 +for it to be downloaded every time. 
   1.221 +
   1.222 +The cache management functionality is required to reduce the amount of memory 
   1.223 +that is consumed by the message cache. CImCacheManager provides a mechanism 
   1.224 +for asynchronously traversing a message tree and for removing text and attachment 
   1.225 +data from messages. Deleting more message data will free up more memory but 
   1.226 +there is a higher chance that a user will need to download a message for a 
   1.227 +second time. 
   1.228 +
   1.229 +CImCacheManager is an abstract base class, which can be specialised to implement 
   1.230 +a filter (Filter()) that decides if data for a message shoulded be deleted: 
   1.231 +for example, deletion could be restricted to 'all read messages over a week 
   1.232 +old,' or, 'all read messages, over 20K in size which are also over a day old.' 
   1.233 +@publishedAll
   1.234 +@released
   1.235 +*/
   1.236 +	{
   1.237 +public:
   1.238 +	IMPORT_C void StartL(TMsvId aRootEntry, TRequestStatus &aStatus);
   1.239 +	IMPORT_C void StartL(const CMsvEntrySelection& aSelection, TRequestStatus &aStatus);
   1.240 +	IMPORT_C ~CImCacheManager();
   1.241 +	IMPORT_C const TDesC8& ProgressL();
   1.242 +	IMPORT_C void DoCancel();
   1.243 +
   1.244 +protected:
   1.245 +	IMPORT_C void ConstructL();
   1.246 +	IMPORT_C CImCacheManager(CMsvSession& aSession, TRequestStatus& aObserverRequestStatus);
   1.247 +
   1.248 +	IMPORT_C void RunL();
   1.249 +
   1.250 +private:
   1.251 +	// Override this function to filter the currently selected message (iCurrentEntry).
   1.252 +	// Return TRUE if the current entry is to be pruned.
   1.253 +	/** Tests if cache cleanup should be performed on a message entry.
   1.254 +	
   1.255 +	After StartL() has been called, this is called once for each message entry. 
   1.256 +	It should return true if the body text and attachment data belonging to the 
   1.257 +	current message, as held in iCurrentEntry, should be deleted, or false if 
   1.258 +	the message should be left unchanged.
   1.259 +	
   1.260 +	This function must be implemented in any classes derived from CImCacheManager.
   1.261 +	
   1.262 +	@return True to clean the entry, false to leave it unchanged */
   1.263 +	virtual TBool Filter() const = 0;
   1.264 +
   1.265 +	void DoRunL();
   1.266 +
   1.267 +	// Remove the store from the currently selected entry
   1.268 +	inline void PruneMessageL();
   1.269 +	
   1.270 +protected:
   1.271 +	/** Message entry currently being processed. */
   1.272 +	CMsvEntry* iCurrentEntry;
   1.273 +
   1.274 +private:
   1.275 +	CMsvSession& iSession;
   1.276 +	CImMessageFinder* iMessageFinder;
   1.277 +	CImMessageCounter* iMessageCounter;
   1.278 +	CMsvOperation* iDeleteOperation;
   1.279 +
   1.280 +	TImCacheManagerProgress iProgress;
   1.281 +	TRequestStatus* iReport;
   1.282 +
   1.283 +	enum TImcmState
   1.284 +		{
   1.285 +		EImcmLookingForMessage,
   1.286 +		EImcmPruningMessages,
   1.287 +		EImcmCountingMessages,
   1.288 +		EImcmSkippingPrune
   1.289 +		};
   1.290 +
   1.291 +	TMsvId iRootEntry;
   1.292 +	TImcmState iState;
   1.293 +	TPckgBuf<TImCacheManagerProgress> iProgressBuf;
   1.294 +
   1.295 +	CMsvEntrySelection* iMessagesToPrune;
   1.296 +	};
   1.297 +
   1.298 +#endif