diff -r 666f914201fb -r 2fe1408b6811 epoc32/include/s32stor.h --- a/epoc32/include/s32stor.h Tue Nov 24 13:55:44 2009 +0000 +++ b/epoc32/include/s32stor.h Tue Mar 16 16:12:26 2010 +0000 @@ -1,1 +1,482 @@ -s32stor.h +// Copyright (c) 1998-2009 Nokia Corporation and/or its subsidiary(-ies). +// All rights reserved. +// This component and the accompanying materials are made available +// 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 +// which accompanies this distribution, and is available +// at the URL "http://www.symbianfoundation.org/legal/licencesv10.html". +// +// Initial Contributors: +// Nokia Corporation - initial contribution. +// +// Contributors: +// +// Description: +// + +#if !defined(__S32STOR_H__) +#define __S32STOR_H__ +#if !defined(__S32STD_H__) +#include +#endif +#if !defined(__S32SHARE_H__) +#include +#endif +#if !defined(__S32PAGE_H__) +#include +#endif + +class MIncrementalCollector; +/** + * @publishedAll + * @released + * Provides the core abstract framework for stores allowing streams to be +created and manipulated. +*/ +class CStreamStore : public CBase + { +public: + inline TStreamId ExtendL(); + IMPORT_C void Delete(TStreamId anId); + IMPORT_C void DeleteL(TStreamId anId); +// + IMPORT_C TInt Commit(); + inline void CommitL(); + IMPORT_C void Revert(); + inline void RevertL(); +// + IMPORT_C TInt ReclaimL(); + IMPORT_C TInt CompactL(); +private: + virtual IMPORT_C TStreamId DoExtendL(); + virtual IMPORT_C void DoDeleteL(TStreamId anId); + + /** Opens the requested stream for reading. The function should return a + stream buffer positioned at the beginning of this stream. + + This function is called by the OpenL() and OpenLC() member functions of + RStoreReadStream. + + @param anId The stream to be read. + @return A stream buffer positioned at the beginning of the stream to be read. + @see RStoreReadStream::OpenL() + @see RStoreReadStream::OpenLC() */ + virtual MStreamBuf* DoReadL(TStreamId anId) const=0; + + /** Creates a new stream in the store. The function gets the allocated + stream id in the anId parameter. A stream buffer for the stream should be + returned, ready to write into the new stream. This provides the + implementation for the RStoreWriteStream::CreateL() functions. + + @param anId On return, contains the allocated stream id. + @return The stream buffer to be written to. */ + virtual MStreamBuf* DoCreateL(TStreamId& anId)=0; + virtual IMPORT_C MStreamBuf* DoWriteL(TStreamId anId); + virtual IMPORT_C MStreamBuf* DoReplaceL(TStreamId anId); + virtual IMPORT_C void DoCommitL(); + virtual IMPORT_C void DoRevertL(); + virtual IMPORT_C MIncrementalCollector* DoReclaimL(); + virtual IMPORT_C MIncrementalCollector* DoCompactL(); +private: + friend class RStoreReadStream; + friend class RStoreWriteStream; + friend class RStoreReclaim; + }; + +/** + * @publishedAll + * @released + * Persistent store abstract base class. It provides the behaviour for setting +and retrieving the root stream id. + +Before closing a persistent store, the root stream id must be set. After opening +a persistent store, the first thing done is to look up the root stream id. +The root stream can then be opened and data read from the store. + +@see CFileStore +*/ +class CPersistentStore : public CStreamStore + { +public: + inline TStreamId Root() const; + inline void SetRootL(TStreamId anId); +protected: + inline CPersistentStore(); +private: + virtual IMPORT_C void DoSetRootL(TStreamId anId); +protected: + TStreamId iRoot; + }; + +/** + * @publishedAll + * @released + * Performs space reclamation or compaction on a permanent file store in +incremental steps. + +Reclaiming unused space makes it available for re-use by the store. Compacting +makes unused space available for re-use by the relevant system pool — for +example, the filing system in the case of file-based stores. + +Once compaction is complete, the store must be committed. + +Notes: + +Space reclamation and compaction are only supported by the file store +CPermanentFileStore and are not supported by embedded or direct file stores. + +Use active objects when implementing space reclamation or compaction +asynchronously. + +This class performs incremental compaction/reclamation. These operations can +be performed in a possibly long running single step using CStreamStore +functions. +*/ +class RStoreReclaim + { +public: + inline RStoreReclaim(); + IMPORT_C void OpenL(CStreamStore& aStore,TInt& aCount); + IMPORT_C void OpenLC(CStreamStore& aStore,TInt& aCount); + IMPORT_C void CompactL(CStreamStore& aStore,TInt& aCount); + IMPORT_C void CompactLC(CStreamStore& aStore,TInt& aCount); + inline void Close(); + IMPORT_C void Release(); +// + IMPORT_C void ResetL(TInt& aCount); + IMPORT_C void NextL(TInt& aStep); + IMPORT_C void Next(TPckgBuf& aStep,TRequestStatus& aStatus); + IMPORT_C void NextL(TPckgBuf& aStep,TRequestStatus& aStatus); + IMPORT_C TInt Next(TInt& aStep); +// + inline TInt Available() const; +private: + MIncrementalCollector* iCol; + TPckgBuf iAvail; + }; + +/** + * @publishedAll + * @released + * Encapsulates an embedded store. + +The embedded store may contain an arbitrarily complex network of streams, +but is viewed as simply another stream by the embedding store. This means +that the embedded store can dealt with as a single stream for purposes of +copying or deleting. + +Once streams within the embedded store have been committed and closed, they +cannot subsequently be changed, i.e. streams cannot be replaced, deleted, +extended or changed in any way. + +@see CPersistentStore +*/ +class CEmbeddedStore : public CPersistentStore + { +public: + IMPORT_C static CEmbeddedStore* FromL(RReadStream& aHost); + IMPORT_C static CEmbeddedStore* FromLC(RReadStream& aHost); + IMPORT_C static CEmbeddedStore* NewL(RWriteStream& aHost); + IMPORT_C static CEmbeddedStore* NewLC(RWriteStream& aHost); +// + inline static TStreamPos Position(TStreamId anId); +// + IMPORT_C void Detach(); + inline void Reattach(MStreamBuf* aHost); + inline MStreamBuf* Host() const; + inline TStreamPos Start() const; +// + IMPORT_C CEmbeddedStore(MStreamBuf* aHost); + IMPORT_C void MarshalL(RReadStream& aStream); + IMPORT_C void ConstructL(RWriteStream& aStream); + IMPORT_C ~CEmbeddedStore(); +protected: + IMPORT_C MStreamBuf* DoReadL(TStreamId anId) const; + IMPORT_C MStreamBuf* DoCreateL(TStreamId& anId); +private: + IMPORT_C void DoSetRootL(TStreamId anId); + IMPORT_C void DoCommitL(); +// + static CEmbeddedStore* DoNewLC(MStreamBuf* aHost); +private: + __MUTABLE TStreamExchange iHost; + TStreamPos iStart; + }; + +/** + * @publishedAll + * @released + * Dictionary store interface. + +This is an abstract class which provides the necessary interface for using +concrete dictionary stores. + +A dictionary store is a store where a stream is accessed by UID (TUid), rather +than directly by stream id (TStreamId). + +This type of store contains streams in the usual way but, in addition, the +root stream is a stream dictionary. The stream dictionary provides a list +of two-way associations between unique identifiers and stream ids. + +Note that a dictionary store object does not derive from CStreamStore, but +owns a persistent store and a stream dictionary as part of its implementation. + +@see CStreamDictionary +@see CPersistentStore +@see CDictionaryFileStore +@see TUid +@see TStreamId +*/ +class CDictionaryStore : public CBase + { +public: + IMPORT_C TBool IsNullL() const; + IMPORT_C TBool IsPresentL(TUid aUid) const; + IMPORT_C void Remove(TUid aUid); + IMPORT_C void RemoveL(TUid aUid); +// + IMPORT_C TInt Commit(); + IMPORT_C void CommitL(); + IMPORT_C void Revert(); + IMPORT_C void RevertL(); +// + IMPORT_C ~CDictionaryStore(); +protected: + IMPORT_C void ConstructL(); +private: + CStreamDictionary* DictionaryL() const; + MStreamBuf* GetSourceL(TUid aUid) const; + MStreamBuf* GetSinkL(TUid aUid); +protected: + CPersistentStore* iStore; +private: + __MUTABLE CStreamDictionary* iDictionary; + TBool iDictionaryHasChanged; +private: + friend class RDictionaryReadStream; + friend class RDictionaryWriteStream; + friend class HDictionaryStoreBuf; + }; +// +const TInt KDictionaryCommitThreshold = 1024; + +/** + * @publishedAll + * @released + * Supports the opening and manipulation of a stream in a dictionary store. + +Construct an object of this type to open an existing stream in a dictionary +store for reading. + +@see CDictionaryStore +*/ +class RDictionaryReadStream : public RReadStream +{ +public: + IMPORT_C void OpenL(const CDictionaryStore& aDictStore,TUid aUid); + IMPORT_C void OpenLC(const CDictionaryStore& aDictStore,TUid aUid); + }; + +/** + * @publishedAll + * @released + * Supports the creation or replacement of a stream a dictionary store. + +@see CDictionaryStore +*/ +class RDictionaryWriteStream : public RWriteStream + { +public: + /** Constructs an uninitialised object. It is necessary because there are + also non-default constructors in this class. */ + RDictionaryWriteStream() {} + inline RDictionaryWriteStream(const MExternalizer& anExter); + IMPORT_C void AssignL(CDictionaryStore& aDictStore,TUid aUid); + IMPORT_C void AssignLC(CDictionaryStore& aDictStore,TUid aUid); + }; + +/** + * @publishedAll + * @released + * Persistent settings to use for a RStorePagePool. + +@see RStorePagePool +*/ +class TStorePagePoolToken + { +public: + /** Provides a TStorePagePoolToken initialisation flag. */ + enum TEmpty + /** Initialise for an empty page pool flag. */ + {EEmpty}; +public: + /** Default constructor. */ + TStorePagePoolToken() {} + + /** Constructor that intialises the TStorePagePoolToken for an empty page pool. + + @param Intialises for an empty page pool */ + inline TStorePagePoolToken(TEmpty); + inline void Touch(); +// + inline TBool HasAvailable() const; + inline TBool IsEmpty() const; +// + IMPORT_C void ExternalizeL(RWriteStream& aStream) const; + IMPORT_C void InternalizeL(RReadStream& aStream); +private: + inline TStorePagePoolToken(TStreamId aHead,TPageRef anAvail); +private: + TStreamId iHead; + TPageRef iAvail; +private: + friend class RStorePagePool; + }; +#if defined(__NO_CLASS_CONSTS__) +#define KEmptyStorePagePoolToken TStorePagePoolToken(TStorePagePoolToken::EEmpty) +#else +/** Defines a TStorePagePoolToken object initialised for an empty page pool. */ +const TStorePagePoolToken KEmptyStorePagePoolToken=TStorePagePoolToken::EEmpty; +#endif + +/** + * @publishedAll + * @released + * Uses a store to implement the page pool interface MPagePool. + +Pages can be reclaimable (tracked by the page pool, so that they can be freed +when required) or not (in which case they must be deleted explicitly): this +is indicated by a flag of type TPageReclamation. Non-reclaimable pages each +have their own stream in the store; reclaimable pages are bundled 15 to a +stream. To track the reclaimable pages, the page pool has a separate token, +type TStorePagePoolToken, that must be saved by the user of the pool. + +The store used must support CStreamStore::ExtendL(), CStreamStore::DeleteL() +and allow streams to be re-written. CPermanentFileStore meets these conditions. + +A store page pool uses a cache to store pages in-memory and to cache frequently +accessed pages. You should provide a cache object (CPageCache) to the pool +for this purpose. + +@see CPageCache +@see CPermanentFileStore +@see CStreamStore +@see TPageReclamation +*/ +class RStorePagePool : public TCachePagePool + { + friend class StorePagePool; +public: + IMPORT_C RStorePagePool(); + IMPORT_C RStorePagePool(CPageCache& aCache); + IMPORT_C RStorePagePool(CStreamStore& aStore); + IMPORT_C RStorePagePool(CStreamStore& aStore,const TStorePagePoolToken& aToken); + IMPORT_C void Create(CStreamStore& aStore); + IMPORT_C void Open(CStreamStore& aStore,const TStorePagePoolToken& aToken); + IMPORT_C TStorePagePoolToken Token() const; + IMPORT_C void Close(); + inline void Release(); +// + inline TBool IsDirty() const; + inline void MarkCurrent(); + inline void MarkDirty(); +// + inline TBool HasAvailable() const; + inline void Discard(); +// + inline TBool IsEmpty() const; + IMPORT_C TBool ReclaimL(); + IMPORT_C void ReclaimAllL(); +protected: + IMPORT_C TPageRef ExtendL(const TAny* aPage,TPageReclamation aReclamation); + IMPORT_C void WriteL(TPageRef aRef,const TAny* aPage,TPageChange aChange); + IMPORT_C void ReadL(TPageRef aRef,TAny* aPage); + IMPORT_C void DoDeleteL(TPageRef aRef); +private: + inline void CacheDeleteL(TPageRef aRef); +private: + CStreamStore* iStore; + TStreamId iHead; + TPageRef iAvail; + TBool iDirty; + }; + +/** + * @publishedAll + * @released + * Interface for incrementally reclaiming or compacting space in a stream store. +The interface allows these actions to be performed in small steps, so that +applications can remain responsive while doing these potentially long-running +tasks. + +An instance of a class derived from this interface is returned by +StreamStore::DoReclaimL() and DoCompactL(). Each step is carried out in +response to a call of DoNextL() and the object is released on completion of +the last step. + +Notes: + +One-step reclaim using CStreamStore::ReclaimL() is actually implemented in +terms of the incremental collector. + +A CStreamStore implementation will only need to implement a collector class +if it supports reclamation or compaction. +*/ +class MIncrementalCollector + { +public: + inline void Close(); + inline void Release(); +// + inline void ResetL(TInt& aCount); + inline void NextL(TInt& aStep,TInt& aTotal); + inline void NextL(TPckgBuf& aStep,TRequestStatus& aStatus,TPckgBuf& aTotal); +protected: + /** Protected constructor. Protecting the constructor ensures that this + abstract class cannot be instantiated. + + MIncrementalCollector(const MIncrementalCollector&); + + MIncrementalCollector& operator=(const MIncrementalCollector&); + + Private copy constructor and copy assignment to prevent */ + MIncrementalCollector() {} +private: + /** Protected constructor. Protecting the constructor ensures that this + abstract class cannot be instantiated. + + MIncrementalCollector(const MIncrementalCollector&); + + MIncrementalCollector& operator=(const MIncrementalCollector&); + + Private copy constructor and copy assignment to prevent */ + MIncrementalCollector(const MIncrementalCollector&); + MIncrementalCollector& operator=(const MIncrementalCollector&); +// + virtual IMPORT_C void DoRelease(); + + /** Implementation of the public ResetL() function. This signals that the + client wants to start or retsart the operation from the beginning. A new + progress count should be returned in aCount. + + @param aCount On return, contains a progress count for the + reclamation/compaction process. */ + virtual void DoResetL(TInt& aCount)=0; + + /** Implementation of the public synchronous NextL() function. The next + step in the reclamation should be done, reporting progress in aStep and + aTotal. + + @param aStep The progress value from either the last NextL() increment of + from ResetL() if the reclamation/compaction was restarted. On return, + should contain the new progress value, which can be used in subsequent + calls to NextL(). This must be equal to, or less than, the previous + value — a zero value must be used to indicate that the operation is + complete. + @param aTotal On return, should contain the total amount of free space in + the store. */ + virtual void DoNextL(TInt& aStep,TInt& aTotal)=0; + virtual IMPORT_C void DoNextL(TPckgBuf& aStep,TRequestStatus& aStatus,TPckgBuf& aTotal); + }; + +#include +#endif