3 (Made by Mark Cawston, 13 March 2002)
5 Fixed FER-56EJNS (Inconsistent dealing with zero length Base64 data.)
7 UMEM\UM_BUF.CPP TMemBuf::Set(TUint8* aPtr,TUint8* anEnd,TInt aMode) changed to
8 treat null data as seekable zero-length data.
10 TMEM\T_MSTRM.CPP extended to cover test case.
14 (Made by Mark Cawston, 20 November 2001)
16 Fixed BAR-4YRCST (Unnecessary stack usage,) by changing EnsurePathL() in UF_DICT.CPP.
20 (Made by Andrew Thoelke, 16 May 2001)
22 Performance optimisations for PermanentFileStore.
24 * Enhanced write-buffering in RFileBuf to maintain the write buffer when overwriting data already in the buffer.
25 * PermanentFileStore now checks for a transactional file system (new API from F32) such as LFFS, reducing
26 the number of overwrites to the file header when commiting and compacting the store.
27 * Improved the use of the TOC caches to maintain them whenever possible, rather than invalidating them.
28 * Improved the process of writing a new TOC to involve minimal file writes.
29 * Added a new compaction algorithm which is still very effective at recovering free space, but moves significantly
30 less data when the file is more than half used. On large stores (1000's of streams, 100's of K) it can be over 8x
31 faster when there is approx. 10% free space (this is ignoring the benefits of the LFFS optimisation)
33 When combined these changes reduce the number of file write requests significantly, which is the predominant
34 performance factor on slow media (such as flash memory).
36 This also fixes GT 6.1 defect THE-4UVH4N, introduced by the addition of TOC-delta's to CPermanentFileStore.
41 (Made by Andrew Thoelke, 2 March 2001)
43 Added TOC (table of contents) 'delta's to Permanent File Store. When
44 committed such a store will not always re-write the entire TOC, instead
45 it will save only the updates since the last full TOC. This can reduce
46 the average overhead of the TOC when committing the store by over 95%.
48 This change is to provide a fix for 6.0 defect EDNAPIN-4T4KZD.
50 The PFSDUMP tool has been updated to understand the new toc structure
51 and report the store contents as before.
54 Data compatibility warning:
56 The new STORE will read and update existing PFS files, but the resulting
57 files can no longer be read by previous versions of STORE.
62 (Made by Mark Cawston, 12 February 2001)
64 Fixed EDNMMIR-4QHDUH (CDictionaryFileStore abuses the filing system on a CommitL).
65 Previously fixed in 6.0 branch by providing 1k threshold for CDictionaryStore::CommitL()
70 (Made by William Roberts, 7th August 1999)
72 Fixed the construction of TStreamMark variables, e.g.
75 becomes TStreamMark mark(pos);
77 This is necessary for the new GCC compiler because it correctly spots that
79 STORE\INC\s32share.h: In method `TInt RFrame16Buf::ExtendL(class TStreamExchange &, TInt, TInt = 3)':
80 STORE\INC\s32share.h:58: `TStreamMark::TStreamMark(const class TStreamMark &)' is private
81 STORE\USTRM\Us_frame.cpp:59: within this context
86 (Made by Graham Asher, 6th August 1999)
88 Fixed a defect caused by a GCC linking problem:
89 GASR-4AGJQX Word panics on closing when Greek letters are entered.
94 (Made by Mark Dowman, 20th May 1999)
96 EPOC Release 5u baseline component
109 No testing performed.
119 Narrow builds removed.
122 Release 061 - Graham Asher - 24th January 1999
123 ==============================================
125 Combines releases 051 and 060, thus joining together the two branches of development.
127 Intended for ER5u (EPOC Release 5 Unicode).
132 (Made by AjThoelke, 8 December 1998)
134 EPOC Release 5 candidate component
139 Fully Binary compatible with 050
148 ARM narrow release size is 69696 bytes (68.1K), as reported from ROMBUILD.
153 Test code changed to verify the fix for defect 430304.
154 All test code passes on all platforms.
158 ER5 defect EDN 430304: Failure to compact a CDictionaryStore no longer masks a successful CommitL().
159 Rebuilt with MSVC++ 5.0 Service Pack 3 to ensure good WINS release builds.
160 Boiler-plated the source code using the SysDoc tool.
164 All literal descriptors now use _LIT(), saving a few hundred bytes
165 All uses of __DECLARE_NAME() have been removed (deprecated)
168 Release 060 - Graham Asher - 23rd November 1998
169 ===============================================
171 ER6 only, hence the jump in release numbers.
173 In the Unicode builds only, 16-bit descriptors are compressed on externalisation, and decompressed on internalisation, using the Standard Compression Scheme for Unicode. The compression and expansion functionality has been moved here from ETEXT, tidied up, and made public by way of exported functions of TUnicodeCompressor and TUnicodeExpander. Prospective clients so far are ETEXT and DBMS. The new header file for the compression and expansion is s32ucmp.h.
178 (Made by AjThoelke, 28 October 1998)
183 Only WINS REL, MARM REL and MARM DEB releases are binary compatible with 049
185 WINS DEB is now BC with WINS REL
186 WINS UREL is BC with WINS UDEB
187 MARM UREL is BC with MARM UDEB
191 ER5 compatibility components:
197 ARM narrow release size is 70056 bytes (68.4K), as reported from ROMBUILD.
199 WINS releases built using MSVC++ 5.0, debug databases are now incompatible with
200 earlier versions of the IDE.
204 1. Implemented phase 3 of Epoc32 Proposal SW1-87. The CleanupXxxPushL()
205 template classes and functions in s32strm.h have been removed, as
206 they are included in e32base.h. STORE header files are no longer
207 required to provide this functionality.
209 2. A new UID has been allocated for the STORE unicode DLL: 0x10003B0D
214 (Made by AjThoelke, 11 June 1998)
216 This release is primarily to provide MSVC 5.0 build compatibility
220 All binary releasables are exactly the 048 releasables as the changes
221 have no impact on the code generated. This fact was verified by
222 validation of objects rebuilt with the new header files.
224 Hence, fully BC with 048, and no test code has been run, as the binaries
225 have already been tested for 048.
229 E32 release 126, for debug/release compatibility and Security framework
233 ARM narrow release size is 70020 bytes (68.4K), as reported from ROMBUILD.
235 The build commands no longer output to the console, but direct all output
236 into a log file: \dbms\bmake\<platfrom>.<build>.log. If a build fails these
237 will contain the compiler/linker errors, If the build succeeds these will
238 contain any warnings.
242 1. SW1-66: s32btree.h and s32cont.h contained various template
243 specialisations which had not been treated for MSVC 5.0 changes.
244 TEMPLATE_SPECIALIZATION added to the affected classes.
246 2. Implemented phase 1 of Epoc32 Proposal SW1-87. The CleanupXxxPushL()
247 template classes and functions in s32strm.h are protected by an
248 include guard macro __EPOC_CLEANUP_SUPPORT__. A future release of E32
249 will place this functionality in a E32 header.
254 (Made by AjThoelke, 5 May 1998)
259 All builds are forwards and backwards compatible with STORE 047
261 All test code has been run against all compatible builds
267 E32 release 126, for debug/release compatibility and Security framework
271 ARM narrow release size is 70020 bytes (68.4K), as reported from ROMBUILD.
276 * TStreamBuf::DoReadL() and DoWriteL() members had an over aggressive
277 debug assertion which checked the state of the other buffer. The
278 assertion also happens to fail for a read-only buffer which lives above
279 address 0x80000000, e.g. in a fixed process.
281 The assertion has been changed to correctly allow for read-only or
282 write-only stream buffer.
284 * Mis-ordering of two inline functions in an internal header resulted in
285 non-inlining. This results in a slightly smaller DLL.
290 (Made by AjThoelke, 19 February 1998)
295 All WINS builds are backwards BC with STORE 046.
296 MARM REL builds are backwards BC with STORE 046.
298 MARM debug builds are NOT binary compatible with STORE 046, in order to
299 introduce compatibility with the corresponding STORE 047 release component.
300 If you are building a release/debug compatible MARM component you must use
301 at least E32 125, F32 95 and STORE 047.
303 New exports have been added to provide the RSecureStorePagePool class in
304 s32crypt.h. If you require this class you must use STORE 047 (and thus
307 All test code has been run against all compatible builds
313 E32 release 125, for debug/release compatibility and Security framework
317 ARM narrow release size is 70052 bytes (68.4K), as reported from ROMBUILD.
319 MAKMAKE is now used throughout STORE. The new BMAKE directory contains the batch
320 file (bld.bat), makefiles and mmp files to build STORE. BWINS and BMARM now just
321 contain the export definitions files.
323 STORE can still be built using the mnt verbs, or by invoking BLD in the BMAKE
324 directory. Invoking BLD without parameters gives the basic syntax used.
326 Test code is built either in each test code sub-project using bld.bat or the
327 makefile, or using mnt.cmd from the group as before to build all test code.
333 * RFrame16Buf::ReadL() could corrupt the internal CPermanentFileStore
334 state if it was called after having already indicated that there was no
335 more data to read. Fixed by reseting the read position if the read
336 terminator has been read.
338 This is extremely unlikely to affect current code, as it only occurs for
339 streams in Permenent File Stores which end exactly on a 16K boundary and
340 which have ReadL() called many times after the end of stream is reached.
341 Fix #3 below was introduced as a result.
343 * TDesBuf::Consolidate() would fail with a descriptor overflow panic if
344 it was operating as read-only and the descriptor data address was in the
345 upper half of memory, i.e. address>=0x80000000.
347 This is unlikely to affect current code, as user data (until E32 121)
348 lived int he lower half of memory. There is a workaround, if required:
349 set the stream buffer to read/write mode.
351 * Encryption filters were very eager to read data from the source stream
352 when the request could be fulfilled from the filter's output buffer.
353 In these cases they now make no read request on the source. This
354 significantly improves performance of the decryption filter when the
355 end of a stream is reached.
361 * Class RSecureStorePagePool in s32crypt.h. This relies on a bounded
362 encryption algorithm and a new framework class from E32[124]. It has the
363 same behaviour as RStorePagePool, except that all pages are encrypted
364 using the supplied key.
366 * Debug and Release builds are compatible. The inline debug assertions
367 will still operate when a DEB client is run against a REL STORE.
368 This will not affect the runtime speed or size of a REL client.
370 One upshot of this is that the CPageCache statistics are not enabled for
371 either REL or DEB builds. A custom STORE would be required were these
372 required for cache-size research.
377 (Made by AjThoelke, 2 October 1997)
381 E32 release 111, for the TEMPLATE _SPECIALIZATION macro used for VC++ 5.0 support
382 F32 release 074 (Platform 001)
385 ARM narrow release size is 68892 bytes (67.3K), as reported from ROMBUILD.
389 * SW3-1555. MSVC++ 5.0 compatibility tweaks added to relevant headers.
391 * SW3-1707. CDictionaryFileStore has a new algorithm for dealing with
392 contention for the same file across multiple threads. It can now
393 typically handle 20 equal priority threads, previously only 4. In the
394 worst case, when the file is locked open, the code will return failure
397 Test code for contention has been added to T_DICFS.CPP.
399 * Some debug code in TStreamMark::IsTracking() and TStreamMark::Track()
400 was not working for data addresses above 0x80000000. This has not
401 affected any code so far as no platform used such data addresses...
402 until now. This is not a BC issue as this is not present in release
408 (Made by AjThoelke, 4 July 1997)
410 1. Built using Platform 001 releases of E32 and F32; used E32TOOLS/074
411 ARM narrow release size is 68676 bytes (67.1K), as reported from ROMBUILD.
413 2. Fixed SW3-1579, by adjusting reclaimation state machine to return
414 more often when caclulating stream lengths.
419 (Made by AjThoelke, 28 May 1997)
421 1. Built using Platform 001 releases of E32 and F32; used E32TOOLS/067
422 ARM narrow release size is 68636 bytes (67K), as reported from ROMBUILD.
424 2. Fixed MNT VALID: needed -e32 in pediff command line.
428 (Made by AjThoelke, 16 May 1997)
430 1. Built using Platform releases of E32 and F32; used E32TOOLS/066
431 ARM narrow release size is 68636 bytes (67K), as reported from ROMBUILD.
433 2. Binary Compatibility
435 Backwards binary compatible with Platform release 042.
437 Three new exports in this release:
441 TInt TStreamMark::ReadL(TStreamExchange& aHost,TDes8& aDes,TRequestStatus& aStatus);
442 TInt TStreamMark::WriteL(TStreamExchange& aHost,const TDesC8& aDes,TRequestStatus& aStatus);
446 TBool CDictionaryStore::IsNullL() const;
448 The first two were declared as IMPORT_C in the platform release, but
449 were not exported. The third is a new function in the header file.
451 If you require any of these exports you must build against this release
452 and state your dependency on STORE 043 explicitly in your release notes.
454 Currently there are no components which do so.
456 3. Removed Name builds from the BWINS project make file.
458 4. Added map files to MARM releaseables
460 5. Fixed SW3-134. Two functions in TStreamMark declared as IMPORT_C did not
461 exist. These have been correctly implemented and exported.
463 6. Fixed SW3-182. Added a new function
465 TBool IsNullL() const;
467 to CDictionaryStore to complement CStreamDictionary::IsNull(). This returns
468 true when the dictionary store is the null mapping:
470 <any uid> -> empty stream
472 7. Adjusted logo text in PFSDUMP "EPOC/32" -> "EPOC32", copyright date, and
473 full version number "1.00(build 043)"
478 (Made by AjThoelke, 16 April 1997)
480 1). Built using E32TOOLS/063, E32/098 and F32/068. ARM narrow release size
481 is 68532 bytes (67K), as reported from ROMBUILD.
483 Binary compatible with 041.
484 File compatible with 041.
486 2. MARM releasables conform to the new Uid scheme:
487 Dynamic Library : Shared Library : ESTOR
489 So MARM requires E32 098 for running anything other than narrow release
492 3. The suffix "Uid" has been added to the KDirectFileStoreLayout and
493 KPermanentFileStoreLayout TUid constants. Binary, but not source,
496 const TInt KDirectFileStoreLayoutUidValue has also been added, similarly
497 for KPermanentFileStoreLayoutUidValue.
499 4. Added member TBool CStreamDictionary::IsNull() const
500 This returns whether a dictionary is the null mapping:
502 <any uid> -> KNullStreamId
504 i.e. this is false if it contains a non-null mapping for at least one
507 5. The system dictionary file store now has the politically correct name:
513 (Made by AjThoelke, 9 April 1997)
515 1). Built using E32TOOLS/059, E32/096 and F32/065. ARM narrow release size
516 is 68492 bytes (67K), as reported from ROMBUILD.
518 Binary compatible with 040.
519 File compatible with 040.
521 2). MARM releasables are now pre-PETRAN'd, so you can remove those UID
522 settings from your .oby and .iby files.
524 3). Two new static members have been added to CDictionaryFileStore:
526 CDictionaryFileStore* SystemL[C](RFs&)
528 This opens (creating if necessary) the system dictionary file (INI
529 file), and replaces the EIKON functions to do the same thing.
534 (Made by AjThoelke, 2 April 1997)
536 1). Built using E32TOOLS/056, E32/095 and F32/064. ARM narrow release size
537 is 68108 bytes (66.5K).
539 Binary compatible with 039.
540 File compatible with 039.
542 2). Destroying a file store resulted in a Panic if the file had previously
543 been detached, due to an attempted Flush() on an unopen file.
545 To fix this a kludge access to RSubSessionBase::SubSessionHandle() has
546 been made to determine if the call to flush should be made or not. This
547 now allows file stroes to be destroyed with out being attached to a
553 (Made by AjThoelke, 27 March 1997)
555 1). Built using E32TOOLS/055, E32/095 and F32/063. ARM narrow release size
556 is 68096 bytes (66.5K).
558 Binary compatible with 038.
559 File compatible with 038.
561 2). Fixed bug SW-1713. CPermanentFileStore more readily discards in-memory
562 state during revert, ensuring correct re-synchronization with the file
568 (Made by AjThoelke, 20 March 1997)
570 1). Built using E32TOOLS/054, E32/093 and F32/061. ARM narrow release size
571 is 68064 bytes (66.5K).
573 Binary compatible with 037.
574 File compatible with 037.
576 2). Fixed a bug where REncryptStream::AttachL[C]() and
577 RDecryptStream::AttachL[C]() were failing to release the host stream
578 if they left with an error.
580 3). Made the TSwizzleC<TAny>::TSwizzleC(TStreamRef) constructor public to
581 allow some clever adaptation of the TSwizzle/CStoreMap protocol for
584 4). RFileBuf::SetSizeL() only writes outstanding data which would be in
585 the file following any file truncation, rather than attempting to write
586 everything in the write buffer.
591 (Made by AjThoelke, 6 March 1997)
593 1). Built using E32TOOLS/051, E32/090 and F32/059. ARM narrow release size
594 is 68012 bytes (66.4K).
596 Binary compatible with 036.
597 Mostly file compatible with 036: streams ids in embedded stores have
600 2). Fixed a bug in embedded stores within direct-type store streams
601 (CDirectFileStore and CEmbeddedStore). Embedded stores being copied
602 directly (without restoration) where ending up corrupted.
604 The fix is to use beginning-relative offsets in direct store streams,
605 which affects the stream ids within these stores, so breaking any such
606 existing embedded stores.
608 3). CEmbeddedStore::Start() is a small additional service which returns the
609 stream position of the store within its host stream.
614 (Made by AjThoelke, 20 February 1997)
616 1). Built using E32TOOLS/051, E32/088 and F32/055. ARM narrow release size
617 is 68020 bytes (66.4K).
619 Binary compatible with 035. File compatible with 035.
621 2). Provided the ability to access an embedded store's underlying stream
622 buffer. This follows a similar protocol to extracting the file from
625 CEmbeddedStore::Host() returns the stream buffer that is hosting the
626 embedded store. This can be used as desired, but the store should not be
627 used at the same time. The embedded store rerains "ownership" of the
630 CEmbeddedStore::Detach() releases the store's ownership of the stream
631 buffer, the caller is then responsible for discarding the buffer.
633 CEmbeddedStore::Reattach(MStreamBuf*) attaches a stream buffer to the
636 CEmbeddedStore::Position(TStreamId) is a static function which reports
637 the position in the host stream of a given stream id within the store.
639 3). This is all just convenience machinery. What really matters is the
642 The layout of direct-style stores is now formally defined as:
644 |-header-|-root id/pos-|-stream 1-|-stream 2-|...|-stream n-|-root stream...
646 with stream ids having values equal to the stream's offset in the host.
647 The whole thing is open-ended; ie, nothing is known about what's after
648 the start of the root stream--except during creation, when it's assumed
649 that the end of the host is a good place to write new streams.
651 In the case of a direct file store, the header is a TCheckedUid::Des()
652 describing the file type. In the case of embedded stores, the header is
653 at the client's discretion--whatever is written to the stream before
654 the embedded store is constructed over it.
656 It follows that you can copy the whole thing by knowing the lengths
657 of header and root streams. You extract the root id/pos, go back to
658 the beginning, copy up to the start of the root and copy the root
659 stream by whatever means available to you.
661 A (not entirely transparent) example of this is in the TSTOR\T_EMBED
662 test program; see the testCopy() function.
665 (It also follows that direct-style stores can be put together quite
666 easily by foreign agents--probably a good thing.)
672 (Made by AjThoelke, 3 February 1997)
674 1). Built using E32TOOLS/051, E32/086 and F32/050. ARM narrow release size
675 is 67988 bytes (66.4K).
677 This is the B5 release. Binary compatible with 034
679 2). Fixed a bug of omission: build 033 claimed that the
680 CDictionaryFileStore would compact the store as part of committing it.
681 Somehow the code was lost in transit--this has been remedied.
683 This bug is known to crash LShell during initialisation in EIKON 156.
686 * Don't leave streams open when you commit a store, it is bad
687 programming practice.
689 * Don't leave streams open when you compact a store, it will
690 refuse with KErrInUse.
692 The second one may cause your code to fail when working with INI
693 files because the dictionary stores now attempt to compact during
696 3). Fixed a StreamFilter bug which was claiming end-of-stream prematurely,
697 preventing the decryption filters from working correctly.
699 This fixes B4 problem SW-295.
704 (Made by AjThoelke, 21st January 1997)
706 1). Built using E32TOOLS/050, E32/085 and F32/049. ARM narrow release size
707 is 67904 bytes (66.3K).
709 File compatible as for 033
710 Exploring new realms of the Almost Binary Compatible(TM)
711 This release is 99% Binary-Incompatibility Free.
713 In particular, if your component does not depend on the header file
714 s32crypt.h it is guaranteed to be 100% binary compatible with this
717 If it does depend on that header file (I'm talking to the 1% now), it
718 will be 100% binary compatible if the only class you use from that
719 header is CSecureStore. Otherwise, if your code explicitly uses any
720 of the classes TEncryptFilter, TDecryptFilter, REncryptStream and
721 RDecryptStream you will need to recompile.
724 2). Completed the encryption filters: they now use the security objects
725 to perform the data encryption and decryption. This cost a re-write of
726 the encryption filter API, and the not-quite-binary-compatiblility
727 disucssed above. All the functionality of S32crypt.h has now been
730 3). Errors which should be recoverable were causing File stores to shut
731 down completely if they came at an inoppurtune moment. This has been
732 fixed, now a failure during commit will allow the store to re-commence
733 operations following a call to Revert().
738 (Made by AjThoelke, 13th January 1997)
740 1). Binary incompatible with 032
741 File compatible as for 031
743 Built using E32TOOLS/050, E32/085 and F32/049. ARM narrow release size
744 is 66968 bytes (65.4K).
747 CPermanentFileStore panic after an OOM when initialising compaction.
749 3). Added public PushL() and Pop() members to RReadStream and RWriteStream
750 which invoke CleanupReleasePushL() on the object. This saves some code
753 Similarly added a public PushL() member to MStreamBuf
757 CDictionaryFileStore now deals properly with access contentions when
758 acquiring the file and race conditions when creating and constructing
759 the file. It will retry several times to open the file if it discovers
760 that it is in use, waiting briefly between attempts.
762 Commiting the CDictionaryFileStore now has the effect of also
765 5). Secure Store API changes.
767 Following on from the changes to the encryption API in E32;
768 CSecureStore now takes a const CSecurityBase& on construction, and
769 uses it to construct encryption and decryption objects as required for
772 The stand-alone REncryptStream and RDecryptStream API has changed:
773 The Open and Attach members can now leave, so the constructor version
774 has been dropped, and LC variants have also been supplied. The last
775 parameter of these is passed on to the CSecurityBase::NewEncryptL and
778 NOTE: The implementation of the encryption and decryption filters does
779 not yet use the security base components, but the API is complete.
784 (Made by AjThoelke, 10th December 1996)
786 1). Binary compatible with 031.
787 File compatibility as for 031.
789 Built using E32TOOLS/048, E32/078 and F32/044. ARM narrow release size
790 is 66932 bytes (65.4K).
794 2). RDictionaryReadStream::OpenLC() and RDictionaryWriteStream::AssignLC()
795 were using the cleanup stack incorrectly. This has been fixed.
800 (Made by AjThoelke, 4 December 1996)
802 1). Binary compatible with 030.
803 File compatibility as for 030.
805 Built using E32TOOLS/048, E32/075 and F32/042. ARM narrow release size
806 is 66892 bytes (65.3K).
808 2). Minor version number set to 4 (this is the B4 release)
810 3). By popular demand, the Debug build info-print on Leaving has been
813 4). Fixed a data-losing read ahead bug in RFileBuf (spotted by DBMS).
818 (Made by Geert, 30 November 1996)
820 1). Largely source compatible with 028-029. Binary incompatible.
821 File compatibility as for 029.
823 Built using E32TOOLS/048, E32/075 and F32/042. ARM narrow release size
824 is 66812 bytes (65.2K).
826 2). CEmbeddedStore now takes ownership of the stream passed into it on
827 construction. Before, the client was responsible for closing the stream.
829 Ownership transfers on entry of CEmbeddedStore::FromL[C]() or NewL[C](),
830 and the incoming stream parameter is cleared.
832 3). There is no longer any attempt to commit automatically in destructors.
833 For CEmbeddedStore, this makes no sense when the object is on the cleanup
834 stack, where cleanup would cause the partially written stream hosting the
835 embedded store to be committed, outside clients' control.
837 Also, while transaction-capable stores such as CPermanentFileStore rarely
838 exist on the cleanup stack for very long, a similar argument applies.
839 Transactions serve to take persistent data from one consistent state to
840 another, with no in-between states.
841 Clients mark their confidence in the integrity of the data by committing
842 at certain, carefully chosen points. Having the destruction of the store
843 object make up their minds for them as to the data's integrity is
846 One knock-on effect is that a permanent file store will remain empty until
847 explicitly committed. Before you could get away with not committing in
848 non-production code since the destructor would have kicked in.
849 This is no longer the case.
851 4). For efficiency reasons, cleanup stack-related services have changed. The
852 new services consist of static template classes CleanupDelete<T>,
853 CleanupClose<T> and CleanupRelease<T>, which have appropriate PushL()
855 Template functions CleanupDeletePushL(), CleanupClosePushL() and
856 CleanupReleasePushL() choose the right class based on the type of their
862 CleanupClosePushL(aFile);
864 where before you would have written
866 CleanupStack::PushL(CleanupClose(aFile));
868 This change works around GCC limitations to do with temporaries of
869 user-defined types, shaving nearly 0.5K off STORE.
871 5). Andrew has implemented delimited read functionality for text which was
872 added to RReadStream as RReadStream::ReadL(TDes8&,TChar) and
873 ReadL(TDes16&,TChar). These read from the stream until either the
874 delimiting character is found or the descriptor is full.
875 The delimiter is copied into the target descriptor along with the rest of
876 the data. As ever, it's the client's responsibility to ensure that things
877 are delimited properly, and it is therefore a leaving offence (KErrEof)
878 to run out stream prematurely.
880 6). Added support for .ini file like stores, courtesy of Ian. See Ian's notes
883 7). New header <s32crypt.h> adds encryption and decryption facilities. Their
884 implementation is strictly a mock-up, since the CSecurityBase services
885 they rely on require some work. The APIs are liable to change somewhat as
888 The basic idea is that a hash derived from the user's password is stored
889 with the encrypted data. Setting a password is done using function
890 CSecurityBase::SetL(), after which the data to be stored can be extracted
891 using CSecurityBase::SecurityData(). This can later be used to restore a
892 security object to this state.
894 Encryption/decryption is enabled using function CSecurityBase::PrepareL(),
895 taking a password and validating it against the stored security data. Thus
896 primed, the object can be used with STORE encryption services.
898 RDecryptStream is a concrete read stream installing a decryption filter
899 over an established read stream. It can be set up to take ownership of the
900 source stream using RDecryptStream::Attach(RReadStream&,CSecurityBase&) or
901 the equivalent constructor, or just to use it using Open().
902 REncryptStream is the equivalent write stream.
904 Because of the slight data expansion due to padding in most strong
905 encryption algorithms, it does not normally make sense to use the host
906 stream any further after the filter is removed, as on read its stream
907 position would not have been moved past an unknown amount of padding.
908 In most cases you will want to pass ownership of the host stream to the
911 CSecureStore is a concrete stream store constructed over a host store
912 and putting a decryption or encryption filter over its streams as they are
913 accessed through the secure store adaptor.
915 Store-aware components can be passed a CSecureStore and remain oblivious as
916 to the encryption of the streams they are accessing.
917 It implements only those services required by store-aware components written
918 to run against a common-denominator store.
920 CSecureStore never takes ownership of the host store.
922 8). CXxxFileStore::NewL[C]() has changed to conform to Arwel's SDK
923 documentation. Before it required the incoming file to be empty, with all
924 sorts of niggling little problems. Now an incoming file is simply emptied.
926 9). KErrDoesNotExist changed to KErrNotFound throughout.
928 10).Debug mode STORE now sends diagnostic messages to the notifier via
929 User::InfoPrint(). The effect is dependent on the notifier server you're
930 running, but only 'hard' failures should cause these messages to be sent.
932 Please let us know if this gets in anybody's way.
934 11).Direct file stores no longer mark the start of streams with "Stream" in
936 Use permanent file stores and the PFSDUMP utility to examine streams.
938 12).MStreamInChan and MStreamOutChan were renamed MStreamInput and
939 MStreamOutput, reasoning that they are after all just intelligent I/O
940 buffers, interacting with a stream in more interesting ways than a lifeless
941 piece of memory can. No need to use arcane O/S terminology.
943 13).Filter framework tweaked slightly. Data can now only ever be moved
944 through a filter forcibly when the filter is part of a write stream, by
945 using CommitL(). On read, if there isn't enough data left in the source
946 stream to move through the filter will stall, resulting in premature
952 //// CDictionaryStore ////
954 A dictionary store is similar to a stream store in that it contains streams,
955 but the streams in a dictionary store are accessed by uid instead of by stream
956 id. CDictionaryStore does not inherit from CStreamStore or any of it's
957 children, though it does privately own a Persistent store.
959 CDictionaryStore, defined in <s32stor.h>, is a base class that defines the
960 api for all dictionary stores, but that is independent of the type of store
961 actually used to implement it.
963 class CDictionaryStore : public CBase
966 void Remove(TUid aUid);
967 void RemoveL(TUid aUid);
968 TBool IsPresentL(TUid aUid) const;
976 Streams may be removed by uid using the Remove[L]() methods. If the stream
977 exists it will be deleted, otherwise calling this method will have no effect.
978 IsPresentL() will return true if a stream with a given uid exists in the store.
980 Commit() and Revert() have the same effect as on any CStreamStore derived
981 class. After making changes to the store (ie writing or removing one or more
982 streams) Commit() must be called before closing the store to persist all the
983 changes made. Failure to commit() may cause loss of data! Calling Revert() has
984 the effect of returning the store to the state it was in after the last
985 Commit() (or when it was opened, if no commit has been made).
987 //// CDictionaryFileStore ////
989 CDictionaryFileStore, defined in <s32file.h>, is a particular implementation
990 of CDictionaryStore based around a permanent file store. This class is
991 suitable for use as an ini file etc.
993 class CDictionaryFileStore : public CDictionaryStore
996 static CDictionaryFileStore* OpenL(RFs& aFs,const TDesC& aName,TUid aUid3);
997 static CDictionaryFileStore* OpenLC(RFs& aFs,const TDesC& aName,TUid aUid3);
1000 OpenL[C]() should be called to open a dictionary file or to create a new one.
1001 "aName" is understood to be the full path of the file, and "aUid3" should be
1002 the third uid of the file (used for type checking). Passing in KNullUid is
1003 illegal and will result in a panic.
1005 OpenL[C]() will attempt to open aName if it exists. If no file matches that
1006 path then a new file aName is created and its third uid is set to aUid3.
1007 If aFile exists but the uid's do not match then OpenL[C]() leaves KErrCorrupt
1008 (awaiting a better error...).
1010 //// RDictionaryReadStream ////
1012 Instances of RDictionaryReadStream, defined in <s32stor.h>, are used to read
1013 data from the dictionary store. They act in a similar way to other RReadStreams.
1015 class RDictionaryReadStream : public RReadStream
1018 void OpenL(const CDictionaryStore& aDictStore,TUid aUid);
1019 void OpenLC(const CDictionaryStore& aDictStore,TUid aUid);
1022 OpenL[C]() should be called to ready a stream for reading, passing in an open
1023 dictionary store and the uid of the stream required. If this stream exists in
1024 the store it is opened, otherwise an empty stream is opened. Reading from an
1025 empty stream will result in an immediate leave KErrEof. All of RReadStream's
1026 reading methods are supported.
1028 //// RDictionaryWriteStream ////
1030 Instances of RDictionaryWriteStream, defined in <s32stor.h>, are used to write
1031 data to a dictionary store. They act in a similar way to other RWriteStreams.
1033 class RDictionaryWriteStream : public RWriteStream
1036 void AssignL(CDictionaryStore& aDictStore,TUid aUid);
1037 void AssignLC(CDictionaryStore& aDictStore,TUid aUid);
1040 AssignL[C]() should be called to ready a stream in a aDictStore for writing.
1041 If a stream matching aUid exists in the store then it is replaced, otherwise
1042 a new stream is created. After writing, a stream should always be Commit()'ed,
1043 otherwise all data will be lost. All of RWriteStream's write methods are
1046 //// Usage of dictionary stores ////
1048 CDictionaryStore derived classes are designed to be temporary objects.
1049 A dictionary store should be opened, a read/write performed as required, and
1050 the store should then be closed and destroyed. Keeping a dictionary store open
1051 for longer than is necessary will stop other people being able to access it
1052 --this can be a problem if the store is eg. the system ini file.
1056 (Made by Geert, 5 November 1996)
1058 1). Binary compatible with 028. Generally file compatible with 027 and 028.
1059 (Reads 025 files or newer.) However, compaction--see below--may result in
1060 files incompatible with any prior release.
1062 Uses E32TOOLS/046, E32/072 and F32/038. ARM narrow release DLL 62972
1063 bytes (61.5K), up 7.6% due to compaction.
1065 2). Permanent file store compaction is now functional--if not tested to the
1066 usual high standard. ;-)
1068 Running compaction unearthed a FAT file system defect which Jal claims
1069 affects both internal drive and CF-card, but which we've only seen on the
1070 RAM drive. The effect is STORE reporting random file corruption.
1071 (Most likely KErrCorrupt, but might come out as KErrNotSupported or others
1072 of that ilk.) Hopefully a fix will be available soon.
1074 Background compaction should be operational but remains to be tested.
1075 Compaction and normal store access interact in that changing and
1076 committing the store will cause the current compaction pass to be
1077 abandoned. (The compactor returns KErrNotReady thereafter.) Also,
1078 compaction steps which physically move a stream fail to do so if any stream
1079 is open at the time (KErrInUse). In the former case, the compactor can be
1080 reset to start a new pass; in the latter, things pick up again when the
1081 offending streams are closed.
1083 Note that running the compaction process in itself does not cause the file
1084 to shrink; you'll need to commit the store for that to happen. If the
1085 store was undergoing changes whilst being compacted the file may not be
1086 truncated even then. However, streams will have been moved down the file
1087 and subsequent compactions will have less work to do.
1089 3). PFSDUMP can now be made to produce output for 'logical' comparison of two
1090 stores; ie, without file offsets and the like. (-c switch)
1092 4). When ownership of a file handle passes into STORE, the incoming handle is
1093 now cleared. This allows those handles to be on the cleanup stack as they
1094 are passed in and is generally slightly safer. Of course this change
1095 breaks code relying on the handle remaining valid after it was passed in.
1097 5). In a future release, CEmbeddedStore will be changed so that it takes
1098 ownership of the stream passed in on instantiation. The incoming stream
1099 will be cleared much like file handles are now.
1101 The original spec of several embedded stores, one after the other, sharing
1102 a stream would be abandoned. As far as I can tell, there's no real
1103 requirement for this, and it results in more code, both within STORE and
1106 The change was originally earmarked for this release but backed out
1107 because it would have compromised binary compatibility. If you can think
1108 of a problem with this new, simplified spec, please let me know as soon
1113 (Made by Geert, 28 October 1996)
1115 1). Not binary compatible with any previous releases. Reads 025 files or
1116 newer, writes files compatible with 027.
1118 Uses E32TOOLS/045, E32/072 and F32/038. ARM narrow release DLL is 58508
1121 2). Implemented type-safe linkage for MARM builds. STORE's uid3 is 0x100000CF.
1123 3). CPermanentFileStore reclamation is now operational. In the context of
1124 permanent file stores, reclamation simply reports free space, as
1125 compaction is the only way a permanent file store can make space
1126 available for reuse.
1128 Compaction is not yet available. For the time being, the relevant services
1129 have the same effect as reclamation. Client code for compaction can be
1130 written and run, but do bear in mind that having a stream open causes
1131 compaction to stall, whereas it has no effect on reclamation.
1133 Reclamation runs in time roughly proportional to the number of streams in
1134 the store, and is generally blindingly fast. (<0.4s for a 500 stream
1135 store, with some file seeking optimisation yet to come.)
1137 Committing the store, or compacting it during reclamation causes the
1138 reclamation process to be aborted.
1140 4). During implementation of permanent file store reclamation, the non-leaving
1141 status of Reset() proved to be untenable.
1143 Changed to RStoreReclaim::ResetL().
1147 (Made by Geert, 23 October 1996)
1149 1). Binary compatible with 024 and newer. Files produced by 027 may not be
1150 readable by older releases. (See point 6 below.) However, this release
1151 reads all files produced by 025 or newer.
1153 Uses E32TOOLS/045, E32/071 and F32/037. ARM narrow release DLL is 56632
1156 2). At MartinB's request, split <s32stor.h> in two, resulting in new header
1157 <s32std.h>. This header publishes most commonly used data types, including
1158 everything a STORE-aware component might need to store and restore itself.
1159 <s32std.h> pulls in some 1150 lines less than does <s32stor.h>, which is
1160 quite nice but not terribly significant given that <e32base.h> accounts
1161 for nearly 6000 lines--3/4 of <s32stor.h>...
1163 Note that <s32std.h> declares CStreamStore but does *not* define it.
1165 3). Added CStreamDictionary, previously featured in APPARCH, making this
1166 release incompatible with APPARCH 016 and 017.
1168 4). Thanks to Andrew, STORE now comes with its own set of tools.
1169 (well, just the one, currently ;-)
1170 They live in new release component TOOLS. MNT getrel fetches this into
1171 your \Epoc32\Tools directory.
1173 PFSDUMP analyses permanent file stores. See the notes at the bottom for a
1174 'read me' file on its operation.
1176 5). F32's new 'set error condition' functionality (037) can be used to
1177 simulate failures. Used without a client-side buffer, the combination of
1178 file server and allocation failure simulation makes it possible to cause
1179 the failure of virtually everything in STORE that has the potential to
1182 Disabling the client side buffer is done through CFileStore::Reset(0).
1183 (or RFileBuf::Reset(0)) See earlier release notes for Reset()
1186 Let me hear no more of a 'store failure tool'. (You know who you are.)
1188 6). Added user-defined type TCardinality, a type which converts to TInt and
1189 back. It has chevrons that compress small values down to take up less
1190 space. (1 byte for 0-127, 2 bytes for 128-16383, 4 bytes otherwise.)
1192 The range of TCardinality is 0 to KMaxCardinality. (2^29-1)
1194 Used TCardinality to stream the counts of arrays and buffers, as well as
1195 descriptor headers. Descriptors of up to 63 in length now take only a
1196 single byte for their length count.
1198 7). Fixed bugs reported by Bruce, MartinH and Duncan.
1203 Permanent File Store Dump Utility
1205 This tool can dump the contents of a permanent file store in terms of the
1206 streams it contains. So it can help in analysing stream usage, as well as
1207 debugging use of the store and stream structure. It has no knowledge of the
1208 internal structure of streams. It cannot know how the streams reference each
1209 other, so it cannot inform you of "stream heaven" or dangling stream
1212 A default invocation of the utility will generate output something like:
1214 > D:\epoc32\wins\c\dbms-tst__on>pfsdump t_window.db
1216 > EPOC/32 PermanentFileStore Dump Utility Version 00.01(build 027)
1217 > Copyright (c) Symbian Ltd. 1996
1219 > Dumping t_window.db
1221 > Toc at 9a3[9c3] with 6 entries: 6 allocated, 0 free
1224 > Stream 000001:0 at 998[9b8], 9 bytes
1225 > Stream 000002:0 at 63c[65c], 73 bytes
1226 > Stream 000003:0 at 956[976], 64 bytes
1227 > Stream 000004:0 at 931[951], 16 bytes
1228 > Stream 000005:0 at 943[963], 17 bytes
1229 > Stream 000006:0 at 427[447], 512 bytes
1231 "Toc" is the table-of-contents. All locations in the file are given in the
1232 format <streampos>[<file offset>] in hexadecimal. The number of entries in the
1233 Toc is the maximum number of stream IDs that existed concurrently in the store.
1234 The number allocated is the number of streams currently in the store.
1236 Stream IDs are always represented as <index>:<generation>, where index is a 6
1237 digit hexadecimal value and generation is a single hex digit. The TStreamId is
1238 calculated by reversing the order, e.g. stream 000004:3 has a TStreamId value
1239 of 0x3000004. The generation number is incremented every time a toc entry is
1240 recycled for a new stream.
1242 Every stream in the store is listed, along with its location and its length.
1243 If the -v option is specified, the contents of the stream will be dumped for
1246 If a store has not been compacted, it is possible to view the history of the
1247 store using the -r<n> option, which dumps the nth previous revision
1248 (commit point) of the store. The default is -r0, i.e. the last commit on the
1249 store, -r1 will show the contents after the previous commit in the store, etc.,
1250 thus making the entire history of the store available. (This does not work
1251 for streams that have been re-written in place.)
1252 Following compaction, some or all of previous revisions may be lost or corrupt.
1254 If you get any errors reported when running PFSDUMP, let us know!
1258 (Made by Geert, 8 October 1996)
1260 1). Compatible with 025 in every conceivable sense of the word; merely
1261 binary compatible with 024.
1263 Built against E32TOOLS/045, E32/070 and F32/036. ARM narrow release
1264 build is 55264 bytes. (54.0K)
1266 2). KNullStreamId now officially denotes a stream that is guaranteed not to
1267 exist. Accordingly, using it to open a stream and so on results in
1268 KErrDoesNotExist. (Earlier releases were liable to panic, which Jezar
1269 convinced me wasn't the right thing to do.)
1271 3). Up to 025, CPermanentFileStore held its entire 'table of contents' in
1272 memory, at a cost of a whopping 12 bytes per stream in existence.
1273 This release uses a little cache, the bulk of the toc is left in the file.
1274 On the other hand, every stream touched by the current, uncommitted
1275 transaction needs 8 bytes; ie, the amount of work done in a single
1276 transaction is constrained by available memory.
1278 I don't expect a very noticeable performance impact, which is borne out
1279 by STORE and DBMS test code. If you do spot things taking significantly
1280 longer please let me know.
1282 4). Fixed permanent file store bug sometimes failing to truncate the file
1283 properly, leading to corruption and/or panics.
1284 Bruce found another nasty to do with accessing different versions of a
1285 stream being replaced. Fixed.
1289 (Made by Geert, 3 October 1996)
1291 1). Binary compatible with 024. File formats, however, are *not* compatible.
1292 See below for details.
1294 Built using E32TOOLS/042, E32/069 and F32/035. 53804 bytes--52.5K
1295 (ARM 8-bit release).
1297 2). Changed the external representation of descriptors, buffers (CBufXxx)
1298 and arrays (CArrayFixXxx) to enable their headers to be compressed.
1299 Whilst the compression doesn't currently happen, headers written by this
1300 release will be able to be read by future releases.
1302 In general, this is the last release to break the file format. All future
1303 releases of STORE will read files written by 025. Of course this guarantee
1304 does not necessarily extend to downstream components.
1306 *WARNING*: Any attempt to read old files with streamed descriptors,
1307 buffers or arrays in them is likely to result in KErrCorrupt errors. In
1308 practice this means *all* old files are unusable. Specifically, you'll
1309 need new font files to be able to run with STORE 025. Compatible fonts
1310 will be released shortly.
1312 3). Removed differences between release and debug build permanent file store
1315 4). Renamed RFileBuf::Set(TInt aSize) to Reset(), and added
1316 CFileStore::Reset(TInt aSize). This change enables the use of a custom
1317 buffer. The effect of a bigger buffer would be most noticeable when large
1318 quantities of data are written in small chunks. When making large requests,
1319 or when reading, a bigger than default buffer is a waste of space.
1321 To reiterate, CFileStore::Reset() must only be used when the buffer is
1322 guaranteed to contain no outstanding write data. This is the case after
1323 opening a file (*not* after creation); after a *succesful* commit; or
1324 after reverting, whether successful or not.
1326 5). Fixed a permanent file store bug which would cause empty streams to panic
1327 on commit in certain circumstances. Also fixed a replace defect, where
1328 closing a prior version of a stream after the new one had been committed
1329 would blow up. Both problems reported by Bruce.
1331 6). Fixed bug where inserting into a B-tree could write a new entry outside
1332 its target node, causing random memory corruption. (Andrew)
1333 Reported by MartinD.
1335 7). TBtree::MarkBroken() would happily mark an empty B-tree as broken--empty
1336 B-trees are inherently unbreakable. You'll have to recompile to get this
1337 fix, as it's an inline function.
1341 (Made by Geert, 27 September 1996)
1343 1). This release is not compatible with anything that went before.
1345 Given the E32/069, F32/035 situation, attempting binary compatibility
1346 would have been a pointless exercise. Just as well, really, it would have
1347 been a bit shaky in places.
1349 Uses E32TOOLS/042, E32/069 and F32/035, ARM 8-bit release is 53560 bytes.
1352 2). Added TPoint, TSize and TRect chevrons, courtesy of Ian. He's promised to
1353 do some test code as well at some point. Until then: caveat emptor--this
1354 product may not be fit for any purpose whatsoever.
1358 - Fixed KEmptyBtreeToken.
1360 - Implemented broken B-tree handling. Broken B-trees can be repaired,
1361 cleared and walked using a TBtreeMark. Any attempt at other operations
1362 results in KErrCorrupt.
1364 - When inserting in order, a B-tree's index set will now be completely
1365 filled--a repaired B-tree will end up having the smallest possible index
1368 - RStorePagePool is now fully implemented, including the reclaimable page
1371 4). Added RFileBuf::SetSizeL(), improved read buffering and reduced the number
1372 of calls to RFile::Size() being made.
1374 KDefaultFileBuffer is back to being called KDefaultFileBufSize, currently
1375 defined as 0x600 (1.5K)--now really the size used. Withdrew
1376 RFileBuf::Buffer(), previously known as Size().
1378 5). Added KEmptyPagedSetToken and TPagedSetToken::Count().
1382 (Made by Geert, 23 September 1996)
1384 1). Candidate final API release. Unless some of the new stuff turns out to be
1385 seriously broken the interface will not change again. Tweaked a thing or
1386 two where I thought living with their previous state would be too
1387 terrible, but for the most part changes in this release are additions.
1389 Built against E32TOOLS/041, E32/067 and F32/033. ARM 8-bit release size is
1390 51484--50.3K, down 13% due to omissions and the withdrawal of
1393 2). Naturally, <s32exp.h>, the 'experimental' header, is no more.
1394 Huffman encoding--<s32huf.h>--has also been withdrawn, possibly temporarily.
1396 3). RXxxStreams can no longer be pushed onto the cleanup stack directly,
1397 they've lost their implicit conversion to TCleanupItem. All the OpenLC()s
1398 etc remain, however, so this is unlikely to affect existing code.
1400 <s32strm.h> features new TCleanupDelete<T>, TCleanupClose<T> and
1401 TCleanupRelease<T> templates, derived from TCleanupItem, which can be used
1402 instead. These are returned from template functions
1403 CleanupDelete(T* aPtr), CleanupClose(T& aRef) and CleanupRelease(T& aRef).
1404 Pushing their return values onto the cleanup stack causes their arguments
1405 to be deleted, Close()d or Release()d on cleanup.
1407 All stream-related XxxLC() member functions use CleanupRelease().
1409 4). Withdrew RStoreXxxStream::StoreL[C]() in favour of a new, public
1410 CEmbeddedStore class. It features FromL[C](RReadStream& aStream) and
1411 NewL[C](RWriteStream& aStream) static factory functions, making it
1412 altogether more flexible than a scheme where the type of store to use is
1413 wired into RStoreXxxStream.
1417 RStoreReadStream stream;
1418 CPersistentStore* store=CEmbeddedStore::FromLC(stream);
1420 RStoreWriteStream stream;
1421 CPersistentStore* store=CEmbeddedStore::NewLC(stream);
1423 where previously you would have written
1425 RStoreReadStream stream;
1426 CPersistentStore* store=stream.StoreLC();
1428 RStoreWriteStream stream;
1429 CPersistentStore* store=stream.StoreLC();
1431 5). Revamped the various seek interfaces. MStreamBuf and TStreamMark acquire
1432 TellL() const functions, returning the current position of the relevant
1433 mark as a TStreamPos. MStreamBuf and TStreamExchange also feature SizeL()
1434 const functions returning the size of a stream--the offset of the stream
1435 end. Withdrew variants of SeekL() taking just a mark, as they are rendered
1436 obsolete by the inclusion of TellL().
1438 6.) Renamed RFileBuf::Size() to Buffer(), and KDefaultFileBufSize to
1439 KDefaultFileBuffer, so as not to conflict with the notion of stream size
1442 KDefaultFileBuffer is now advertised as 4K. This is not in fact the value
1443 used internally as RFileBuf's read buffering strategy needs to be altered
1444 to avoid spending too much effort reading data which won't be required by
1445 the client. 4K may not be the final value, either. Ultimately, the choice
1446 needs to be made on the basis of performance measurements.
1448 7). With CPermanentFileStore, and, in general, any CStreamStore implementation
1449 providing full transaction support, the effect of certain stream
1450 operations is delayed until the affected streams are committed.
1452 A stream created using RStoreWriteStream::CreateL[C]() does not come into
1453 existence until RWriteStream::Commit[L]() is first called and completes
1454 succesfully. (RWriteStream::Close() attempts an implicit commit,
1455 RWriteStream::Release() doesn't.) Until that time, attempting to open the
1456 stream using the id returned from CreateL[C]() will result in
1459 Similarly, people opening a stream which is being ReplaceL[C]()d but has
1460 not yet been committed see the stream's original contents.
1462 8). Added CStreamStore space reclamation and compaction services. Single shot
1463 (long-running) as well as incremental services are provided.
1464 In general, space reclamation makes free space available for reuse within
1465 the store, whereas compaction attempts to return as much space as possible
1466 to the global system pool; ie, to the filing system in the case of
1469 CStreamStore::ReclaimL() and CompactL() perform an entire reclamation or
1470 compacting reclamation pass in one call. They may take an extended time to
1471 complete. Both return the amount of free space in the store on completion.
1473 Use RStoreReclaim to reclaim space incrementally.
1474 RStoreReclaim::OpenL[C](CStreamStore& aStore,TInt& aCount) sets one up for
1475 incremental reclamation, whereas CompactL[C]() initiates compacting
1476 reclamation. Both return an estimate of the effort involved in aCount,
1477 which should be used to set a control variable passed into subsequent
1478 Next[L]() calls. This variable may only be changed by Next[L](), which
1479 decrements it by an unspecified amount on each call. The process finishes
1480 when the variable is set to 0. Next[L]() should not be called again after
1483 Four variants of Next[L]() are provided: synchronous leaving (1);
1484 asynchronous with guaranteed completion (2); asynchronous, initiation
1485 leaving (3); and synchronous returning error code (4).
1487 (1) void NextL(TInt& aStep): Performs a reclamation step synchronously,
1490 (2) void Next(TPckgBuf<TInt>& aStep,TRequestStatus& aStatus): Performs a
1491 reclamation step asynchronously with guaranteed completion; ie, for every
1492 call of Next(), an asynchronous request will be initiated--and
1493 eventually complete. Correct asynchronous request protocol is simply a
1494 matter of balancing waits with Next() calls. Problems are reported
1495 exclusively through aStatus. (Equivalent to p_ioc() in PLIB speak.) As far
1496 as I'm aware, asynchronous requests in EPOC/32 are all of this nature.
1498 (3) void NextL(TPckgBuf<TInt>& aStep,TRequestStatus& aStatus): Performs an
1499 asynchronous reclamation step. The initiation phase may leave in which
1500 case no request will have been started. (A leaving p_ioa(), if you like.)
1502 (4) TInt Next(TInt& aStep): Performs a reclamation step synchronously,
1503 reporting errors through its return value.
1505 Leaving variants are generally cheaper in that they do not require a trap
1508 At any time during reclamation, RStoreReclaim::Available() returns a
1509 running total of free space discovered so far. This may decrease during
1510 compacting reclamation as space is returned to the system.
1512 RStoreReclaim::Close() and Release() serve their usual purpose of
1513 releasing resources. They can be called at any time, abandoning any
1514 reclamation in progress. Reset(TInt& aCount) can be used to restart the
1515 process at any time.
1517 This release implements neither reclamation nor compaction.
1518 Both will be supported by CPermanentFileStore in a future release.
1520 9). Added asynchronous transfer services to the MStreamBuf interface.
1521 Guaranteed completion variants (1) are provided as well as ones that may
1522 leave during initiation (2).
1524 (1) Report errors through request completion exclusively:
1526 TInt Read(TDes8& aDes,TRequestStatus& aStatus);
1527 TInt Read(TDes8& aDes,TInt aMaxLength,TRequestStatus& aStatus);
1528 TInt Write(const TDesC8& aDes,TRequestStatus& aStatus);
1529 TInt Write(const TDesC8& aDes,TInt aMaxLength,TRequestStatus& aStatus);
1531 (2) Won't have started a request in case of initiation failure:
1533 TInt ReadL(TDes8& aDes,TRequestStatus& aStatus);
1534 TInt ReadL(TDes8& aDes,TInt aMaxLength,TRequestStatus& aStatus);
1535 TInt WriteL(const TDesC8& aDes,TRequestStatus& aStatus);
1536 TInt WriteL(const TDesC8& aDes,TInt aMaxLength,TRequestStatus& aStatus);
1538 In all cases, aMaxLength serves to override the descriptor as usual.
1539 During initiation, an implementation determines the maximum request it can
1540 undertake in the circumstances, which value is returned as the result of
1541 the initiation function.
1543 Note that the number of asynchronous channels available may be severely
1544 limited. For instance, streams open on a file store can have have just one
1545 pending read and one pending write between them. (Well, they could if
1546 RFileBuf implemented the interface, which it doesn't.)
1548 10).Added functions HasAvailable() and IsEmpty() to TStorePagePoolToken.
1549 Renamed RStorePagePool::Available() to HasAvailable() and added IsEmpty()
1550 member. Introduced KEmptyPagePoolToken, a constant token representing an
1551 empty--newly created or fully reclaimed--page pool.
1553 11).Added functions IsBroken(), IsIntact() and IsEmpty() to TBtreeToken, and
1554 therefore indirectly to TPagedSetToken. The new constant KEmptyBtreeToken
1555 represents the token of an empty B-tree.
1557 12).Various semi-internal changes, including:
1559 - Withdrew CStreamStore::DoAppendL(). RStoreWriteStream::AppendL[C]() just
1560 seeks to the end of an OpenL[C]()ed stream.
1562 - Added virtual functions CStreamStore::DoReclaimL() and DoCompactL(), and
1563 abstract interface MIncrementalCollector to implement space reclamation.
1565 - Changed TStreamBuf::UnderflowL() to enable more sophisticated read
1566 buffering. Withdrew MovePtr() and renamed Left() to Avail().
1568 - Brought TStreamFilter's state flags in line with current concrete stream
1573 (Made by Geert, 18 September 1996)
1575 1). A new concept in compatiblity: this release is *binary compatible* but not
1576 source compatible with STORE 021. There are some incompatible file format
1577 changes as well. See below for details.
1579 Uses E32TOOLS/041, E32/067, F32/033 or compatible. The ARM release DLL
1580 (8 bit) weighs in at 59040 bytes (57.7K).
1582 2). Withdrew or inlined several ctors and dtors, where those members were only
1583 required to work around past limitations of gcc.
1585 3). CFragmentFileStore and related bits and pieces are no longer in the public
1586 interface, although the DLL continues to export them for compatibility
1587 reasons. The next release will omit fragment file stores altogether.
1589 4). CPermanentFileStore's file format has changed and it will fail to open
1590 021-generated files.
1592 5). Generally made permanent file stores more robust; eg, files will now
1593 survive having an uncommitted stream written to them.
1594 CStreamStore::RevertL() will do the right thing as well.
1596 6). Due to efficiency considerations, CPermanentFileStore's stream id
1597 allocation scheme has changed significantly.
1599 Stream ids are now recycled, in some cases fairly rapidly. The upshot is
1600 that some bad references may go undetected by the store. However, for
1601 every stream id in use 15 others are known to be invalid, so there's generally
1602 a better than 90% chance of referential integrity problems being caught.
1604 The worst case is when a stream is deleted and replaced by a newly created
1605 one repeatedly. 16 iterations of this and the initial id will come up
1606 again. Also, after rollback--CStreamStore::RevertL()--an identical pattern of
1607 allocations and deallocations will yield identical numbers.
1609 A CPermanentFileStore can hold up to 16M streams concurrently.
1611 7). The good news is that this scheme gives the best possible stream lookup
1612 performance, for little space overhead. Per-stream overhead is 7 bytes.
1614 The size of a fully compact permanent file store is now, and for all time
1615 32+(12+7*#streams+payload)*(16K+2)/16K
1617 (The tacked-on factor represents a bulk data overhead of 0.012%.)
1619 Note that there may be some unused space in a file that in-place
1620 compaction cannot recover.
1622 8). MStreamUpdate had become surplus to requirements due to internal
1623 CPermanentFileStore changes and has been withdrawn.
1627 (Made by Geert, 1 September 1996)
1629 1). This is the B1-Day API freeze release. Whilst not binary compatible with
1630 020, it preserves source compatibility with mainstream client code; ie,
1631 for the vast majority of clients, recompilation should suffice.
1633 Built using on E32TOOLS/039, E32/066 and F32/031. The 8-bit ARM release
1634 DLL is 60192 bytes, or 58.8K.
1636 2). CPermanentFileStore is now fully functional. Fixed one or two seek bugs
1637 reported by Andrew wearing his DBMS hat.
1639 *WARNING*: Do not use a debug-build CPermanentFileStore for anything but
1640 the shortest-running tests. In debug mode, various internal parameters are
1641 set to maximise our chances of catching bugs in code that would normally
1642 run very rarely. As a result, permanent file stores are at least an order
1643 of magnitude slower in debug mode.
1645 Neither build can read the other's files.
1647 3). Fixed MNT getrel verb.
1649 4). Miscellaneous API changes (which shouldn't affect existing clients):
1651 - Adopted Release() as a counterpart to Close(). Where Close() will
1652 attempt to bring things to a successful conclusion, flushing buffers and
1653 the like, Release() backs out without any such attempt. Release() is
1654 generally more suitable as a cleanup action. Introduced the new functions
1655 where required, most notably in RReadStream and RWriteStream, which
1656 acquire Release() functions. RReadStream::Close() and Release() are
1658 Streams are released rather than closed on cleanup.
1660 - Withdrew all heap-based MStreamBuf subclasses from the public interface
1661 as too trivial to be worth reusing. HBufBuf, HShareBuf, HHufEncodeFilter
1662 and HHufDecodeFilter are no more. As a result, public headers are once
1663 again free of gcc warnings.
1665 - Replaced RFileBuf's Seize() member with a mechanism private to STORE.
1667 The remaining changes are aimed at making B-trees safer in the face of
1668 failures. Used in conjunction with STORE's transaction feature, there is
1669 no reason why B-trees should ever corrupt user data or cause stream
1672 Unless you are a STORE B-tree user, you can safely skip the rest of these
1675 5). Reworked MPagePool's interface to enable secure B-tree operation.
1676 Changed B-tree code and concrete page pool classes to match.
1678 6). CPageCache is now an entirely passive object and serves merely to enable
1679 caching page pools to share resources; ie, memory. CPageCache::FlushL()
1682 Simplified cache statistics. The cache will now only report the total
1683 number of requests made, how many of those were hits and how many were
1686 7). The base class for cache-based page page pools is now known as
1687 TCachePagePool, changed from TCachedPagePool, as that name was a bit too
1690 Added TCachePagePool::Flush(), which returns an error code, complementing
1691 the existing FlushL().
1693 No concrete cache-based page pool must be destroyed without having removed
1694 all its pages from the cache. To this end, added TCachePagePool::Purge().
1696 8). Changed RFilePagePool to bring it more in line with other file-related
1697 classes in STORE. Its interface is now very close to RFileBuf's.
1699 RFilePagePool::Close() and Release() automatically Purge() the page pool,
1700 in Close()'s case after Flush()ing.
1702 9). RStorePagePool, renamed from TStorePagePool, has all security features
1703 a B-tree needs to run safely.
1705 It can update pages safely--by Replace()ing the streams they are in--and
1706 it has a page allocator which independently keeps track of those pages a
1707 B-tree can't be guaranteed not to lose.
1709 Independent page tracking involves some persistent data which is not
1710 maintained by the page pool itself but wrapped into a TStorePagePoolToken,
1711 to become part of the client's persistent data structures.
1713 Correct use of these features in a store running transactions involves
1714 following a protocol which, whilst not terribly hard, is too complicated
1715 to go into here. For more information, talk to Andrew or myself.
1717 The change to an R-style class involved a reshuffle of the CPageCache and
1718 CStreamStore initialisation parameters. Should be reasonably
1719 straigthforward. RStorePagePool::Close() and Release() do the right thing
1720 in terms of clearing themselves out of the cache.
1722 Independent page tracking is not yet implemented.
1724 10).TBtree has undergone fairly extensive changes:
1726 - Its persistent bits are now assembled into a TBtreeToken. The new class
1727 takes over responsibility for the externalisation and internalisation of
1728 the various B-tree parameters.
1730 - TBtree::TQos has disappeared. Enter TBtreeMode, which gives you just two
1731 operating modes to choose from. Neither allows the B-tree's structure to
1732 become terminally damaged, but EBtreeFast may cause the loss of data
1733 entered into the B-tree, whereas EBtreeSecure doesn't. EBtreeSecure should
1734 be used unless the B-tree can be regenerated.
1735 Both do less writing and should therefore perform better than the service
1736 levels they replace, EQosBalance and EQosSafest.
1738 - The operating mode and token together determine the B-tree's state and
1739 so are parameters to c'tors and Set() functions. (A broken EBtreeFast
1740 B-tree must be assumed to contain damaged data.)
1742 - The First(), Root(), and Height() functions are replaced by the single
1745 - Added RepairL() function (courtesy of Andrew) to rebuild a B-tree's
1746 index set from the sequence set.
1748 - Shortened TBtree::TFindMode to TFind, and MBtreeLeafNodeOrg,
1749 MBtreeIndexNodeOrg to MBtreeLeafOrg,MBtreeIndexOrg.
1751 - TBtreeLeafNodeOrgFix and TBtreeIndexNodeOrgFix are henceforth known as
1752 TBtreeInlineLeafOrg and TBtreeInlineIndexOrg. 'Inline' referring to the
1753 fact that they store all bits associated with an entry together.
1755 TBtreeMark, the sequence set cursor, is now fully implemented.
1756 Its interface remains unchanged.
1758 As with RStorePagePool, there's a protocol to be followed to implement the
1759 safety features correctly. Feel free to ask.
1761 Derived B-tree classes have been brought more in line with other templated
1762 containers (ie, CArrayXxx). TBtreeFixBase's type-unsafe functions have
1763 become accessible and the stock template instance TBtreeFix<TAny,TAny> is
1764 available for those wishing to use B-trees of untyped fixed-length records.
1766 11).Added full complement of B-tree management functions to TPagedSet<T>.
1768 On the other hand, generally made the set functionality less B-tree
1769 flavoured. TBtreeMode, for instance, is not carried over: sets operate in
1770 secure mode only. InsertL() and DeletL() lose their return value in favour
1771 of appropriate KErrAlreadyExists and KErrDoesNotExist error conditions.
1773 By the same token, split the existing TPagedSet which would either accept
1774 or reject duplicates on insertion based on a flag argument into
1775 TPagedSet<T>, which does not allow duplicates, and TPagedMultiset<T>,
1778 TPagedMultiset arguably needs further functionality; eg, a function
1779 returning the number of occurences of a given element, but no new features
1780 have been introduced as multisets are on 'omissions'.
1782 Naturally, the set iterators work with either flavour of set.
1784 Added IsEmpty() member function to the sets and brought sets and iterators
1785 in line with CArrayXxx and TBtreeFix in terms of accessibility of untyped
1786 functions through the template 'base' class and the addition of untyped
1787 stock instances TPagedSet<TAny>, TPagedSetIter<TAny> etc.
1791 (Made by Geert, 19 August 1996)
1793 1). Depends on E32TOOLS/038, E32/065 and F32/029. Adopted the new directory
1794 structure and the organisation of releasables that goes with it.
1795 See E32 065 release notes for more details.
1797 Due to the scope of changes some MNT features are temporarily unavailable.
1799 The 8-bit ARM release mode DLL's size is 56284 bytes (55K).
1801 2). Most of the contents of <s32exp.h> have been moved to <s32file.h> or
1802 <s32share.h>. The latter is a new public header which very few people
1803 will ever need to include directly.
1805 Another of those pesky "`class Xxx' has virtual functions but non-virtual
1806 destructor" gcc warnings seems to have crept into this header. This is
1807 harmless and will be dealt with in a future release.
1809 3). TCheckedUid has acquired chevron operators.
1811 4). The 'experimental' file store interface introduced in STORE 019 has moved
1814 CWriteOnceFileStore and CRewritableFileStore are no longer with us. They
1815 are superseded by the new-style CDirectFileStore and CFragmentFileStore.
1817 File formats and functionality remain unchanged.
1819 5). The new CFileStore can open files of unknown type and instantiate the
1820 concrete subclass to be used with the file.
1822 It does this using a file store factory which is simply a NULL-terminated
1823 array of pointers to factory functions--typedef TFileStoreFactoryFunction.
1825 STORE supplies a default file store factory--KDefaultFileStoreFactory--as
1826 well as constant definitions for the functions it contains,
1827 KDirectFileStoreFactoryFunction, KPermanentFileStoreFactoryFunction and
1828 KFragmentFileStoreFactoryFunction.
1830 The factory handles files whose first UID is KDirectFileStoreLayout,
1831 KPermanentFileStoreLayout or KFragmentFileStoreLayout.
1833 Alternative factories can be declared and initialised as constant static
1834 data and will go into the .rdata section of your executable; ie, EPOC/32
1835 DLLs are no worse off than other executables.
1837 6). Opening a file of uncertain type is done through CFileStore's static
1838 OpenL() or OpenLC() functions. They take the same parameters as
1839 RFile::Open() and return a newly instantiated CFileStore.
1841 Alternatively, if you happen to have a handle to the file you can use
1842 CFileStore::FromL(RFile&) or FromLC().
1844 [For the guardians of Symbian naming conventions: these would have been
1845 called NewL() if it weren't for the fact that, with persistent objects, a
1846 distinction needs to be made between constructing a new persistent object,
1847 and merely hooking up to an existing one.
1848 I've adopted a FromL()/MarshalL() pattern for the latter case, where
1849 MarshalL() is equivalent to ConstructL() in the former.]
1851 There are also overloads of OpenL[C]() and FromL[C]() taking a custom
1854 7). The concrete file store classes also have static OpenL[C]() and FromL[C]()
1855 functions. These accept files of the right type as well as invalid
1856 type. CFileStore does not open files with an invalid type.
1858 It is possible, if not very likely, that a file's type should be lost if
1859 changed. Without this facility, such files could not be opened again.
1861 8). To create a new file store, CFileStore-derived classes feature static
1862 CreateL[C](), ReplaceL[C]() and TempL[C]() functions. They take the same
1863 parameters as the equivalent RFile functions, returning a pointer to the
1864 new file store. A newly created store only becomes operational when its
1865 type is set using SetTypeL(). (See below.)
1867 Should you have the file by handle, there are NewL[C](RFile&) functions
1870 All file store functions with file handle arguments take ownership of the
1871 file on entry; ie, if NewL[C]() or FromL[C]() fails the file is closed.
1873 CreateL[C]() and friends may leave an empty or partly written file behind
1876 9). CFileStore provides access to the file's type through the Type() function,
1877 which returns a TUidType.
1879 The file's type _must_ be set immediately after creation and can be
1880 changed subsequently using the SetTypeL() member function. SetTypeL()
1881 takes a TUidType which is required to specify the concrete file store's
1882 layout as its first id.
1884 A file store's layout id is available through the Layout() function (and
1885 also through the KXxxFileStoreLayout constants).
1887 Type()[0] may differ from Layout() only when the file's type is invalid
1888 (!Type().IsValid()).
1890 10).CFileStore::Reset(),Detach(),Reattach(RFile&) and File() afford some
1891 control over the RFileBuf at the heart of a file store.
1893 File(), and certainly Detach() and Reattach() must only be used for
1894 certain, well-behaved applications, such as substituting a new handle
1895 to the same file after it's been closed and re-opened.
1897 Reset() frees the file store's buffer space. It will be re-allocated
1898 automatically when needed. Reset() should only be used straight after a
1899 successful CommitL() or RevertL() call, which leaves the buffer empty.
1901 11).CPermanentFileStore is a brand new file store intended in due course to
1902 become the preferred choice for applications managing large numbers of
1905 It supports transactions as described in STORE 019 release notes and
1906 generally the full CPersistentStore interface, including embedded stores.
1908 The exception is appending to an existing stream, which it doesn't support.
1909 (RStoreWriteStream::AppendL[C]()) Streams can only be replaced in their
1910 entirety--using RStoreWriteStream::ReplaceL[C]()--or rewritten up to their
1911 original length--using RStoreWriteStream::OpenL[C](). KErrOverflow errors
1914 Note that a rewritten stream can not be reverted, whereas a replaced
1917 Additional design goals for the format were:
1919 - low persistent overhead: 32 bytes fixed + 2 bytes per 16K of data,
1920 overhead per stream is variable but could be as low as 4 bytes and no
1923 - fast, constant time access to any arbitrary stream.
1925 - small, bounded I/O bandwidth reduction: the insertion or removal of
1926 a 2-byte marker every 16K is all that stands between clients and the
1929 - fast random access within streams, supporting embedded stores
1932 - atomiticity of transactions in the face of failures: short of
1933 catastrophic failures--ie, loss of the file--the state recorded in the
1934 file is that of the last commit point.
1936 - relatively simple and entirely safe in-place compaction.
1938 *NOTE*: The CPermanentFileStore in this release has a few crucial bits
1939 missing and is little more than a glorified write-once jobbie. However,
1940 these defects do not affect the API and a fully functional, binary
1941 compatible version will be available within days.
1943 12).<s32buf.h> contains a new MStreamUpdate interface for atomic updates, used
1944 by CPermanentFileStore.
1948 (Made by Geert, 29 July 1996)
1950 1). Built using E32TOOLS/036, E32/064 and F32/028. Not compatible with
1953 Contains only an ARM 8-bit release build, since E32/064 doesn't come with
1954 any other variants. ESTOR.DLL grows to 56336 bytes (55K), largely due to
1955 some temporary code duplication.
1957 2). Features pre-release versions of a fair amount of new functionality.
1959 Most has been developed in parallel with existing code, and is currently
1960 available through 'experimental' header <s32exp.h>.
1962 A lot of what is part of that header at the moment is not directly of
1963 interest to STORE clients, with the exception of class XFileStore and its
1964 subclasses XDirectFileStore and XFragmentFileStore. These will shortly
1965 replace CFileStore, CWriteOnceFileStore and CRewritableFileStore,
1966 respectively. (at which point they'll be renamed CXxxFileStore, of course)
1968 Although not entirely ready for prime time yet, these represent the new
1969 file store API, which should not change substantially hereafter. I would
1970 like to hear any comments on this API you might have. The 'experimental'
1971 classes should be up to the standard of their predecessors, and support
1972 additional functionality:
1974 - XFileStore and derived classes open or create their file themselves.
1975 - XFileStore is capable of opening (_not_ creating) all known types of
1977 - They support 'embedded stores'. (In the case of XFragmentFileStore, this
1978 is subject to certain limitations. Contact me if you wish to experiment
1979 with stores embedded in fragment file stores.)
1981 3). There have been a few changes to the streaming framework. (header <s32strm.h>)
1983 An RWriteStream's externaliser of 'foreign' references
1984 (MExternalizer<TStreamRef>) has become a fixed attribute of the stream, set
1985 at construction time and never changed. This change has been carried
1986 through into the various stream implementations.
1988 In practice the only such beast around is CStoreMap, which means that where
1991 CStoreMap* map=CStoreMap::NewLC(aStore);
1993 RStoreWriteStream stream;
1994 TStreamId id=stream.CreateLC(aStore,*map);
1998 RStoreWriteStream stream(*map);
1999 TStreamId id=stream.CreateLC(aStore);
2001 This is the only stream change likely to affect existing code outside
2002 STORE. For completeness:
2004 RXxxStream::Open()--taking a MStreamBuf*--has been withdrawn. Instantiate
2005 stream objects using the equivalent constructor instead.
2007 RReadStream::Source() and RWriteStream::Sink() provide access to the
2008 stream's underlying stream buffer, for advanced applications.
2010 TExternalizerFunction and TInternalizerFunction have lost their 'r' and are
2011 known as TExternalizeFunction and TInternalizeFunction.
2013 One or two more changes to the protected interface of interest to stream
2016 4). The store framework has also undergone a number of changes.
2017 (header <s32stor.h>)
2019 The variants of RStoreWriteStream::CreateL(), OpenL(), TruncateL() and
2020 AppendL() taking a MExternalizer<TStreamRef> (or CStoreMap) have
2022 This is merely the effect of the changed relationship between write streams
2023 and these externalisers. See the previous point for more information.
2025 CStreamStore now features protocol to support transaction-like behaviour.
2026 CStreamStore::CommitL() commits changes made since the last commit point,
2027 establishing a new one. CStreamStore::RevertL() rolls the store back to
2028 its state at the last commit point.
2030 If a failure of any sort occurs, stores fully supporting transactions will
2031 be recovered to the state at the last succesful commit point; ie, on
2032 failure (eg, process termination, media failure), an implicit revert
2035 Store transactions apply to all operations affecting a whole stream at
2036 once, not to piecemeal changes made to an existing stream; ie, re-opening
2037 a stream for writing and changing or appending a few bytes is not subject
2040 Better to reflect its status under the transaction feature,
2041 RStoreWriteStream::TruncateL() has been renamed ReplaceL(). Operations
2042 subject to transactions are:
2044 - CStreamStore::ExtendL()
2045 - CStreamStore::DeleteL()
2046 - CPersistentStore::SetRootL()
2047 - RStoreWriteStream::CreateL()
2048 - RStoreWriteStream::ReplaceL()
2050 and all variations thereof.
2052 At present no flavour of store implements this behaviour. However, one
2053 that does will appear shortly.
2055 CStreamStore::Commit() is simply a non-leaving variant returning an error
2056 code. CStreamStore::Revert(), on the other hand, does not report errors
2057 and is useful as a last attempt to recover from failures. Destroying a
2058 store object will result in an implicit Commit() and, if this fails,
2061 Whilst any seekable stream can host 'embedded stores', direct support is
2062 built into RStoreReadStream and RStoreWriteStream.
2064 Their StoreL() or StoreLC() functions return a persistent store which in
2065 turn contains streams which can contain stores, ad infinitum. Until
2066 deleted, the embedded store object has sole control over the state of the
2067 stream; ie, the host stream should not be used while an embedded store is
2070 Embedded stores are of a 'direct' nature; ie, their behaviour is roughly
2071 the same as that of write-once (direct) file stores.
2072 RStoreReadStream::StoreL() returns a read-only store which can be used to
2073 restore an object network from. RStoreWriteStream returns a writable,
2074 blank store which can store an object network.
2076 Although this isn't currently implemented, if the criterion of full
2077 reachability from the root stream is satisfied, and proper bottom-up store
2078 as well as top-down restore procedures are used, it will be possible to
2079 carry on streaming after an embedded store is closed. This means that a
2080 stream can actually hold any number of embedded stores, accessible in turn.
2082 To use embedded stores with file stores, you should switch to the new
2083 XFileStore and friends, as the existing classes don't support them.
2085 Other changes are of interest to store implementors only.
2087 5). File-based streams and stores have undergone a few minor changes.
2088 (header <s32file.h>)
2090 In preparation for the introduction of the new file stores, all but the
2091 overload of CWriteOnceFileStore::NewL(), NewLC() and
2092 CRewritableFileStore::NewL(), NewLC() taking a file handle and two
2093 UIDs have been withdrawn.
2095 This will reduce the opportunity for mistakes in porting to the new API
2096 as that contains NewL() and NewLC() functions with the same signature but
2097 a different meaning. Meanwhile, just pass KNullUid for any missing TUids.
2099 RFileBuf::Attach() taking a file handle and an initial read position as
2100 well as a write position has been withdrawn as not required and too
2103 RFileBuf::Reattach() just reinstates a file handle which had been detached
2104 without changing the current read or write position. Useful in case a file
2105 needs to be closed and re-opened to give up a write lock. (for backup
2107 This functionality is carried through into the new file store API. It is
2108 vital that the file contents shouldn't change while the file is detached.
2109 Or indeed, ever, except under the store's control.
2111 RFileBuf::Seize(RFileBuf&) is a 'destructive assignment' operation,
2112 whereby one buffer can take over all resources managed by another, leaving
2115 6). Changes to <s32buf.h> include:
2117 - Added constant KStreamBeginning, a TStreamPos denoting the beginning
2118 of any seekable stream. TStreamPos::Offset() returns the offset relative
2119 to KStreamBeginning; ie, for any pos, KStreamBeginning+pos.Offset()==pos.
2120 - MStreamBuf::TLocation has become the global TStreamLocation; its values
2121 MStreamBuf::EBeginning, EBMark and EEnd the global EStreamBeginning,
2122 EStreamMark and EStreamEnd.
2124 as well as a few quasi-internal ones.
2126 7). On Arwel's recommendation, added debug mode only range checks to
2127 functions taking a descriptor and a length parameter.
2131 (Made by Geert, 9 July 1996)
2133 1). Uses E32/063, F32/027 and E32TOOLS/034. 8-bit ARM release build 42776
2136 Strictly binary compatible with 017, even though there are one or two
2137 changes in <s32file.h>
2139 2). Optimised RFileBuf's seek function to do as little work as possible.
2141 No file server calls will be made unless the write mark is moved or
2142 seeking from the end of the file, and seek will preserve an existing
2143 bufferful of read data whenever the resulting position is within that
2146 While this should speed up most file store operations, the effect will
2147 be most noticeable with rewritable file stores containing a large
2148 proportion of small streams. (<512 bytes) Performance increases of up to
2149 200% have been measured.
2151 3). Fixed a CPageCache bug which would cause release mode code to see 'ghost'
2152 data in certain rare circumstances.
2154 A cache page's owning page pool was not cleared on initialisation so that,
2155 if cache and page pool happened to be instantiated in the same cells as
2156 a previous incarnation the cache would contain old data. This would happen
2157 in release mode only since heaps clear freed cells in debug mode.
2159 Fixed by clearing the owner pointer during initialisation.
2161 4). Some internal changes to TBufBuf. (<s32mem.h>) Most notably, any read mark
2162 on a buffer being inserted into will be moved along with data that's
2167 (Made by Geert, 3 July 1996)
2169 1). This release is binary incompatible with 016.
2171 Uses E32/063, F32/027 and E32TOOLS/034. 8-bit ARM release build 42588
2172 bytes (41.6K), or nearly 20% savings compared to 016.
2173 This is entirely due to the compiler upgrade coming through.
2175 2). Template functions are now fully inlined, all chevron-related
2176 instantiation requests or pseudo instantiation requests can be removed.
2178 However, there is currently a problem with implicit instantiation of
2179 callable function templates. The compiler will happily lay down instances
2180 in every compilation unit that needs them and give them 'extern' linkage.
2182 This means that if two or more compilation units in your program need the
2183 same instance of a 'fat' template, your program won't link. You'll get
2184 "multiple definition of `<some template function>'" errors.
2186 Fortunately there aren't very many non-thin templates around, though it
2187 might still happen if you are unlucky enough to be streaming pointers,
2188 swizzles or arrays having the same 'content' type from different
2191 If this happens you will have no choice but to carry on compiling with
2192 -fno-implicit-templates until the compiler can be fixed. See E32TOOLS 028
2193 release notes on maktran's -g option.
2195 3). RFileBuf::Attach() no longer uses the current file position as the
2196 starting point for I/O. Instead, separate read and write positions can be
2197 passed into Attach(RFile& aFile,TInt aReadPos,TInt aWritePos).
2198 Attach(RFile& aFile,TInt aPos) uses the same position for both, and
2199 Attach(RFile& aFile) starts at position 0.
2201 Note that this means RFileBuf::Attach(RFile&)'s semantics have changed
2202 from starting at the current file position to starting at the beginning
2205 This change has been carried through into RFileReadStream and
2206 RFileWriteStream's Attach() functions, as well as the equivalent
2207 constructors, except that these take at most one starting position.
2209 4). The WINS variants now use link-by-ordinal exclusively.
2211 5). CStreamStore::DeleteL() is back to leaving with KErrNotSupported
2214 It was changed to do nothing in case delete couldn't be supported in the
2215 mistaken belief that this was necessary to implement the new CStoreMap
2216 functionality introduced in 014.
2221 CRewritableFileStore users: a performance upgrade of RFileBuf is in the works,
2222 which we should be able to release within the next couple of days.
2223 This should have significant beneficial impact on CRewritableFileStore
2225 The release will be binary compatible with 017.
2229 (Made by Geert, 31 May 1996)
2231 1). Final J-Day release, binary compatible with 014.
2233 Built using E32/061, F32/025 and E32TOOLS/028, compatible with E32/058,
2234 F32/022 and higher. ARM release build 52992 bytes (51.75K).
2236 2). Potential end-of-file death fixed in CRewritableFileStore. If, having
2237 recovered from a failed write extending the file, you'd carry on using the
2238 store, and manage to write a new stream in the space left by the failed
2239 write without using it all up, this would result in file corruption if you
2240 closed the file at this point.
2242 *WARNING*: To cope with this eventuality, CRewritableFileStore's
2243 end-of-file detection scheme has changed so that there is always a marker
2244 record in the file. 016 expects to see this marker, and, since 015 did not
2245 write it in all circumstances, 016 may not be able to use some old files.
2246 Symptoms would be KErrEof errors during stream open or creation.
2248 Note that this applies to CRewritableFileStore only. CWriteOnceFileStore
2249 files are not affected.
2251 3). Tracked down and fixed another RFileBuf problem, causing an invariant
2252 panic as a result of certain rare sequences of transfers.
2256 (Made by Geert, 28 May 1996)
2258 1). Maintenance release, binary compatible with 014 clients.
2260 Built using E32/060, F32/024 and E32TOOLS/026, compatible with E32/058,
2263 ARM release build, as reported by BUILDROM, 52928 bytes (<52K).
2265 2). Implemented link-by-ordinal import libraries for the WINS variants. All
2266 functions are fixed at 014 ordinals.
2268 However, to preserve binary compatibility with the link-by-name 014
2269 import libraries, the DLLs continue to export by name as well as by
2270 ordinal. The names will be removed after J-day.
2272 3). Fixed bug in RFileBuf to do with simultaneous reads and writes, close
2275 This would normally only show up when copying between two streams within
2276 the same file store, and result in a panic.
2278 4). Various bug fixes in CRewritableFileStore as the recent re-write settles.
2280 Symptoms would be corruption occurring in the first stream in the file
2281 and the last stream added, and a deplorable tendency for the file to grow
2282 until it takes up all available disk space.
2284 5). A number of internal changes, hammering a few things into "final" shape.
2286 Note that this has resulted in one or two header changes, although
2287 compatibility is not compromised.
2291 (Made by Geert, 21 May 1996)
2293 1). Somewhat later than intended, but there it is: STORE's J-Day release.
2294 I'd like to blame the delay on the new file typing scheme, but that
2295 wouldn't be entirely fair.
2297 Built using E32/059, F32/023 and E32TOOLS/024, compatible with E32/058,
2298 F32/022 and newer. ARM release build size 53.5K.
2300 There are a few, hopefully relatively low-impact changes. See the
2303 2). CStoreMap's role has changed somewhat. A map now takes ownership of
2304 streams passed into it using BindL(), until such time as it is told to
2305 forget about them, typically using Reset().
2307 Think of CStoreMap as a kind of cleanup stack, keeping track of newly
2308 allocated resources until a permanent home is found for them. In this
2309 case, until the head stream pointing to the streams held in the map is
2312 On destruction, the map will attempt to delete any streams it still owns,
2313 thus helping to prevent "stream heaven." Stream deletion _can_ fail, but
2314 only if the filing system is broken beyond repair. CStoreMap will not
2315 report any problems it encounters during destruction.
2317 CStoreMap::NewL() and NewLC() now take a CStreamStore& parameter, telling
2318 the map which store contains the new streams.
2322 TStreamId Xxx::StoreL(CStreamStore& aStore) const
2324 CStoreMap* map=CStoreMap::NewLC(aStore); // leave on cleanup stack
2325 StoreComponentsL(aStore,*map); // create and bind any child streams
2327 RStoreWriteStream stream;
2328 TStreamId id=stream.CreateLC(aStore,*map); // leave on cleanup stack
2329 ExternalizeL(stream); // or "stream<<*this;"
2330 stream.CommitL(); // the stream doesn't really exist before commit
2332 map->Reset(); // it's all done, forget about component streams !!!
2333 CleanupStack::PopAndDestroy(2); // close stream and delete map
2337 *WARNING*: The "map->Reset()" statement in the above is _essential_
2338 if you want to hang on to the streams created in StoreComponentsL().
2340 Note that the change in CStoreMap::NewL()'s signature means you don't
2341 have to go hunting for all places where store maps might be used: the
2344 CStoreMap's interface has become quite a bit richer, mainly in case the
2345 pattern in the example code above breaks down. Come and see us if for
2346 some reason you cannot use CStoreMap in this way.
2348 3). Implemented the EON file typing scheme. The format of a store file has
2349 changed to accommodate the 16-byte header.
2351 *WARNING*: Old files will _not_ open. CXxxFileStore::NewL() leaves with
2352 KErrGeneral. If you have a significant investment in data files which
2353 aren't easily re-generated, come and see us. We may be able to help you
2356 CXxxFileStore::NewL() and NewLC()'s optional signature argument has been
2357 replaced with up to two TUids. If you supply values they will be checked
2358 against the file header, and the file will fail to open in case of a
2361 KStoreWriteOnceLayoutId and KStoreRewritableLayoutId are the UIDs of the
2362 file formats used by STORE. They replace KWriteOnceSignature and
2363 KRewritableSignature, respectively. The file format ID occupies slot 0.
2365 4). Added members TruncateL() and TruncateLC() to RStoreWriteStream. Streams
2366 re-written using these functions will be cut off at the write position,
2367 whereas OpenL()-ed streams will retain their contents after that point.
2369 This changes the semantics of RStoreWriteStream::OpenL(), which used to
2370 mean what TruncateL() now means. The motivation for the change was the
2371 tension between security and performance. TruncateL() is safer in that,
2372 should things go wrong during write, it is virtually guaranteed that this
2373 will be detected when the file is next loaded.
2375 However, in order to achieve this, TruncateL() needs to mark the stream
2376 _before_ writing user data. Even though this is obviously more expensive,
2377 unless you have some other means of detecting potential file corruption
2378 you should use TruncateL() to re-write existing streams.
2380 Note that CRewritableFileStore does not currently implement the full
2381 semantics of TruncateL() v. OpenL().
2383 5). The interface to standalone file streams (i.e., RFileXxxStream) has
2384 changed. They now feature Open(), Create(), Replace() and Temp() functions
2385 with the same signature and semantics as the RFile members of the same
2386 name, as well as Attach(RFile&) functions taking ownership of an open
2389 When a file is attached, data transfer starts at the current position.
2391 The constructors taking a file handle are equivalent to default
2392 construction followed by Attach().
2394 6). Added function CStreamStore::Delete() which attempts to delete a stream,
2395 without reporting any errors.
2397 Both this function and the existing CStreamStore::DeleteL() now accept
2398 and ignore KNullStreamId.
2400 7). Replaced RBufferedFile with an implementation of the MStreamBuf interface
2401 by the name of RFileBuf.
2403 8). Implemented TBufBuf, and withdrew TBufSource and TBufSink. HBufBuf
2404 replaces HBufSource and HBufSink.
2406 9). Now compiles without gcc warnings.
2410 (Made by Geert, 9 May 1996)
2412 1). Hopefully the last release before STORE's J-Day API freeze.
2413 Compatible with E32/058 and F32/022 and upwards, until further notice.
2414 Built using E32TOOLS/023. ARM release build size 51K.
2416 2). Adapted array and buffer streaming code to take advantage of the new E32
2419 Prior to this release, you would have had to instantiate template
2420 functions AppendL(CArrayFix<T>&,const T&,TInt) and
2421 ResizeL(CArrayFix<T>&,TInt) in order to stream arrays under __GCC32__.
2422 As their functionality has now been absorbed into CArrayFix<T> these
2423 templates are no longer with us.
2425 3). Streaming operators for the defunct TGuid have been replaced with
2426 equivalent ones for TUid.
2428 4). A change to the semantics of RFile::Read() may break streaming operations
2429 in certain, rare circumstances. This will be fixed in a forthcoming
2430 release of F32. Symptoms of the problem are unwarranted KErrEof errors
2431 reported by stream to stream copy operations or reads from a filtered
2434 5). Removed broken formatting code from the test programs since this is now
2435 taken care of at file server startup.
2437 6). MStreamBuf has a new Synch() function returning an error code. This is in
2438 addition to the existing SynchL(). As synch's only purpose in life is to
2439 make sure all data is delivered or report an error, it might as well
2440 return success or failure as its value. Both functions are implemented by
2441 the virtual DoSynchL(), which hasn't changed.
2443 7). MStreamInChan and MStreamOutChan have changed somewhat and are now
2444 "fully pure." As a side effect, this turns them into responsible STORE
2445 citizens and clients can provide custom implementations if they so wish.
2447 8). Derived classes of TStreamBuf will now receive an UnderFlowL() or
2448 OverflowL() call when a buffer area's delimiting pointers are _both_ NULL.
2449 As this is the state of a newly constructed stream buffer, initialisation
2450 can be deferred until the first client request, which will cause
2455 (Made by Geert, 25 April 1996)
2457 1). Basically another interim release. Few API changes though the internals
2458 continue to evolve. Based on E32/057, F32/21 and E32TOOLS/21. ARM release
2459 mode code size 51K. (As reported by E32ROM.)
2461 2). Interface changes:
2463 - RReadStream and RWriteStream feature new ReadL() and WriteL() functions
2464 reading and writing 16-bit quantities, in the form of 16-bit descriptors
2465 or TUint16* and length. The purpose is obviously making wide text transfers
2466 easier to do. As with all such functions in E32, length parameters are
2467 expressed in "units," rather than size in bytes.
2469 - Because it would have been too easy to call the wrong overload, the
2470 existing 8-bit transfer functions now take a pointer to TUint8 rather than
2471 a TAny pointer. If this affects you, you may want to consider whether you
2472 should be calling the "raw" read and write functions in the first place.
2473 The streaming framework exists to do away with "struct dumping," so unless
2474 you have a buffer made up of TUint8s or TUint16s you probably shouldn't be
2475 using these functions.
2477 - <s32cache.h> has been scrapped, its contents moved to various, existing
2478 headers. The new setup may be less than totally politically correct in
2479 terms of layering, but is perhaps more practical.
2480 CPageCache and TCachedPagePool are now found in <s32page.h>; TStorePagePool
2481 has moved to <s32stor.h>, which has started including <s32page.h>; and
2482 RFilePagePool now lives in <s32file.h>.
2484 - There is a new B-tree cursor by the name of TBtreeMark. This is currently
2485 an alias for TBtreePos but will become a sequence set iterator in due
2486 course. The upshot is that TBtreeMark can only be used to walk the entries
2487 in a B-tree from start to finish, but that it will be smaller, faster, and
2488 able to be used with a broken B-tree. B-tree member functions ResetL(),
2489 NextL() as well as ExtractAtL() and AtL() accept TBtreeMarks.
2491 - In addition to the existing TPagedSetIter<T>, there are now bidirectional
2492 iterators and reverse iterators for sets, by the name of TPagedSetBiIter<T>
2493 and TPagedSetRIter<T>.
2494 The default, forward only iterator uses a TBtreeMark.
2495 The iterators all feature a new ExtractAtL(), in addition to the existing
2496 AtL() function which can be used to assign the current element to an
2497 existing object of type T.
2499 3). Implemented streaming of MARM's word-swapped doubles, so that TReal64's
2500 external representation is now also identical between WINS and MARM.
2501 File formats should now be totally compatible.
2503 4). Quasi-internal changes:
2505 - MStreamBuf has acquired SeekL() members. Seeking is optional
2506 functionality and may not work on certain implementations. (A stream
2507 of data coming in across a network connection is an example of a
2508 non-seekable stream.) Those MStreamBuf implementations providing SeekL()
2509 will be able to support stream stores, clearing the way for stores
2510 embedded within other stores.
2512 - Classes TStreamSource and TStreamSink have been withdrawn from
2513 <s32buf.h>. Their functionality is now effectively provided by the base
2516 - TStreamBuf is a new base class for streambufs with buffering
2519 - <s32mem.h> has lost classes TMemSource, TMemSink and TDesSink. They are
2520 replaced with TMemBuf and TDesBuf, derived from TStreamBuf. HMemSource,
2521 HMemSink and HDesSink have been withdrawn. New streambufs are an integral,
2522 exported part of the library so that anyone requiring HXxx versions can
2523 trivially derive them from outside.
2524 TBufBuf is intended to replace TBufSource and TBufSink and obviate the
2525 need for HBufSource and HBufSink, but is not yet implemented.
2527 5). The test code now creates its files in C:\STOR-TST\, a directory it
2529 There is also code to format the rack's RAM drive if needed, but this is
2530 currently broken. If the test code fails on a rack during formatting,
2531 format drive C: manually.
2535 (Made by Geert, 9 April 1996)
2537 1). For the most part just an upgrade release. Should be source compatible
2538 with the vast majority of client code.
2540 Uses E32/056, F32/020 and E32TOOLS/019. The ARM release build passes all
2541 tests thanks to Jal's wonderful new file server.
2543 2). New functionality:
2545 - Implemenent HBufCX's new NewL(RReadStream &aStream,TInt aMaxLength) and
2546 NewLC(RReadStream &aStream,TInt aMaxLength) static member functions.
2547 They instantiate a HBufCX of the exact length required, or leave with
2548 KErrOverflow if that length is greater than aMaxLength.
2550 - TGuid has acquired streaming operators, courtesy of Duncan.
2552 - RReadStream has a new ReadL() overload taking just a length parameter.
2553 This reads and discards the specified number of bytes from the stream.
2555 Note that the purpose of this function is not to prevent the data transfer
2556 actually happening, although it will generally save on buffer copying.
2557 Rather, it serves to save clients the hassle of managing buffer space and
2558 the transfer loop. Do not use it as a substitute for the random access
2559 afforded by a stream store.
2561 3). Various minor changes:
2563 - <s32chan.h> has been replaced by <s32buf.h> which also takes over some of
2564 <s32strm.h>'s old contents. Should be completely transparent.
2566 - Slight re-shuffle of responsibilities in streaming pointers etc. This
2567 used to be done by the stream buffer and has now become a task of the
2568 stream itself. RWriteStream doubles in size from 4 to 8 bytes.
2569 No change to the API.
2571 - TAnyExternalizer and TAnyInternalizer have become stock instances of the
2572 TExternalizer and TInternalizer templates and are henceforth known as
2573 TExternalizer<TAny> and TInternalizer<TAny>.
2575 - By the same token TAnySwizzle has become TSwizzleC<TAny>. TSwizzle<TAny>
2576 is to TSwizzleC<TAny> what TAny* is to const TAny*. Compared to generic
2577 instances they are cut down in the sense that they cannot be externalized
2578 but enhanced in that any TSwizzle<T> or TSwizzleC<T> can be converted into
2581 4). Some more, purely internal, changes were made in preparation for major new
2582 stuff coming through in the near future.
2586 (Made by Geert, 19 March 1996)
2588 1). This is the first release of STORE to include ARM releasables. It is
2589 compatible with E32/055, F32/019 and E32TOOLS/016.
2590 The WINS release components are now called EWINS and EWINSDB, instead of
2591 ESTOR and ESTORDB. The ARM release component contains an 8-bit release
2592 build only, and is called EMARM.
2594 2). The library has been reorganised to accommodate new areas of
2596 There are a number of new project directories, and if you plan to get the
2597 source down to your local hard disk it's best to start with a clean slate.
2599 The project directories each correspond roughly with one of the public
2602 - <s32strm.h> was--and still is--the stream framework header. It is the
2603 only header required to implement ExternalizeL/InternalizeL. It also
2604 defines the major abstractions used in stream implementations: data
2605 sources, sinks and filters.
2607 - <s32stor.h> remains the main stream store header. StoreL/RestoreL
2608 implementors require this header only.
2610 - <s32file.h> and <s32mem.h> provide concrete implementations of the
2611 stream/store framework, based around files or in-memory data structures,
2614 - <s32huf.h> is a stream "filter" providing on-the-fly Huffman encoding
2615 and decoding. Filters (THufEncodeFilter, THufDecodeFilter) can be combined
2616 with data sources or sinks to produce new stream implementations, or can be
2617 used directly by clients to filter an existing stream
2618 (RHufEncodeWriteStream, RHufDecodeReadStream, etc.).
2620 - <s32chan.h> is an additional header for stream implementors. Clients
2621 shouldn't ever need it.
2623 The remaining headers are to do with STORE's new B-tree functionality:
2625 B-trees are large-scale storage containers for ordered data.
2626 Persistent forms do not require the entire structure to be in memory,
2627 yet provide rapid lookup, insertion and deletion of items.
2629 - <s32page.h> contains the storage abstraction used by STORE B-trees.
2630 The storage is provided by a "page pool", which is described by the
2631 MPagePool interface. The pool provides access to in-memory pages
2632 which are released by the B-tree when no longer required.
2633 Three concrete pools are provided in STORE which use different
2634 media for their page storage:
2637 allocates pages from the default heap, storing them in an
2638 array. This pool is not persistent.
2640 - <s32cache.h> provides cached page pools. The persistent pools rely on a
2641 page cache to provide the in-memory space for their pages and to cache
2642 frequently accessed pages.
2645 The cache. Manages pages for multiple pools.
2648 uses a file directly, pages following each other sequentially
2649 through the file. Close() should be used after OpenL() or
2650 ReplaceL() to release the file resource.
2653 uses a store for persistent storage, each page having its own
2654 stream. The stream store must support ExtendL(), DeleteL() and
2655 allow streams to be re-written. (In practice, this means
2656 CRewritableFileStore only at present. Other than for testing
2657 purposes there seems little point in having a B-tree inside a
2660 - <s32btree.h> is the B-tree header itself. STORE B-trees are a flavour of
2661 B-tree sometimes referred to as B+-trees. ("B-plus-tree") The
2662 distinguishing property of a B+-tree is that all interesting data is
2663 contained within the leaf nodes. These are linked together in a singly
2664 linked list known as the "sequence set." Singly linked lists are reasonably
2665 easy to maintain safely on unreliable media.
2668 The "raw" TBtree is untyped and does not provide the means to
2669 manage the data, which is done by four organisation classes. These
2670 are set using the Connect() member.
2671 The information a B-tree requires to operate once it has its
2672 managers can be set in construction or with the Set() member.
2673 This can be extracted from a tree via the inline functions
2674 First(), Root() and Height().
2677 The important bit of TBtree is the scoped enum TQos--"Quality of
2678 service" (or security). TQos affects when pages containing the
2679 data (leaf pages) are written to persistent storage:
2680 EQosFastest: Never force a write, leaf pages will only be
2681 written if they cannot be kept in memory (e.g.
2682 flushed from the cache) (least secure but fastest)
2683 EQosBalance: Force a write if a leaf page is added or deleted.
2684 (this provides a reasonable balance between speed and
2685 safety: small amounts of user data may be lost in the
2686 event of media failure.)
2687 EQosSafest: Force a write whenever a leaf page is changed
2688 (most secure but slowest)
2689 The higher the security the more often pages will have to be
2690 written when making lots of changes to the tree.
2693 This records a position within the B-tree, and via the TBtree
2694 interface allows iteration over the contents, indexed lookup,
2695 record extraction and positioned deletion.
2698 This beast is a concrete Key for TBtree to order its data. It
2699 is very similar in construction to the keys used for CArrays.
2700 The key cannot be more than KMaxBtreeKeyLength long.
2702 Note that the text comparison constructors which do not provide a
2703 length do not assume the data is a TDesC8, they assume that the
2704 data is leading character counted, i.e. an 8-bit character count
2705 of following 8-bit data or a 16-bit character count of 16-bit
2708 TBtreeFix<Record,Lookup>
2709 For storing Record classes, ordered by the Lookup, which must be
2710 embedded within the Record class. This provides real node
2711 organisations for TBtree which assume that each entry takes up
2712 the same fixed size. A Key must still be created for this tree. A
2713 suitably constructed TBtreeKey should do the trick.
2715 e.g. suppose you want a persistent map from TInt32 to TReal64:
2722 class TMyBtree : public TBtreeFix<Map,TInt32>
2724 TMyBtree(MPagePool &pool);
2730 TMyBtree::TMyBtree(MPagePool &aPool)
2731 : TBtreeFix<Map,TInt32>(),iKey(_FOFF(Map,iLookup),ECmpTInt32)
2733 Connect(&aPool,TBtree::EQosBalance,&iKey);
2736 - <s32cont.h> layers a container-style interface over STORE B-trees.
2740 This is a packaged B-tree to provide a persistent associative set
2742 Ts can be inserted (with or without duplicates) into the set and
2743 deleted from the set, or tested for being in the set.
2744 The iterator for the set provides ResetL and NextL, these return
2745 ETrue if the AtL() member can be used to extract the current item.
2748 TPagedSetIter<T> iter(set);
2754 // do something with x;
2755 } while (iter.NextL());
2758 Note that STORE B-trees and the containers built on top of them do not
2759 acquire resources, except transiently during B-tree primitive operations.
2760 (Hence the "TXxx"-s.)
2761 All external resources are held within the page pool, B-trees and
2762 containers briefly "borrow" a pool's pages, returning them to the pool
2763 before control reverts back to client code.
2765 3). A number of relatively minor interface changes were made (some of which
2766 were already implemented in 009):
2768 - Stream implementations which don't acquire resources ("lightweight
2769 streams") are now fully supported. Concrete stream classes in this category
2770 are: RMemXxxStream, RDesXxxStream, RBufXxxStream, RHufEncodeXxxStream and
2771 RHufDecodeXxxStream. Such flavours of "Open()" as they may have don't
2772 leave, and they all have constructors combining the effect of default
2773 construction followed by Open().
2774 Closing these streams is not strictly necessary.
2776 - RBufWriteStream's interface has become a lot richer. It can now be used
2777 to insert into a buffer at an arbitrary position as well as to overwrite
2778 the data in the buffer starting anywhere within te buffer. Append(buf) is
2779 the same as Insert(buf,buf.Size()). An overwriting stream will extend the
2780 buffer when it reaches the end, and you have a choice between a stream which
2781 leaves the rest of the buffer intact (Open()) and a stream truncating the
2782 buffer (Truncate()).
2783 Note that this is a change in semantics for Open()-ed RBufWriteStreams:
2784 prior to this release they would truncate. If you need the old behaviour,
2785 use Truncate() instead.
2786 All modes behave the same when operating on an empty buffer. Actual
2787 truncation happens on CommitL()--or Close().
2789 - RMemXxxStream and RDesXxxStream allow stream access to regions of memory,
2790 described using pointer and length (RMemXxxStream) or a descriptor
2791 (RDesXxxStream). RDesWriteStream will update its host descriptor's length.
2792 This is deferred until CommitL() or Close().
2794 - Stream ID values are now limited to 28 bits. KMaxStreamIdValue,
2795 KMaskStreamIdValue, KShiftStreamIdValue are a variety of ways in which
2796 this information is available to clients.
2798 - The global streaming operator templates can be made to work with a given
2801 1. If the type is a class, it can be provided with ExternalizeL() and
2802 InternalizeL() members. The templates will call these by default.
2804 2. If it's a non-template, non-class type (e.g., an enum) you can
2805 implement specific instances of the templates. They have to match the
2806 templates' prototypes exactly, and you can't rely on conversions to
2807 limit the number of functions to write. E.g.,
2809 enum TXxx {EXxx,EYyy,EZzz};
2810 RWriteStream &operator<<(RWriteStream &aStream,const TXxx &anXxx);
2811 RReadStream &operator>>(RReadStream &aStream,TXxx &anXxx);
2813 3. If the type is somehow dependent on a template you have to plug in
2814 to the templates' implemention selection mechanism. This is a variant
2815 of the mechanism used in the Standard Template Library to select
2816 the version of an algorithm which is best suited to a particular data
2818 This situation occurs within STORE when externalising pointers to any
2819 type of object. Another case might be one where you want to provide
2820 streaming for a template class but the component defining it can't
2821 depend on STORE. (a third party library, say)
2823 Imagine you want to provide streaming functionality for E32's regions
2824 without changing the base.
2825 The TRegionFix<Nnn> subclass template precludes the use of the previous
2826 technique, so you'd have to use the method STORE uses for descriptor
2829 inline Externalize::Function Externalization(const TRegion*)
2830 {return Externalize::Function();}
2831 inline Internalize::Function Internalization(TRegion*)
2832 {return Internalize::Function();}
2834 IMPORT_C void ExternalizeL(const TRegion &aRegion,RWriteStream &aStream);
2835 IMPORT_C void InternalizeL(TRegion &aRegion,RReadStream &aStream);
2837 These Externalization() and Internalization() definitions will
2838 cause the streaming operator templates to invoke the ExternalizeL()
2839 and InternalizeL() functions provided, rather than nonexistent members.
2841 - A number of new function objects can be of assistance in some of the more
2842 complex streaming situations, e.g., streaming for a container class
2844 TAnyExternalizer/TAnyInternalizer stream an object in or out given a TAny
2846 In contrast, TExternalizer<T>/TInternalizer<T> are typed and can be
2847 converted into the above.
2848 MExternalize<T>/MInternalizer<T> are mixin classes defining an operator()
2849 which can stream Ts in or out.
2851 - Some changes to the Huffman filter interface serve to enable sharing of
2852 code and tables with E32 descriptors' Huffman encoding and decoding.
2854 4). Fixes to 009 and implementation changes:
2856 - CFileStore's destructor was still protected when it should have become
2857 public in order to work with single-phase destruction. Reported by Bruce.
2859 - A weird and wonderful MSVC4 bug caused compiler errors if KNullStreamId
2860 or KNullPageRef were used on the right hand side of assignments. Fixed by
2861 removing the outer parentheses from the macro definitions. Operator
2862 precedence shouldn't be a problems in any sensible expression.
2863 First spotted by David Wood.
2865 - A copy request from one stream to another where the source stream was
2866 reading from a buffer (RBufReadStream or RStoreReadStream on a CBufStore)
2867 and the input buffer was consumed exactly would panic. Duncan reported
2870 - MNT.CMD's getrel verb was broken when T:\pvcs\getrel mysteriously
2871 disappeared, as reported by Jal and Brendan. Now fixed.
2873 - CRewritableFileStore will now cause fewer file hits when rewriting a
2874 stream whose length remains unchanged.
2878 (Made by Geert, 27 February 1996)
2880 1). Uses E32/054 and F32/018, initial MSVC4 release.
2882 2). This is an interim release made to allow work dependent on STORE to proceed
2883 in the new environment. It represents work in progress, although with few
2884 exceptions--noted below--all existing functionality remains available.
2886 The following is a brief porting guide describing the changes that need to
2887 be made to existing STORE client code, above and beyond those mandated by
2890 - headers <s32bstr.h> and <s32fstr.h> have been renamed <s32mem.h> and
2891 <s32file.h>, respectively.
2893 - RBufReadStream and RBufWriteStream have become lightweight in the sense
2894 that they no longer acquire resources. Close()-ing these streams is now
2895 optional. CommitL(), however, cuts of the buffer at the point written to
2896 and should be used if the buffer might shrink as a result of the write
2898 Calls to OpenL() or OpenLC() should be replaced by calls to Open() or by
2899 using the constructor taking a buffer. AppendL() and AppendLC() calls
2900 can be replaced by Append().
2902 - TStream has been renamed TStreamId and KNullStream changed to
2903 KNullStreamId. A stream id's numeric value is now publicly available
2904 through a conversion of TUint32 to TStreamId and the TStreamId.Value()
2907 - CStreamStore::CreateL() has been renamed ExtendL().
2909 - All Xxx::StoreL(RWriteStream&) const and Xxx::RestoreL(RReadStream&)
2910 member functions have been renamed ExternalizeL() and InternalizeL(),
2911 respectively. Any class that has ExternalizeL/InternalizeL members can
2912 have streaming operators << and >> applied to its instances without the
2913 class designer having to provide the operator functions.
2915 - TSurrogate<T>, TSurrogateC<T> and TAnySurrogate have been renamed
2916 TSwizzle<T>, TSwizzleC<T> and TAnySwizzle, respectively. The class
2917 hierarchy has also been reorganised so that the conversions to T* and
2918 const T* could be reinstated without lurking ambiguities. Calling AsPtr()
2919 should never be necessary. The conversion to TStreamId, however, remains
2920 explicit for the old reasons.
2922 - TSurrogateX<T>::AsStream() is now known as TSwizzleX<T>::AsId().
2924 - RStoreWriteStream now takes a const CStoreMap& where it used to take a
2925 CStoreMap*, in effect. In actual fact it takes a reference to a new
2926 functor mixin CStoreMap derives from.
2928 - The stream operators copying one stream to another have been withdrawn.
2929 Use RReadStream::ReadL(RWriteStream&) or RWriteStream::WriteL(RReadStream&)
2932 - Resource support, i.e., header <s32rstr.h>, has been withdrawn. Current
2933 thinking is that the store model is not the right thing for resources,
2934 although streaming might still be used.
2936 - CArrayVar<T> and CArrayPak<T> streaming support has been withdrawn. It
2937 is not in fact possible to implement it safely, i.e., without the
2938 potential for it crashing an unsuspecting application if the input
2939 operator were to be presented with a corrupt stream. CArrayFix<T>
2940 streaming has a different implementation mechanism which no longer relies
2941 on the template classes in <s32tmpl.h> (i.e., TStreamCArrayFix<T>).
2942 Header and contents have been withdrawn.
2946 (Made by AjT, 30 January 1996)
2948 1). Now uses E32 (053) and F32 (017)
2950 2). Fixed a compilation bug which MSVC does not pick up.
2951 RReadStream is now a friend of TStreamSource
2955 (Made by AjT, 18 January 1996)
2957 1). Now uses E32 (052) and F32 (016)
2959 2). Stream buffering for files has been moved into its own class
2960 RBufferedFile. This is used by CFileStore and the new single
2961 stream file classes.
2963 3). Two new types of stream are available: RFileReadStream and
2964 RFileWriteStream. These are single-stream-files, providing stream
2967 4). All File stores now provide two information members:
2969 TInt SizeL() - returns the total store size in bytes
2970 TInt FreeSpaceL() - returns the (approximate) space in bytes that may
2971 be recovered by compaction (when we get it).
2973 5). Added free-space filling in Debug builds for fragment truncation.
2974 In Debug builds, all padding for alignment is filled with '=', all
2975 deleted data is filled with '-'.
2979 (Made by AjT, 27 December 1995)
2981 1). Now uses E32 (051) and F32 (015)
2985 (Made by AjT, 14 December 1995)
2987 1). Now uses E32 (050) and F32 (014)
2991 (Made by Geert, 24 November 1995)
2993 1). Fully exploits the cleanup stack, including the new 049 functionality.
2995 All CBase-derived classes now feature both NewL() and NewLC() static
2996 member functions. NewLC() returns a new instance which has been placed
2997 on the cleanup stack.
2999 RReadStream and RWriteStream instances provide the conversion to
3000 TCleanupItem which enables them to be pushed onto the cleanup stack.
3002 The effect is as if the stream is passed to CleanupStack::PushL() by
3003 reference; i.e., the cleanup stack holds a pointer to the RXxxStream
3004 and should be popped before it goes out of scope.
3005 The benefit of this is that the RXxxStream instance is effectively
3006 NULLed by the cleanup operation, as it is by Close(). It can therefore
3007 be Close()'d afterwards without adverse effects.
3008 The same is not true for any copies of the RXxxStream object.
3010 The various stream classes' OpenL(), CreateL() and AppendL() members
3011 have been complemented with OpenLC(), CreateLC() and AppendLC() which
3012 additionally push the stream in question.
3014 The 'canonical' form of functions opening and processing a stream
3015 should be something like the following (taken from T_SHAPE.CPP):
3017 TStream CShape::StoreL(CStreamStore &aStore) const
3020 RStoreWriteStream stream;
3021 TStream id=stream.CreateLC(aStore);
3024 CleanupStack::PopAndDestroy();
3028 Note that the cleanup operation does not attempt to commit the stream
3029 and the call to CommitL() is therefore essential. Close() causes a
3030 CommitL() to happen but does not pass on any errors. A function like
3031 the one shown should make sure to report errors during commit, since
3032 they may invalidate the entire operation.
3034 This code may result in 'stream heaven', since a new stream may be
3035 created whose id is never returned to the outside world. One possible
3036 solution would be for CreateLC to push a cleanup operation designed to
3037 get rid of the stream altogether.
3039 2). The full functionality of descriptor streaming is now implemented.
3041 TDes8 and TDes16 input operators now handle the case where the stream
3042 was written by the other class's output operator. This would occur
3043 when a text descriptor stream written on an ASCII machine is moved
3044 to a Unicode machine or vice versa. The result is the same as that
3045 of TDes16::Copy(const TDesC8&) and TDes8::Copy(const TDesC16&).
3046 The external representation of TDes16 has changed to accommodate this
3047 requirement. TDes8's remains the same.
3049 In addition, the input operators no longer panic if the streamed
3050 descriptor is too long to fit into the one being read. They now leave
3055 (Made by Geert, 15 November 1995)
3057 1). CStoreMap now associates stream ids with surrogates, rather than pointers.
3058 This is necessary to be able to store partially loaded object networks.
3059 A 'Save As...' function storing documents using deferred loading may
3060 benefit from this functionality. The alternative is to load the component,
3061 possibly temporarily, and use its StoreL() as usual.
3062 When a StoreComponentsL() encounters a component which hasn't been loaded,
3063 it should copy the component's stream using RWriteStream::WriteL
3064 (RReadStream&) or RWriteStream::WriteL(RReadStream&,TInt) and bind the
3065 existing surrogate to the new stream id.
3067 The following code illustrates this:
3069 void TShapeHolder::StoreComponentsL(
3070 CStreamStore &aStore,CStoreMap &aMap) const
3078 id=iShape->StoreL(aStore);
3081 RStoreReadStream in;
3082 in.OpenL(BackingStore(),iShape.AsStream());
3083 RStoreWriteStream out;
3084 id=out.CreateL(aStore);
3089 aMap.BindL(iShape,id);
3092 For reasons of clarity, the example ignores error recovery issues. It also
3093 assumes there is a BackingStore() member returning a reference to the store
3094 containing unloaded components. The iShape member is a surrogate.
3096 Note that the version of WriteL() used will only work if the underlying
3097 stream implementation has an end-of-stream marker of some sort.
3098 This is currently the case for all implementations, with the exception of
3099 CWriteOnceFileStore. On a CWriteOnceFileStore, use the length-limited
3100 stream copying functions.
3102 2). The implicit conversions from surrogates to pointers or stream ids have
3103 been withdrawn. The two-way implicit conversions were ambiguities
3104 waiting to happen. Moreover, when storing, stream ids are interpreted
3105 as references within the same store, whereas surrogates and pointers
3106 are treated as external references, and mapped to an 'equivalent'
3107 stream within the store. It seemed prudent not to have implicit conversions
3108 that might cause an external reference to be interpreted as an internal one
3110 Use the AsStream() and AsPtr() explicit conversion functions instead. Note
3111 that surrogates can still be used as pointers in most circumstances.
3113 3). Problems with FileStore::FlushL() during clean-up have been fixed,
3114 also ensuring stores which are not written to do not have their headers
3117 4). The rewritable file store lost its root stream saving code in a code
3118 reshuffle. This has been fixed.
3120 5). Slight change in CommitL() semantics. Whenever possible, a stream
3121 implementation will carry on accepting data after a CommitL().
3122 Currently only Huffman-filtered streams shut down on CommitL().
3124 Filters can be separate from the data producer or consumer; or they can
3125 be attached to it. Filters attached to a stream are virtually transparent:
3126 they pass CommitL()s on down the chain to the ultimate consumer.
3127 Separate filters work relative to the stream they have been opened on:
3128 CommitL()'s effect is to terminate the filter's output; the consuming
3129 stream is not committed.
3131 6). Resource stores have been modified. Header file is S32RSTR.H. Two
3132 stores are available:
3134 CResourceFileStore: is a single file resource store. No format
3135 assumptions are made, and resources are indexed from 1.
3137 CResourceStore: is a multi-file resource store, assuming the HCIL
3138 first resource format. AddFileL() adds a resource file, and returns
3139 the id of the first resource; to remove a file RemoveFileL() requires
3140 the id of the first resource.
3142 RResourceStream works with either type of store: The CResourceStore
3143 will locate the resource file which has the resource id passed.
3145 7). There is a known problem with copying streams in the presence of
3146 a filter. (e.g., copying a compressed stream to an uncompressed one)
3147 If both streams are contained within the same CRewritableFileStore,
3148 this situation will cause contention for the single read buffer,
3149 resulting in a panic.
3151 8). When the new cleanup stack arrives, hopefully in E32 049, streams will
3152 be able to be pushed onto the cleanup stack. By their nature, streams are
3153 almost always local to a function; e.g., StoreComponentsL() and
3154 RestoreComponentsL(). Streaming code should therefore benefit enormously
3159 (Made by Geert, 27 October 1995)
3161 1). Finalised the design of stream internals to support efficient
3162 stream-to-stream copying and data filters such as on-the-fly Huffman
3163 compression and decompression as well as encryption. The client API was
3166 2). Fixed a conditional inclusion in <s32bstr.h> testing the wrong macro.
3167 Thanks to Duncan Skelton for pointing this out.
3169 3). On failure, CXxxFileStore::NewL() would not Close() the RFile passed in if
3170 the initial allocation failed, but it would do so during the second phase
3171 of construction. Ownership of the file now passes to the file store as soon
3172 as it is handed to NewL(). Accordingly, if NewL() fails the file will be
3174 Thanks to David Wood and Chris Wilson for reporting this problem.
3176 4). All User::Leave()s now use error codes taken from <e32std.h>.
3178 5). Implemented Huffman encoding and decoding filters. They are not currently
3179 available through the client API, pending a rethink of the various public
3180 headers. If a requirement for standalone Huffman filters emerges, they can
3181 be added quickly and easily. T_STRM.CPP and T_HUFF.CPP demonstrate the way
3182 we intend to provide standalone filters. (RHexXxxStream and RHuffXxxStream.)
3184 6). Implemented an experimental 'resource store'. It provides access to Symbian
3185 resource files via the stream store interface. For the time being, it
3186 is made available through <s32fstr.h>. Streams opened on the resource store
3187 use the Huffman decoding filter to present the client with uncompressed
3190 7). Added a number of #pragma message()s to remind us of areas needing attention.
3192 8). Implemented TInt64 streaming and CBufXxx input. (i.e., operator>>(
3193 RReadStream&,CBufBase&))
3194 We would like to hear of people's requirements for streaming additional base
3197 9). There is a testCopy() template function in T_CONV.CPP which can provide some
3198 assistance in testing your component's StoreL() and RestoreL() functions.
3199 The intention is to make it available through a <s32test.h> header shortly.
3203 (Made by Geert, 16 October 1995)
3207 The main header files are S32STRM.H and S32STOR.H.
3208 S32BSTR.H and S32FSTR.H respectively provide memory-based and
3209 file-based streams and stores.
3211 The header file S32ADT.H is for the use of implementers of the
3212 various stream and store flavours.
3214 2). Works with E32 047 and F32 011.
3216 3). CBufStore may be removed in a future release.