windows-server-2003/com/ole32/stg/ref/readme.txt

-------------------------------------------------------------------------------                        
                        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]