Symaptic: os/persistentdata/persistentstorage/store/group/RELEASE.TXT@260cb5ec6c19 (annotated)

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

author	sl
	Tue, 10 Jun 2014 14:32:02 +0200
changeset 1	260cb5ec6c19
permissions	-rw-r--r--