1 s32stor.h |
1 // Copyright (c) 1998-2009 Nokia Corporation and/or its subsidiary(-ies). |
|
2 // All rights reserved. |
|
3 // This component and the accompanying materials are made available |
|
4 // 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 |
|
5 // which accompanies this distribution, and is available |
|
6 // at the URL "http://www.symbianfoundation.org/legal/licencesv10.html". |
|
7 // |
|
8 // Initial Contributors: |
|
9 // Nokia Corporation - initial contribution. |
|
10 // |
|
11 // Contributors: |
|
12 // |
|
13 // Description: |
|
14 // |
|
15 |
|
16 #if !defined(__S32STOR_H__) |
|
17 #define __S32STOR_H__ |
|
18 #if !defined(__S32STD_H__) |
|
19 #include <s32std.h> |
|
20 #endif |
|
21 #if !defined(__S32SHARE_H__) |
|
22 #include <s32share.h> |
|
23 #endif |
|
24 #if !defined(__S32PAGE_H__) |
|
25 #include <s32page.h> |
|
26 #endif |
|
27 |
|
28 class MIncrementalCollector; |
|
29 /** |
|
30 * @publishedAll |
|
31 * @released |
|
32 * Provides the core abstract framework for stores allowing streams to be |
|
33 created and manipulated. |
|
34 */ |
|
35 class CStreamStore : public CBase |
|
36 { |
|
37 public: |
|
38 inline TStreamId ExtendL(); |
|
39 IMPORT_C void Delete(TStreamId anId); |
|
40 IMPORT_C void DeleteL(TStreamId anId); |
|
41 // |
|
42 IMPORT_C TInt Commit(); |
|
43 inline void CommitL(); |
|
44 IMPORT_C void Revert(); |
|
45 inline void RevertL(); |
|
46 // |
|
47 IMPORT_C TInt ReclaimL(); |
|
48 IMPORT_C TInt CompactL(); |
|
49 private: |
|
50 virtual IMPORT_C TStreamId DoExtendL(); |
|
51 virtual IMPORT_C void DoDeleteL(TStreamId anId); |
|
52 |
|
53 /** Opens the requested stream for reading. The function should return a |
|
54 stream buffer positioned at the beginning of this stream. |
|
55 |
|
56 This function is called by the OpenL() and OpenLC() member functions of |
|
57 RStoreReadStream. |
|
58 |
|
59 @param anId The stream to be read. |
|
60 @return A stream buffer positioned at the beginning of the stream to be read. |
|
61 @see RStoreReadStream::OpenL() |
|
62 @see RStoreReadStream::OpenLC() */ |
|
63 virtual MStreamBuf* DoReadL(TStreamId anId) const=0; |
|
64 |
|
65 /** Creates a new stream in the store. The function gets the allocated |
|
66 stream id in the anId parameter. A stream buffer for the stream should be |
|
67 returned, ready to write into the new stream. This provides the |
|
68 implementation for the RStoreWriteStream::CreateL() functions. |
|
69 |
|
70 @param anId On return, contains the allocated stream id. |
|
71 @return The stream buffer to be written to. */ |
|
72 virtual MStreamBuf* DoCreateL(TStreamId& anId)=0; |
|
73 virtual IMPORT_C MStreamBuf* DoWriteL(TStreamId anId); |
|
74 virtual IMPORT_C MStreamBuf* DoReplaceL(TStreamId anId); |
|
75 virtual IMPORT_C void DoCommitL(); |
|
76 virtual IMPORT_C void DoRevertL(); |
|
77 virtual IMPORT_C MIncrementalCollector* DoReclaimL(); |
|
78 virtual IMPORT_C MIncrementalCollector* DoCompactL(); |
|
79 private: |
|
80 friend class RStoreReadStream; |
|
81 friend class RStoreWriteStream; |
|
82 friend class RStoreReclaim; |
|
83 }; |
|
84 |
|
85 /** |
|
86 * @publishedAll |
|
87 * @released |
|
88 * Persistent store abstract base class. It provides the behaviour for setting |
|
89 and retrieving the root stream id. |
|
90 |
|
91 Before closing a persistent store, the root stream id must be set. After opening |
|
92 a persistent store, the first thing done is to look up the root stream id. |
|
93 The root stream can then be opened and data read from the store. |
|
94 |
|
95 @see CFileStore |
|
96 */ |
|
97 class CPersistentStore : public CStreamStore |
|
98 { |
|
99 public: |
|
100 inline TStreamId Root() const; |
|
101 inline void SetRootL(TStreamId anId); |
|
102 protected: |
|
103 inline CPersistentStore(); |
|
104 private: |
|
105 virtual IMPORT_C void DoSetRootL(TStreamId anId); |
|
106 protected: |
|
107 TStreamId iRoot; |
|
108 }; |
|
109 |
|
110 /** |
|
111 * @publishedAll |
|
112 * @released |
|
113 * Performs space reclamation or compaction on a permanent file store in |
|
114 incremental steps. |
|
115 |
|
116 Reclaiming unused space makes it available for re-use by the store. Compacting |
|
117 makes unused space available for re-use by the relevant system pool — for |
|
118 example, the filing system in the case of file-based stores. |
|
119 |
|
120 Once compaction is complete, the store must be committed. |
|
121 |
|
122 Notes: |
|
123 |
|
124 Space reclamation and compaction are only supported by the file store |
|
125 CPermanentFileStore and are not supported by embedded or direct file stores. |
|
126 |
|
127 Use active objects when implementing space reclamation or compaction |
|
128 asynchronously. |
|
129 |
|
130 This class performs incremental compaction/reclamation. These operations can |
|
131 be performed in a possibly long running single step using CStreamStore |
|
132 functions. |
|
133 */ |
|
134 class RStoreReclaim |
|
135 { |
|
136 public: |
|
137 inline RStoreReclaim(); |
|
138 IMPORT_C void OpenL(CStreamStore& aStore,TInt& aCount); |
|
139 IMPORT_C void OpenLC(CStreamStore& aStore,TInt& aCount); |
|
140 IMPORT_C void CompactL(CStreamStore& aStore,TInt& aCount); |
|
141 IMPORT_C void CompactLC(CStreamStore& aStore,TInt& aCount); |
|
142 inline void Close(); |
|
143 IMPORT_C void Release(); |
|
144 // |
|
145 IMPORT_C void ResetL(TInt& aCount); |
|
146 IMPORT_C void NextL(TInt& aStep); |
|
147 IMPORT_C void Next(TPckgBuf<TInt>& aStep,TRequestStatus& aStatus); |
|
148 IMPORT_C void NextL(TPckgBuf<TInt>& aStep,TRequestStatus& aStatus); |
|
149 IMPORT_C TInt Next(TInt& aStep); |
|
150 // |
|
151 inline TInt Available() const; |
|
152 private: |
|
153 MIncrementalCollector* iCol; |
|
154 TPckgBuf<TInt> iAvail; |
|
155 }; |
|
156 |
|
157 /** |
|
158 * @publishedAll |
|
159 * @released |
|
160 * Encapsulates an embedded store. |
|
161 |
|
162 The embedded store may contain an arbitrarily complex network of streams, |
|
163 but is viewed as simply another stream by the embedding store. This means |
|
164 that the embedded store can dealt with as a single stream for purposes of |
|
165 copying or deleting. |
|
166 |
|
167 Once streams within the embedded store have been committed and closed, they |
|
168 cannot subsequently be changed, i.e. streams cannot be replaced, deleted, |
|
169 extended or changed in any way. |
|
170 |
|
171 @see CPersistentStore |
|
172 */ |
|
173 class CEmbeddedStore : public CPersistentStore |
|
174 { |
|
175 public: |
|
176 IMPORT_C static CEmbeddedStore* FromL(RReadStream& aHost); |
|
177 IMPORT_C static CEmbeddedStore* FromLC(RReadStream& aHost); |
|
178 IMPORT_C static CEmbeddedStore* NewL(RWriteStream& aHost); |
|
179 IMPORT_C static CEmbeddedStore* NewLC(RWriteStream& aHost); |
|
180 // |
|
181 inline static TStreamPos Position(TStreamId anId); |
|
182 // |
|
183 IMPORT_C void Detach(); |
|
184 inline void Reattach(MStreamBuf* aHost); |
|
185 inline MStreamBuf* Host() const; |
|
186 inline TStreamPos Start() const; |
|
187 // |
|
188 IMPORT_C CEmbeddedStore(MStreamBuf* aHost); |
|
189 IMPORT_C void MarshalL(RReadStream& aStream); |
|
190 IMPORT_C void ConstructL(RWriteStream& aStream); |
|
191 IMPORT_C ~CEmbeddedStore(); |
|
192 protected: |
|
193 IMPORT_C MStreamBuf* DoReadL(TStreamId anId) const; |
|
194 IMPORT_C MStreamBuf* DoCreateL(TStreamId& anId); |
|
195 private: |
|
196 IMPORT_C void DoSetRootL(TStreamId anId); |
|
197 IMPORT_C void DoCommitL(); |
|
198 // |
|
199 static CEmbeddedStore* DoNewLC(MStreamBuf* aHost); |
|
200 private: |
|
201 __MUTABLE TStreamExchange iHost; |
|
202 TStreamPos iStart; |
|
203 }; |
|
204 |
|
205 /** |
|
206 * @publishedAll |
|
207 * @released |
|
208 * Dictionary store interface. |
|
209 |
|
210 This is an abstract class which provides the necessary interface for using |
|
211 concrete dictionary stores. |
|
212 |
|
213 A dictionary store is a store where a stream is accessed by UID (TUid), rather |
|
214 than directly by stream id (TStreamId). |
|
215 |
|
216 This type of store contains streams in the usual way but, in addition, the |
|
217 root stream is a stream dictionary. The stream dictionary provides a list |
|
218 of two-way associations between unique identifiers and stream ids. |
|
219 |
|
220 Note that a dictionary store object does not derive from CStreamStore, but |
|
221 owns a persistent store and a stream dictionary as part of its implementation. |
|
222 |
|
223 @see CStreamDictionary |
|
224 @see CPersistentStore |
|
225 @see CDictionaryFileStore |
|
226 @see TUid |
|
227 @see TStreamId |
|
228 */ |
|
229 class CDictionaryStore : public CBase |
|
230 { |
|
231 public: |
|
232 IMPORT_C TBool IsNullL() const; |
|
233 IMPORT_C TBool IsPresentL(TUid aUid) const; |
|
234 IMPORT_C void Remove(TUid aUid); |
|
235 IMPORT_C void RemoveL(TUid aUid); |
|
236 // |
|
237 IMPORT_C TInt Commit(); |
|
238 IMPORT_C void CommitL(); |
|
239 IMPORT_C void Revert(); |
|
240 IMPORT_C void RevertL(); |
|
241 // |
|
242 IMPORT_C ~CDictionaryStore(); |
|
243 protected: |
|
244 IMPORT_C void ConstructL(); |
|
245 private: |
|
246 CStreamDictionary* DictionaryL() const; |
|
247 MStreamBuf* GetSourceL(TUid aUid) const; |
|
248 MStreamBuf* GetSinkL(TUid aUid); |
|
249 protected: |
|
250 CPersistentStore* iStore; |
|
251 private: |
|
252 __MUTABLE CStreamDictionary* iDictionary; |
|
253 TBool iDictionaryHasChanged; |
|
254 private: |
|
255 friend class RDictionaryReadStream; |
|
256 friend class RDictionaryWriteStream; |
|
257 friend class HDictionaryStoreBuf; |
|
258 }; |
|
259 // |
|
260 const TInt KDictionaryCommitThreshold = 1024; |
|
261 |
|
262 /** |
|
263 * @publishedAll |
|
264 * @released |
|
265 * Supports the opening and manipulation of a stream in a dictionary store. |
|
266 |
|
267 Construct an object of this type to open an existing stream in a dictionary |
|
268 store for reading. |
|
269 |
|
270 @see CDictionaryStore |
|
271 */ |
|
272 class RDictionaryReadStream : public RReadStream |
|
273 { |
|
274 public: |
|
275 IMPORT_C void OpenL(const CDictionaryStore& aDictStore,TUid aUid); |
|
276 IMPORT_C void OpenLC(const CDictionaryStore& aDictStore,TUid aUid); |
|
277 }; |
|
278 |
|
279 /** |
|
280 * @publishedAll |
|
281 * @released |
|
282 * Supports the creation or replacement of a stream a dictionary store. |
|
283 |
|
284 @see CDictionaryStore |
|
285 */ |
|
286 class RDictionaryWriteStream : public RWriteStream |
|
287 { |
|
288 public: |
|
289 /** Constructs an uninitialised object. It is necessary because there are |
|
290 also non-default constructors in this class. */ |
|
291 RDictionaryWriteStream() {} |
|
292 inline RDictionaryWriteStream(const MExternalizer<TStreamRef>& anExter); |
|
293 IMPORT_C void AssignL(CDictionaryStore& aDictStore,TUid aUid); |
|
294 IMPORT_C void AssignLC(CDictionaryStore& aDictStore,TUid aUid); |
|
295 }; |
|
296 |
|
297 /** |
|
298 * @publishedAll |
|
299 * @released |
|
300 * Persistent settings to use for a RStorePagePool. |
|
301 |
|
302 @see RStorePagePool |
|
303 */ |
|
304 class TStorePagePoolToken |
|
305 { |
|
306 public: |
|
307 /** Provides a TStorePagePoolToken initialisation flag. */ |
|
308 enum TEmpty |
|
309 /** Initialise for an empty page pool flag. */ |
|
310 {EEmpty}; |
|
311 public: |
|
312 /** Default constructor. */ |
|
313 TStorePagePoolToken() {} |
|
314 |
|
315 /** Constructor that intialises the TStorePagePoolToken for an empty page pool. |
|
316 |
|
317 @param Intialises for an empty page pool */ |
|
318 inline TStorePagePoolToken(TEmpty); |
|
319 inline void Touch(); |
|
320 // |
|
321 inline TBool HasAvailable() const; |
|
322 inline TBool IsEmpty() const; |
|
323 // |
|
324 IMPORT_C void ExternalizeL(RWriteStream& aStream) const; |
|
325 IMPORT_C void InternalizeL(RReadStream& aStream); |
|
326 private: |
|
327 inline TStorePagePoolToken(TStreamId aHead,TPageRef anAvail); |
|
328 private: |
|
329 TStreamId iHead; |
|
330 TPageRef iAvail; |
|
331 private: |
|
332 friend class RStorePagePool; |
|
333 }; |
|
334 #if defined(__NO_CLASS_CONSTS__) |
|
335 #define KEmptyStorePagePoolToken TStorePagePoolToken(TStorePagePoolToken::EEmpty) |
|
336 #else |
|
337 /** Defines a TStorePagePoolToken object initialised for an empty page pool. */ |
|
338 const TStorePagePoolToken KEmptyStorePagePoolToken=TStorePagePoolToken::EEmpty; |
|
339 #endif |
|
340 |
|
341 /** |
|
342 * @publishedAll |
|
343 * @released |
|
344 * Uses a store to implement the page pool interface MPagePool. |
|
345 |
|
346 Pages can be reclaimable (tracked by the page pool, so that they can be freed |
|
347 when required) or not (in which case they must be deleted explicitly): this |
|
348 is indicated by a flag of type TPageReclamation. Non-reclaimable pages each |
|
349 have their own stream in the store; reclaimable pages are bundled 15 to a |
|
350 stream. To track the reclaimable pages, the page pool has a separate token, |
|
351 type TStorePagePoolToken, that must be saved by the user of the pool. |
|
352 |
|
353 The store used must support CStreamStore::ExtendL(), CStreamStore::DeleteL() |
|
354 and allow streams to be re-written. CPermanentFileStore meets these conditions. |
|
355 |
|
356 A store page pool uses a cache to store pages in-memory and to cache frequently |
|
357 accessed pages. You should provide a cache object (CPageCache) to the pool |
|
358 for this purpose. |
|
359 |
|
360 @see CPageCache |
|
361 @see CPermanentFileStore |
|
362 @see CStreamStore |
|
363 @see TPageReclamation |
|
364 */ |
|
365 class RStorePagePool : public TCachePagePool |
|
366 { |
|
367 friend class StorePagePool; |
|
368 public: |
|
369 IMPORT_C RStorePagePool(); |
|
370 IMPORT_C RStorePagePool(CPageCache& aCache); |
|
371 IMPORT_C RStorePagePool(CStreamStore& aStore); |
|
372 IMPORT_C RStorePagePool(CStreamStore& aStore,const TStorePagePoolToken& aToken); |
|
373 IMPORT_C void Create(CStreamStore& aStore); |
|
374 IMPORT_C void Open(CStreamStore& aStore,const TStorePagePoolToken& aToken); |
|
375 IMPORT_C TStorePagePoolToken Token() const; |
|
376 IMPORT_C void Close(); |
|
377 inline void Release(); |
|
378 // |
|
379 inline TBool IsDirty() const; |
|
380 inline void MarkCurrent(); |
|
381 inline void MarkDirty(); |
|
382 // |
|
383 inline TBool HasAvailable() const; |
|
384 inline void Discard(); |
|
385 // |
|
386 inline TBool IsEmpty() const; |
|
387 IMPORT_C TBool ReclaimL(); |
|
388 IMPORT_C void ReclaimAllL(); |
|
389 protected: |
|
390 IMPORT_C TPageRef ExtendL(const TAny* aPage,TPageReclamation aReclamation); |
|
391 IMPORT_C void WriteL(TPageRef aRef,const TAny* aPage,TPageChange aChange); |
|
392 IMPORT_C void ReadL(TPageRef aRef,TAny* aPage); |
|
393 IMPORT_C void DoDeleteL(TPageRef aRef); |
|
394 private: |
|
395 inline void CacheDeleteL(TPageRef aRef); |
|
396 private: |
|
397 CStreamStore* iStore; |
|
398 TStreamId iHead; |
|
399 TPageRef iAvail; |
|
400 TBool iDirty; |
|
401 }; |
|
402 |
|
403 /** |
|
404 * @publishedAll |
|
405 * @released |
|
406 * Interface for incrementally reclaiming or compacting space in a stream store. |
|
407 The interface allows these actions to be performed in small steps, so that |
|
408 applications can remain responsive while doing these potentially long-running |
|
409 tasks. |
|
410 |
|
411 An instance of a class derived from this interface is returned by |
|
412 StreamStore::DoReclaimL() and DoCompactL(). Each step is carried out in |
|
413 response to a call of DoNextL() and the object is released on completion of |
|
414 the last step. |
|
415 |
|
416 Notes: |
|
417 |
|
418 One-step reclaim using CStreamStore::ReclaimL() is actually implemented in |
|
419 terms of the incremental collector. |
|
420 |
|
421 A CStreamStore implementation will only need to implement a collector class |
|
422 if it supports reclamation or compaction. |
|
423 */ |
|
424 class MIncrementalCollector |
|
425 { |
|
426 public: |
|
427 inline void Close(); |
|
428 inline void Release(); |
|
429 // |
|
430 inline void ResetL(TInt& aCount); |
|
431 inline void NextL(TInt& aStep,TInt& aTotal); |
|
432 inline void NextL(TPckgBuf<TInt>& aStep,TRequestStatus& aStatus,TPckgBuf<TInt>& aTotal); |
|
433 protected: |
|
434 /** Protected constructor. Protecting the constructor ensures that this |
|
435 abstract class cannot be instantiated. |
|
436 |
|
437 MIncrementalCollector(const MIncrementalCollector&); |
|
438 |
|
439 MIncrementalCollector& operator=(const MIncrementalCollector&); |
|
440 |
|
441 Private copy constructor and copy assignment to prevent */ |
|
442 MIncrementalCollector() {} |
|
443 private: |
|
444 /** Protected constructor. Protecting the constructor ensures that this |
|
445 abstract class cannot be instantiated. |
|
446 |
|
447 MIncrementalCollector(const MIncrementalCollector&); |
|
448 |
|
449 MIncrementalCollector& operator=(const MIncrementalCollector&); |
|
450 |
|
451 Private copy constructor and copy assignment to prevent */ |
|
452 MIncrementalCollector(const MIncrementalCollector&); |
|
453 MIncrementalCollector& operator=(const MIncrementalCollector&); |
|
454 // |
|
455 virtual IMPORT_C void DoRelease(); |
|
456 |
|
457 /** Implementation of the public ResetL() function. This signals that the |
|
458 client wants to start or retsart the operation from the beginning. A new |
|
459 progress count should be returned in aCount. |
|
460 |
|
461 @param aCount On return, contains a progress count for the |
|
462 reclamation/compaction process. */ |
|
463 virtual void DoResetL(TInt& aCount)=0; |
|
464 |
|
465 /** Implementation of the public synchronous NextL() function. The next |
|
466 step in the reclamation should be done, reporting progress in aStep and |
|
467 aTotal. |
|
468 |
|
469 @param aStep The progress value from either the last NextL() increment of |
|
470 from ResetL() if the reclamation/compaction was restarted. On return, |
|
471 should contain the new progress value, which can be used in subsequent |
|
472 calls to NextL(). This must be equal to, or less than, the previous |
|
473 value — a zero value must be used to indicate that the operation is |
|
474 complete. |
|
475 @param aTotal On return, should contain the total amount of free space in |
|
476 the store. */ |
|
477 virtual void DoNextL(TInt& aStep,TInt& aTotal)=0; |
|
478 virtual IMPORT_C void DoNextL(TPckgBuf<TInt>& aStep,TRequestStatus& aStatus,TPckgBuf<TInt>& aTotal); |
|
479 }; |
|
480 |
|
481 #include <s32stor.inl> |
|
482 #endif |