windows-server-2003/com/ole32/stg/ref

-------------------------------------------------------------------------------                        

                        OLE STRUCTURED STORAGE



                      REFERERENCE IMPLEMENTATION



                            RELEASE NOTES



                            August, 2002







                          Microsoft Windows

               Copyright (C) 1992-2002, Microsoft Corporation.



-------------------------------------------------------------------------------



<add: license agreement?>



CONTENTS

--------

1) What is included in the distribution



2) Building the distribution



3) ANSI and Unicode API support



4) Documentation

 

5) Supported Interfaces and differences



6) Using the reference implementation



7) Reporting bugs



-------------------------------------------------------------------------------





1) What is included in the distribution



Included in the distribution are the source code for the interfaces IStorage,

ILockBytes, IStream, IEnumSTATSTG, IMalloc, IPropertySetStorage,

IPropertyStorage, IEnumSTATPROPSETSTG, and IEnumSTATPROPSTG. Note that not all

the functionality of these interfaces are supported, see (5) for more

information. 



Also, included are some test programs: 'stgdrt' and 'reftest' for the storage

interfaces, and 'proptest' for the property set interfaces. There is a

'readme.txt' in each of those directories that contains a short description of

the tests. For details, please read the source code files.





----------------------------

2) Building the distribution



The distributions comes with a "makefile" which includes the correct makefile

file:

        - makefile.<system>     the actual makefile

where <system> refers to the development system used to compile the

makefile. Therefore, to change the development system, edit the makefile to

include the correct files, or overwrite it with the correct one. Please note

that the files in the distribution are in the DOS format, and thus you will

need to use some utilities to remove the linefeeds before they can be compiled.



Files included in the distribution support these systems:

        -  "msc" which works with Microsoft Visual C++ compiler and 'nmake'.

           This has been tested on Windows.



        -  "gcc" which works with GNU C++ compiler aka 'gcc' and GNU's 'make',

           dependencies can be generated using 'makedepend'.

           Only tested on Solaris, HP-UX, and Linux (2.0.7). 

           However, using these files on other O.S. using the ported versions

           of the GNU tools should require minimum effort.



To compile the distribution, type 'make' or 'nmake' at the root of the src

tree. To do a clean build, do 'make clean' or 'nmake clean'. You might also

need to do a 'make depend' to update the dependencies since the standard

include paths tend to be different.



Note that in the common makefile, 'commk.<system>', in the main directory you

must specify the correct byte-order of the target machine. For Big Endian

machines, define the macro BIGENDIAN as 1. Otherwise, define LITTLEENDIAN as

1. These macros allow the byte-swapping code to work correctly.



The tests 'stgdrt', 'reftest' and 'proptest' can be built likewise.





----------------------------

3) ANSI and Unicode API support



For flexibility, the reference implementation can be compiled to support

either ANSI (i.e. char) or Unicode (i.e. WCHAR) API's. When the macro

'_UNICODE' is turned on, the APIs will be using Unicode, otherwise it uses

ANSI. 



Affected functions are those that contain 'STATSTG' parameters:

        - IEnumSTATSTG::Next

        - IStream::Stat

        - IStorage::Stat



those that contain "WCHAR" parameters:

        - StgCreateStorageEx

        - StgCreateDocfile

        - StgOpenStorage

        - StgIsStorageFile

        - IStorage::OpenStream

        - IStorage::CreateStorage

        - IStorage::OpenStorage

        - IStorage::DestroyElement

        - IStorage::RenameElement

        - IStorage::MoveElementTo

        - IStorage::SetElementTimes



and those that contain the "SNB" parameters:

        - IStorage::CopyTo

        - StgOpenStorageOnILockBytes



For property set related functions, BSTR is single char based for ANSI

API's and wide character based for UNICODE API's. This affect the following

functions :

        - SysAllocString

        - SysFreeString



Also PROPSPEC's lpwstr function is defined with LPOLESTR, which means it will

be either a 'WCHAR' array or 'char' array. This affects the following

