1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/os/persistentdata/persistentstorage/store/INC/S32STOR.H Fri Jun 15 03:10:57 2012 +0200
1.3 @@ -0,0 +1,482 @@
1.4 +// Copyright (c) 1998-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 "Eclipse Public License v1.0"
1.8 +// which accompanies this distribution, and is available
1.9 +// at the URL "http://www.eclipse.org/legal/epl-v10.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(__S32STOR_H__)
1.20 +#define __S32STOR_H__
1.21 +#if !defined(__S32STD_H__)
1.22 +#include <s32std.h>
1.23 +#endif
1.24 +#if !defined(__S32SHARE_H__)
1.25 +#include <s32share.h>
1.26 +#endif
1.27 +#if !defined(__S32PAGE_H__)
1.28 +#include <s32page.h>
1.29 +#endif
1.30 +
1.31 +class MIncrementalCollector;
1.32 +/**
1.33 + * @publishedAll
1.34 + * @released
1.35 + * Provides the core abstract framework for stores allowing streams to be
1.36 +created and manipulated.
1.37 +*/
1.38 +class CStreamStore : public CBase
1.39 + {
1.40 +public:
1.41 + inline TStreamId ExtendL();
1.42 + IMPORT_C void Delete(TStreamId anId);
1.43 + IMPORT_C void DeleteL(TStreamId anId);
1.44 +//
1.45 + IMPORT_C TInt Commit();
1.46 + inline void CommitL();
1.47 + IMPORT_C void Revert();
1.48 + inline void RevertL();
1.49 +//
1.50 + IMPORT_C TInt ReclaimL();
1.51 + IMPORT_C TInt CompactL();
1.52 +private:
1.53 + virtual IMPORT_C TStreamId DoExtendL();
1.54 + virtual IMPORT_C void DoDeleteL(TStreamId anId);
1.55 +
1.56 + /** Opens the requested stream for reading. The function should return a
1.57 + stream buffer positioned at the beginning of this stream.
1.58 +
1.59 + This function is called by the OpenL() and OpenLC() member functions of
1.60 + RStoreReadStream.
1.61 +
1.62 + @param anId The stream to be read.
1.63 + @return A stream buffer positioned at the beginning of the stream to be read.
1.64 + @see RStoreReadStream::OpenL()
1.65 + @see RStoreReadStream::OpenLC() */
1.66 + virtual MStreamBuf* DoReadL(TStreamId anId) const=0;
1.67 +
1.68 + /** Creates a new stream in the store. The function gets the allocated
1.69 + stream id in the anId parameter. A stream buffer for the stream should be
1.70 + returned, ready to write into the new stream. This provides the
1.71 + implementation for the RStoreWriteStream::CreateL() functions.
1.72 +
1.73 + @param anId On return, contains the allocated stream id.
1.74 + @return The stream buffer to be written to. */
1.75 + virtual MStreamBuf* DoCreateL(TStreamId& anId)=0;
1.76 + virtual IMPORT_C MStreamBuf* DoWriteL(TStreamId anId);
1.77 + virtual IMPORT_C MStreamBuf* DoReplaceL(TStreamId anId);
1.78 + virtual IMPORT_C void DoCommitL();
1.79 + virtual IMPORT_C void DoRevertL();
1.80 + virtual IMPORT_C MIncrementalCollector* DoReclaimL();
1.81 + virtual IMPORT_C MIncrementalCollector* DoCompactL();
1.82 +private:
1.83 + friend class RStoreReadStream;
1.84 + friend class RStoreWriteStream;
1.85 + friend class RStoreReclaim;
1.86 + };
1.87 +
1.88 +/**
1.89 + * @publishedAll
1.90 + * @released
1.91 + * Persistent store abstract base class. It provides the behaviour for setting
1.92 +and retrieving the root stream id.
1.93 +
1.94 +Before closing a persistent store, the root stream id must be set. After opening
1.95 +a persistent store, the first thing done is to look up the root stream id.
1.96 +The root stream can then be opened and data read from the store.
1.97 +
1.98 +@see CFileStore
1.99 +*/
1.100 +class CPersistentStore : public CStreamStore
1.101 + {
1.102 +public:
1.103 + inline TStreamId Root() const;
1.104 + inline void SetRootL(TStreamId anId);
1.105 +protected:
1.106 + inline CPersistentStore();
1.107 +private:
1.108 + virtual IMPORT_C void DoSetRootL(TStreamId anId);
1.109 +protected:
1.110 + TStreamId iRoot;
1.111 + };
1.112 +
1.113 +/**
1.114 + * @publishedAll
1.115 + * @released
1.116 + * Performs space reclamation or compaction on a permanent file store in
1.117 +incremental steps.
1.118 +
1.119 +Reclaiming unused space makes it available for re-use by the store. Compacting
1.120 +makes unused space available for re-use by the relevant system pool — for
1.121 +example, the filing system in the case of file-based stores.
1.122 +
1.123 +Once compaction is complete, the store must be committed.
1.124 +
1.125 +Notes:
1.126 +
1.127 +Space reclamation and compaction are only supported by the file store
1.128 +CPermanentFileStore and are not supported by embedded or direct file stores.
1.129 +
1.130 +Use active objects when implementing space reclamation or compaction
1.131 +asynchronously.
1.132 +
1.133 +This class performs incremental compaction/reclamation. These operations can
1.134 +be performed in a possibly long running single step using CStreamStore
1.135 +functions.
1.136 +*/
1.137 +class RStoreReclaim
1.138 + {
1.139 +public:
1.140 + inline RStoreReclaim();
1.141 + IMPORT_C void OpenL(CStreamStore& aStore,TInt& aCount);
1.142 + IMPORT_C void OpenLC(CStreamStore& aStore,TInt& aCount);
1.143 + IMPORT_C void CompactL(CStreamStore& aStore,TInt& aCount);
1.144 + IMPORT_C void CompactLC(CStreamStore& aStore,TInt& aCount);
1.145 + inline void Close();
1.146 + IMPORT_C void Release();
1.147 +//
1.148 + IMPORT_C void ResetL(TInt& aCount);
1.149 + IMPORT_C void NextL(TInt& aStep);
1.150 + IMPORT_C void Next(TPckgBuf<TInt>& aStep,TRequestStatus& aStatus);
1.151 + IMPORT_C void NextL(TPckgBuf<TInt>& aStep,TRequestStatus& aStatus);
1.152 + IMPORT_C TInt Next(TInt& aStep);
1.153 +//
1.154 + inline TInt Available() const;
1.155 +private:
1.156 + MIncrementalCollector* iCol;
1.157 + TPckgBuf<TInt> iAvail;
1.158 + };
1.159 +
1.160 +/**
1.161 + * @publishedAll
1.162 + * @released
1.163 + * Encapsulates an embedded store.
1.164 +
1.165 +The embedded store may contain an arbitrarily complex network of streams,
1.166 +but is viewed as simply another stream by the embedding store. This means
1.167 +that the embedded store can dealt with as a single stream for purposes of
1.168 +copying or deleting.
1.169 +
1.170 +Once streams within the embedded store have been committed and closed, they
1.171 +cannot subsequently be changed, i.e. streams cannot be replaced, deleted,
1.172 +extended or changed in any way.
1.173 +
1.174 +@see CPersistentStore
1.175 +*/
1.176 +class CEmbeddedStore : public CPersistentStore
1.177 + {
1.178 +public:
1.179 + IMPORT_C static CEmbeddedStore* FromL(RReadStream& aHost);
1.180 + IMPORT_C static CEmbeddedStore* FromLC(RReadStream& aHost);
1.181 + IMPORT_C static CEmbeddedStore* NewL(RWriteStream& aHost);
1.182 + IMPORT_C static CEmbeddedStore* NewLC(RWriteStream& aHost);
1.183 +//
1.184 + inline static TStreamPos Position(TStreamId anId);
1.185 +//
1.186 + IMPORT_C void Detach();
1.187 + inline void Reattach(MStreamBuf* aHost);
1.188 + inline MStreamBuf* Host() const;
1.189 + inline TStreamPos Start() const;
1.190 +//
1.191 + IMPORT_C CEmbeddedStore(MStreamBuf* aHost);
1.192 + IMPORT_C void MarshalL(RReadStream& aStream);
1.193 + IMPORT_C void ConstructL(RWriteStream& aStream);
1.194 + IMPORT_C ~CEmbeddedStore();
1.195 +protected:
1.196 + IMPORT_C MStreamBuf* DoReadL(TStreamId anId) const;
1.197 + IMPORT_C MStreamBuf* DoCreateL(TStreamId& anId);
1.198 +private:
1.199 + IMPORT_C void DoSetRootL(TStreamId anId);
1.200 + IMPORT_C void DoCommitL();
1.201 +//
1.202 + static CEmbeddedStore* DoNewLC(MStreamBuf* aHost);
1.203 +private:
1.204 + __MUTABLE TStreamExchange iHost;
1.205 + TStreamPos iStart;
1.206 + };
1.207 +
1.208 +/**
1.209 + * @publishedAll
1.210 + * @released
1.211 + * Dictionary store interface.
1.212 +
1.213 +This is an abstract class which provides the necessary interface for using
1.214 +concrete dictionary stores.
1.215 +
1.216 +A dictionary store is a store where a stream is accessed by UID (TUid), rather
1.217 +than directly by stream id (TStreamId).
1.218 +
1.219 +This type of store contains streams in the usual way but, in addition, the
1.220 +root stream is a stream dictionary. The stream dictionary provides a list
1.221 +of two-way associations between unique identifiers and stream ids.
1.222 +
1.223 +Note that a dictionary store object does not derive from CStreamStore, but
1.224 +owns a persistent store and a stream dictionary as part of its implementation.
1.225 +
1.226 +@see CStreamDictionary
1.227 +@see CPersistentStore
1.228 +@see CDictionaryFileStore
1.229 +@see TUid
1.230 +@see TStreamId
1.231 +*/
1.232 +class CDictionaryStore : public CBase
1.233 + {
1.234 +public:
1.235 + IMPORT_C TBool IsNullL() const;
1.236 + IMPORT_C TBool IsPresentL(TUid aUid) const;
1.237 + IMPORT_C void Remove(TUid aUid);
1.238 + IMPORT_C void RemoveL(TUid aUid);
1.239 +//
1.240 + IMPORT_C TInt Commit();
1.241 + IMPORT_C void CommitL();
1.242 + IMPORT_C void Revert();
1.243 + IMPORT_C void RevertL();
1.244 +//
1.245 + IMPORT_C ~CDictionaryStore();
1.246 +protected:
1.247 + IMPORT_C void ConstructL();
1.248 +private:
1.249 + CStreamDictionary* DictionaryL() const;
1.250 + MStreamBuf* GetSourceL(TUid aUid) const;
1.251 + MStreamBuf* GetSinkL(TUid aUid);
1.252 +protected:
1.253 + CPersistentStore* iStore;
1.254 +private:
1.255 + __MUTABLE CStreamDictionary* iDictionary;
1.256 + TBool iDictionaryHasChanged;
1.257 +private:
1.258 + friend class RDictionaryReadStream;
1.259 + friend class RDictionaryWriteStream;
1.260 + friend class HDictionaryStoreBuf;
1.261 + };
1.262 +//
1.263 +const TInt KDictionaryCommitThreshold = 1024;
1.264 +
1.265 +/**
1.266 + * @publishedAll
1.267 + * @released
1.268 + * Supports the opening and manipulation of a stream in a dictionary store.
1.269 +
1.270 +Construct an object of this type to open an existing stream in a dictionary
1.271 +store for reading.
1.272 +
1.273 +@see CDictionaryStore
1.274 +*/
1.275 +class RDictionaryReadStream : public RReadStream
1.276 +{
1.277 +public:
1.278 + IMPORT_C void OpenL(const CDictionaryStore& aDictStore,TUid aUid);
1.279 + IMPORT_C void OpenLC(const CDictionaryStore& aDictStore,TUid aUid);
1.280 + };
1.281 +
1.282 +/**
1.283 + * @publishedAll
1.284 + * @released
1.285 + * Supports the creation or replacement of a stream a dictionary store.
1.286 +
1.287 +@see CDictionaryStore
1.288 +*/
1.289 +class RDictionaryWriteStream : public RWriteStream
1.290 + {
1.291 +public:
1.292 + /** Constructs an uninitialised object. It is necessary because there are
1.293 + also non-default constructors in this class. */
1.294 + RDictionaryWriteStream() {}
1.295 + inline RDictionaryWriteStream(const MExternalizer<TStreamRef>& anExter);
1.296 + IMPORT_C void AssignL(CDictionaryStore& aDictStore,TUid aUid);
1.297 + IMPORT_C void AssignLC(CDictionaryStore& aDictStore,TUid aUid);
1.298 + };
1.299 +
1.300 +/**
1.301 + * @publishedAll
1.302 + * @released
1.303 + * Persistent settings to use for a RStorePagePool.
1.304 +
1.305 +@see RStorePagePool
1.306 +*/
1.307 +class TStorePagePoolToken
1.308 + {
1.309 +public:
1.310 + /** Provides a TStorePagePoolToken initialisation flag. */
1.311 + enum TEmpty
1.312 + /** Initialise for an empty page pool flag. */
1.313 + {EEmpty};
1.314 +public:
1.315 + /** Default constructor. */
1.316 + TStorePagePoolToken() {}
1.317 +
1.318 + /** Constructor that intialises the TStorePagePoolToken for an empty page pool.
1.319 +
1.320 + @param Intialises for an empty page pool */
1.321 + inline TStorePagePoolToken(TEmpty);
1.322 + inline void Touch();
1.323 +//
1.324 + inline TBool HasAvailable() const;
1.325 + inline TBool IsEmpty() const;
1.326 +//
1.327 + IMPORT_C void ExternalizeL(RWriteStream& aStream) const;
1.328 + IMPORT_C void InternalizeL(RReadStream& aStream);
1.329 +private:
1.330 + inline TStorePagePoolToken(TStreamId aHead,TPageRef anAvail);
1.331 +private:
1.332 + TStreamId iHead;
1.333 + TPageRef iAvail;
1.334 +private:
1.335 + friend class RStorePagePool;
1.336 + };
1.337 +#if defined(__NO_CLASS_CONSTS__)
1.338 +#define KEmptyStorePagePoolToken TStorePagePoolToken(TStorePagePoolToken::EEmpty)
1.339 +#else
1.340 +/** Defines a TStorePagePoolToken object initialised for an empty page pool. */
1.341 +const TStorePagePoolToken KEmptyStorePagePoolToken=TStorePagePoolToken::EEmpty;
1.342 +#endif
1.343 +
1.344 +/**
1.345 + * @publishedAll
1.346 + * @released
1.347 + * Uses a store to implement the page pool interface MPagePool.
1.348 +
1.349 +Pages can be reclaimable (tracked by the page pool, so that they can be freed
1.350 +when required) or not (in which case they must be deleted explicitly): this
1.351 +is indicated by a flag of type TPageReclamation. Non-reclaimable pages each
1.352 +have their own stream in the store; reclaimable pages are bundled 15 to a
1.353 +stream. To track the reclaimable pages, the page pool has a separate token,
1.354 +type TStorePagePoolToken, that must be saved by the user of the pool.
1.355 +
1.356 +The store used must support CStreamStore::ExtendL(), CStreamStore::DeleteL()
1.357 +and allow streams to be re-written. CPermanentFileStore meets these conditions.
1.358 +
1.359 +A store page pool uses a cache to store pages in-memory and to cache frequently
1.360 +accessed pages. You should provide a cache object (CPageCache) to the pool
1.361 +for this purpose.
1.362 +
1.363 +@see CPageCache
1.364 +@see CPermanentFileStore
1.365 +@see CStreamStore
1.366 +@see TPageReclamation
1.367 +*/
1.368 +class RStorePagePool : public TCachePagePool
1.369 + {
1.370 + friend class StorePagePool;
1.371 +public:
1.372 + IMPORT_C RStorePagePool();
1.373 + IMPORT_C RStorePagePool(CPageCache& aCache);
1.374 + IMPORT_C RStorePagePool(CStreamStore& aStore);
1.375 + IMPORT_C RStorePagePool(CStreamStore& aStore,const TStorePagePoolToken& aToken);
1.376 + IMPORT_C void Create(CStreamStore& aStore);
1.377 + IMPORT_C void Open(CStreamStore& aStore,const TStorePagePoolToken& aToken);
1.378 + IMPORT_C TStorePagePoolToken Token() const;
1.379 + IMPORT_C void Close();
1.380 + inline void Release();
1.381 +//
1.382 + inline TBool IsDirty() const;
1.383 + inline void MarkCurrent();
1.384 + inline void MarkDirty();
1.385 +//
1.386 + inline TBool HasAvailable() const;
1.387 + inline void Discard();
1.388 +//
1.389 + inline TBool IsEmpty() const;
1.390 + IMPORT_C TBool ReclaimL();
1.391 + IMPORT_C void ReclaimAllL();
1.392 +protected:
1.393 + IMPORT_C TPageRef ExtendL(const TAny* aPage,TPageReclamation aReclamation);
1.394 + IMPORT_C void WriteL(TPageRef aRef,const TAny* aPage,TPageChange aChange);
1.395 + IMPORT_C void ReadL(TPageRef aRef,TAny* aPage);
1.396 + IMPORT_C void DoDeleteL(TPageRef aRef);
1.397 +private:
1.398 + inline void CacheDeleteL(TPageRef aRef);
1.399 +private:
1.400 + CStreamStore* iStore;
1.401 + TStreamId iHead;
1.402 + TPageRef iAvail;
1.403 + TBool iDirty;
1.404 + };
1.405 +
1.406 +/**
1.407 + * @publishedAll
1.408 + * @released
1.409 + * Interface for incrementally reclaiming or compacting space in a stream store.
1.410 +The interface allows these actions to be performed in small steps, so that
1.411 +applications can remain responsive while doing these potentially long-running
1.412 +tasks.
1.413 +
1.414 +An instance of a class derived from this interface is returned by
1.415 +StreamStore::DoReclaimL() and DoCompactL(). Each step is carried out in
1.416 +response to a call of DoNextL() and the object is released on completion of
1.417 +the last step.
1.418 +
1.419 +Notes:
1.420 +
1.421 +One-step reclaim using CStreamStore::ReclaimL() is actually implemented in
1.422 +terms of the incremental collector.
1.423 +
1.424 +A CStreamStore implementation will only need to implement a collector class
1.425 +if it supports reclamation or compaction.
1.426 +*/
1.427 +class MIncrementalCollector
1.428 + {
1.429 +public:
1.430 + inline void Close();
1.431 + inline void Release();
1.432 +//
1.433 + inline void ResetL(TInt& aCount);
1.434 + inline void NextL(TInt& aStep,TInt& aTotal);
1.435 + inline void NextL(TPckgBuf<TInt>& aStep,TRequestStatus& aStatus,TPckgBuf<TInt>& aTotal);
1.436 +protected:
1.437 + /** Protected constructor. Protecting the constructor ensures that this
1.438 + abstract class cannot be instantiated.
1.439 +
1.440 + MIncrementalCollector(const MIncrementalCollector&);
1.441 +
1.442 + MIncrementalCollector& operator=(const MIncrementalCollector&);
1.443 +
1.444 + Private copy constructor and copy assignment to prevent */
1.445 + MIncrementalCollector() {}
1.446 +private:
1.447 + /** Protected constructor. Protecting the constructor ensures that this
1.448 + abstract class cannot be instantiated.
1.449 +
1.450 + MIncrementalCollector(const MIncrementalCollector&);
1.451 +
1.452 + MIncrementalCollector& operator=(const MIncrementalCollector&);
1.453 +
1.454 + Private copy constructor and copy assignment to prevent */
1.455 + MIncrementalCollector(const MIncrementalCollector&);
1.456 + MIncrementalCollector& operator=(const MIncrementalCollector&);
1.457 +//
1.458 + virtual IMPORT_C void DoRelease();
1.459 +
1.460 + /** Implementation of the public ResetL() function. This signals that the
1.461 + client wants to start or retsart the operation from the beginning. A new
1.462 + progress count should be returned in aCount.
1.463 +
1.464 + @param aCount On return, contains a progress count for the
1.465 + reclamation/compaction process. */
1.466 + virtual void DoResetL(TInt& aCount)=0;
1.467 +
1.468 + /** Implementation of the public synchronous NextL() function. The next
1.469 + step in the reclamation should be done, reporting progress in aStep and
1.470 + aTotal.
1.471 +
1.472 + @param aStep The progress value from either the last NextL() increment of
1.473 + from ResetL() if the reclamation/compaction was restarted. On return,
1.474 + should contain the new progress value, which can be used in subsequent
1.475 + calls to NextL(). This must be equal to, or less than, the previous
1.476 + value — a zero value must be used to indicate that the operation is
1.477 + complete.
1.478 + @param aTotal On return, should contain the total amount of free space in
1.479 + the store. */
1.480 + virtual void DoNextL(TInt& aStep,TInt& aTotal)=0;
1.481 + virtual IMPORT_C void DoNextL(TPckgBuf<TInt>& aStep,TRequestStatus& aStatus,TPckgBuf<TInt>& aTotal);
1.482 + };
1.483 +
1.484 +#include <s32stor.inl>
1.485 +#endif