Source code of Windows XP (NT5)
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

239 lines
8.4 KiB

  1. -------------------------------------------------------------------------------
  2. OLE STRUCTURED STORAGE
  3. REFERERENCE IMPLEMENTATION
  4. RELEASE NOTES
  5. August 2, 1996
  6. Microsoft Windows
  7. Copyright (C) 1992-1996, Microsoft Corporation.
  8. -------------------------------------------------------------------------------
  9. <add: license agreement?>
  10. CONTENTS
  11. --------
  12. 1) What is included in the distribution
  13. 2) Building the distribution
  14. 3) ANSI and Unicode API support
  15. 4) Documentation
  16. 5) Supported Interfaces and differences
  17. 6) Using the reference implementation
  18. 7) Reporting bugs
  19. -------------------------------------------------------------------------------
  20. 1) What is included in the distribution
  21. Included in the distribution are the source code for the interfaces IStorage,
  22. ILockBytes, IStream, IEnumSTATSTG, IMalloc, IPropertySetStorage,
  23. IPropertyStorage, IEnumSTATPROPSETSTG, and IEnumSTATPROPSTG. Note that not all
  24. the functionality of these interfaces are supported, see (5) for more
  25. information.
  26. Also, included are some test programs: 'stgdrt' and 'reftest' for the storage
  27. interfaces, and 'proptest' for the property set interfaces. There is a
  28. 'readme.txt' in each of those directories that contains a short description of
  29. the tests. For details, please read the source code files.
  30. ----------------------------
  31. 2) Building the distribution
  32. The distributions comes with a "makefile" which includes the correct makefile
  33. file:
  34. - makefile.<system> the actual makefile
  35. where <system> refers to the development system used to compile the
  36. makefile. Therefore, to change the development system, edit the makefile to
  37. include the correct files, or overwrite it with the correct one. Please note
  38. that the files in the distribution are in the DOS format, and thus you will
  39. need to use some utilities to remove the linefeeds before they can be compiled.
  40. Files included in the distribution support these systems:
  41. - "msc" which works with Microsoft Visual C++ compiler and 'nmake'.
  42. This has been tested on Windows.
  43. - "gcc" which works with GNU C++ compiler aka 'gcc' and GNU's 'make',
  44. dependencies can be generated using 'makedepend'.
  45. Only tested on Solaris, HP-UX, and Linux (2.0.7).
  46. However, using these files on other O.S. using the ported versions
  47. of the GNU tools should require minimum effort.
  48. To compile the distribution, type 'make' or 'nmake' at the root of the src
  49. tree. To do a clean build, do 'make clean' or 'nmake clean'. You might also
  50. need to do a 'make depend' to update the dependencies since the standard
  51. include paths tend to be different.
  52. Note that in the common makefile, 'commk.<system>', in the main directory you
  53. must specify the correct byte-order of the target machine. For Big Endian
  54. machines, define the macro BIGENDIAN as 1. Otherwise, define LITTLEENDIAN as
  55. 1. These macros allow the byte-swapping code to work correctly.
  56. The tests 'stgdrt', 'reftest' and 'proptest' can be built likewise.
  57. ----------------------------
  58. 3) ANSI and Unicode API support
  59. For flexibility, the reference implementation can be compiled to support
  60. either ANSI (i.e. char) or Unicode (i.e. WCHAR) API's. When the macro
  61. '_UNICODE' is turned on, the APIs will be using Unicode, otherwise it uses
  62. ANSI.
  63. Affected functions are those that contain 'STATSTG' parameters:
  64. - IEnumSTATSTG::Next
  65. - IStream::Stat
  66. - IStorage::Stat
  67. those that contain "WCHAR" parameters:
  68. - StgCreateDocfile
  69. - StgOpenStorage
  70. - StgIsStorageFile
  71. - IStorage::OpenStream
  72. - IStorage::CreateStorage
  73. - IStorage::OpenStorage
  74. - IStorage::DestroyElement
  75. - IStorage::RenameElement
  76. - IStorage::MoveElementTo
  77. - IStorage::SetElementTimes
  78. and those that contain the "SNB" parameters:
  79. - IStorage::CopyTo
  80. - StgOpenStorageOnILockBytes
  81. For property set related functions, BSTR is single char based for ANSI
  82. API's and wide character based for UNICODE API's. This affect the following
  83. functions :
  84. - SysAllocString
  85. - SysFreeString
  86. Also PROPSPEC's lpwstr function is defined with LPOLESTR, which means it will
  87. be either a 'WCHAR' array or 'char' array. This affects the following
  88. functions:
  89. - IPropertyStorage::ReadMultiple
  90. - IPropertyStorage::WriteMultiple
  91. - IPropertyStorage::DeleteMultiple
  92. The change of names of properties to LPOLESTR affects these functions:
  93. - IPropertyStorage::ReadPropertyNames
  94. - IPropertyStorage::WritePropertyNames
  95. - IPropertyStorage::DeletePropertyNames
  96. Remember to recompile the tests using the same precompiler flags before using
  97. them on the new library!
  98. ----------------------------
  99. 4) Documentation
  100. The documentation for the API's can be found in the MSDN library and Win32
  101. SDK. The property sets API's are new and their documentation can be found in
  102. MSDN library July 96 (or later), or NT Beta 2 win32 SDK (or later). Another
  103. source of documentation for the property set interfaces would be "Introducing
  104. Distributed COM and the New OLE Features in Windows NT 4.0" in the May/96
  105. Microsoft Systems Journal.
  106. In addition, in the 'doc' sub-directory, there is a file stgfmt.doc which is a
  107. Microsoft Word document describing the disk format of OLE docfiles.
  108. ----------------------------
  109. 5) Supported functions/Interfaces and differences
  110. First of all, the reference implementation is not multi-thread safe, and it
  111. has no marshaling support. Below are details of differences between the
  112. reference implementation and that of the actual OLE API's.
  113. o StgCreateDocFile
  114. o StgCreateDocFileOnILockBytes
  115. o StgOpenStorage
  116. o StgOpenStorageOnILockBytes
  117. o StgIsStorageFile
  118. o StgIsStorageILockBytes
  119. o IStorage
  120. o ILockBytes
  121. o IStream
  122. o IEnumSTATSTG
  123. For the above interfaces and APIs,
  124. - There is no transaction or simple mode in the storage interfaces, namely
  125. STGM_TRANSACTED/STGM_SIMPLE/STGM_PRIORITY/STGM_NOSCRATCH are not supported.
  126. - IStorage::SetElementTime() with a NULL 'lpszName' is not supported also.
  127. For the same reason StgSetTimes() is not supported as well
  128. - Access Times (part of STATSTG) for storage elements are not suported.
  129. - ILockBytes::LockRegion(), ILockBytes::UnlockRegion(), IStream::LockRegion(),
  130. IStream::UnlockRegion() are not supported
  131. o CoGetMalloc
  132. o CoTaskMemAlloc
  133. o CoTaskMemFree
  134. o CoTaskRealloc
  135. o IMalloc
  136. These interfaces are mapped into the generic 'new' and 'delete' calls. They
  137. are provided to ease conversion of existing code that might be dependent on
  138. them to use the reference implementation.
  139. o FreePropVariantArray
  140. o PropVariantClear
  141. o PropVariantCopy
  142. o SysAllocString
  143. o SysFreeString
  144. o IPropertySetStorage
  145. o IPropertyStorage
  146. o IEnumSTATPROPSETSTG
  147. o IEnumSTATPROPSTG
  148. Code from these interfaces can be turned off by removing '-DNEWPROPS' from the
  149. makefiles, or specifying 'nmake NOPROPS=1' when building. For these
  150. interfaces, non-simple property sets are not supported. In fact, the reference
  151. implementation of property sets treats non-simple propvariant types like
  152. VT_STREAM as invalid types.
  153. ----------------------------
  154. 6) Using the reference implementation
  155. On the Windows platform, the code will compile into a dynamic link library
  156. (i.e. refstg.dll). To use the reference implementation, include 'storage.h'
  157. (for the storage interfaces) and ('props.h') for the property set interfaces
  158. to link up with the declarations. Note that only C++ headers are provided for
  159. this distribution.
  160. On UNIX, the code compiles into a library archive. i.e. "refstg.a". The
  161. headers should be included as in the Windows Platform. Please note that on
  162. certain UNIX machines, the standard headers declare 'wchar_t' as a 4-byte data
  163. type, which is incompatible with OLE's 2-byte character type. The reference
  164. implementation uses 'WCHAR' as the 2-byte character type, to avoid any
  165. confusion.
  166. NOTE: We have experience some problems when the g++ library, namely the
  167. fwrite() function on some versions of Linux overwrites memory in the wrong
  168. places. This can be avoided by using 'gcc' instead of 'g++' as the compiler.
  169. To turn off debugging code and do a 'retail' build, edit the makefiles (both
  170. in the root and in props sub-directory) and specify the relevant flags and do
  171. a clean build (see the makefiles for details).
  172. ----------------------------
  173. 7) Bug reports
  174. Please report any bugs found to :
  175. <insert name of contact person and procedure here>