functions: 

        - IPropertyStorage::ReadMultiple

        - IPropertyStorage::WriteMultiple

        - IPropertyStorage::DeleteMultiple



The change of names of properties to LPOLESTR affects these functions:

        - IPropertyStorage::ReadPropertyNames

        - IPropertyStorage::WritePropertyNames

        - IPropertyStorage::DeletePropertyNames



Remember to recompile the tests using the same precompiler flags before using

them on the new library!



----------------------------

4) Documentation



The documentation for the API's can be found in the MSDN library and Windows

 Platform  SDK. The property sets API's are new and their documentation can be

 found in MSDN library, or Windows Platform SDK. Another

source of documentation for the property set interfaces would be "Introducing

Distributed COM and the New OLE Features in Windows NT 4.0" in the May/96

Microsoft Systems Journal.



In addition, there is a file stgfmt2.doc which is a

Microsoft Word document describing the disk format of OLE docfiles.





----------------------------

5) Supported functions/Interfaces and differences



First of all, the reference implementation is not multi-thread safe, and it

has no marshaling support. Below are details of differences between the

reference implementation and that of the actual OLE API's.

o StgCreateDocFile

o StgCreateDocFileOnILockBytes

o StgCreateStorageEx

o StgOpenStorage

o StgOpenStorageOnILockBytes

o StgIsStorageFile

o StgIsStorageILockBytes



o IStorage        

o ILockBytes

o IStream

o IEnumSTATSTG



For the above interfaces and APIs,

- There is no transaction or simple mode in the storage interfaces, namely

  STGM_TRANSACTED/STGM_SIMPLE/STGM_PRIORITY/STGM_NOSCRATCH are not supported.

- IStorage::SetElementTime() with a NULL 'lpszName' is not supported also.

  For the same reason StgSetTimes() is not supported as well

- Access Times (part of STATSTG) for storage elements are not suported.

- ILockBytes::LockRegion(), ILockBytes::UnlockRegion(), IStream::LockRegion(),

  IStream::UnlockRegion() are not supported

- The STGOPTIONS parameter in StgCreateStorageEx can be used to create 4k sector structured storage files, which are supported in Windows 2000 and above.



o CoGetMalloc

o CoTaskMemAlloc

o CoTaskMemFree

o CoTaskRealloc



o IMalloc



These interfaces are mapped into the generic 'new' and 'delete' calls. They

are provided to ease conversion of existing code that might be dependent on

them to use the reference implementation.



o FreePropVariantArray

o PropVariantClear

o PropVariantCopy

o SysAllocString

o SysFreeString



o IPropertySetStorage

o IPropertyStorage

o IEnumSTATPROPSETSTG

o IEnumSTATPROPSTG



Code from these interfaces can be turned off by removing '-DNEWPROPS' from the

makefiles, or specifying 'nmake NOPROPS=1' when building. For these

interfaces, non-simple property sets are not supported. In fact, the reference

implementation of property sets treats non-simple propvariant types like

VT_STREAM as invalid types.





----------------------------

6) Using the reference implementation



On the Windows platform, the code will compile into a dynamic link library

(i.e. refstg.dll). To use the reference implementation, include 'storage.h'

(for the storage interfaces) and ('props.h') for the property set interfaces

to link up with the declarations. Note that only C++ headers are provided for

this distribution.



On UNIX, the code compiles into a library archive. i.e. "refstg.a". The

headers should be included as in the Windows Platform. Please note that on

certain UNIX machines, the standard headers declare 'wchar_t' as a 4-byte data

type, which is incompatible with OLE's 2-byte character type. The reference

implementation uses 'WCHAR' as the 2-byte character type, to avoid any

confusion. 



NOTE: We have experience some problems when the g++ library, namely the

fwrite() function on some versions of Linux overwrites memory in the wrong

places. This can be avoided by using 'gcc' instead of 'g++' as the compiler.



To turn off debugging code and do a 'retail' build, edit the makefiles (both

in the root and in props sub-directory) and specify the relevant flags and do 

a clean build (see the makefiles for details).







----------------------------

7) Bug reports



Please report any bugs found to :



        [email protected]