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