home *** CD-ROM | disk | FTP | other *** search
/ Chip 1999 January / Chip_1999-01_cd.bin / zkuste / delphi / D / COMPDOCS.ZIP / CompDoc.txt < prev    next >
Text File  |  1998-01-06  |  5KB  |  104 lines
  1.  
  2.  
  3.                      Compound Documents v1.00
  4.                      ~~~~~~~~~~~~~~~~~~~~~~~~
  5.                        Robert R. Marsh, SJ
  6.                          rrm@sprynet.com
  7.                  http://home.sprynet.com/sprynet/rrm/
  8.  
  9.    Compound Documents, or OLE Structured Storage, provide an
  10.    ingenious and easy way to effectively create a full file-system
  11.    within a file. A compound document functions as a 'directory'
  12.    (or root storage in the lingo) which can contain 'sub-directories'
  13.    (aka storages) and/or 'files' (aka streams).
  14.    Compound documents also have the ability to automatically buffer
  15.    any changes until they are committed or rolled back.
  16.  
  17.    Unfortunately, the association with OLE/ActiveX keeps many Delphi
  18.    users away. But while the details can be messy there is no deep
  19.    difficulty. Some Delphi encapsulations of compound files are
  20.    already available but either cost big bucks or mirror the
  21.    underlying API too closely with all its arcane flags many of which
  22.    are mutually exclusive. The components presented here encapsulate
  23.    the OLE structured storage API in a what is, I hope, a Delphi-
  24.    friendly manner, free from all the OLE clutter. What's more they
  25.    work in all three versions of Delphi (see below for a caveat).
  26.  
  27.    A TRootStorage object corresponds to a physical file on disk.
  28.    Other TStorage objects correspond to sub-storages of a root
  29.    storage. Apart from their mode of construction both objects have
  30.    similar behavior. They have methods to manage the sub-storages
  31.    and streams they contain (CopyElement, MoveElement, RenameElement,
  32.    DeleteElement, CopyTo, ListStorages, ListStreams) and methods to
  33.    handle transaction processing (Commit, Revert).
  34.  
  35.    TStorageStream objects always belong to a parent storage object.
  36.    They are fully compatible with Delphi's other stream objects.
  37.    Despite the impression given in many descriptions transaction
  38.    processing does not work at the stream level but only for storages.
  39.  
  40.    Transaction processing operates by publishing any changes visible
  41.    at one level in the storage hierarchy to the parent level. A
  42.    storage has no knowledge of changes made at a deeper level until
  43.    they percolate upwards through a series of Commit operations.
  44.    When a root storage commits its changes they are written to the
  45.    physical file.
  46.  
  47.    Both storages and streams can be created as temporary objects by
  48.    providing no Name parameter. A unique name is generated by Windows
  49.    and is available through the Name property. Such objects are self-
  50.    deleting.
  51.  
  52.    The OLE documentation warns that compound files are optimized
  53.    for common operations (like the reading and writing of streams)
  54.    and that other operations (especially those involving the
  55.    enumeration of storage elements) can be slow. Although I have
  56.    provided some enumeration methods (ListStorages, ListStreams) you
  57.    will get better performance if you create a separate stream to
  58.    store such information for yourself. In general, I have found
  59.    read/write operations to be about 2 to 3 times slower than
  60.    equivalent operations on 'ordinary' file streams. Not bad
  61.    considering the extra functionality.
  62.  
  63.    You can find out more about Compound Documents / OLE Structured
  64.    Storage from the excellent book "Inside OLE" (2nd ed.) by Kraig
  65.    Brockschmidt (Microsoft Press) or from the Microsoft Developers
  66.    Network library (via http://microsoft.com/msdn/). Good luck!
  67.  
  68.    One of the benefits of these components is that someone has read
  69.    the small print for you and made many illegal operations
  70.    impossible. I realize, however, that I have probably misread in
  71.    some cases. So if you find problems with this code please let me
  72.    know at the address above so that I can learn from my mistakes.
  73.  
  74.    I referred above to a caveat regarding the use of these components
  75.    with Delphi 1. There are two issues. First, as I understand it, OLE2
  76.    came on the scene after Windows 3.1 so that plain vanilla
  77.    installations don't include the necessary OLE dlls. Nevertheless,
  78.    it would be rare to find a machine that hasn't had the OLE2 files
  79.    added by one application or another. The second issue has more to
  80.    do with Borland. The OLE2 DCU and PAS files they supplied with D1
  81.    seem to be contain errors (even on the D2 and D3 CDs). I have taken
  82.    the liberty of correcting the problems which pertain to Compound
  83.    Documents and also changed some of the flag declaration to bring them
  84.    more into line with D2 and D3. The result is a file called OLE2_16
  85.    which must be used with CompDoc.DCU under Delphi 1. Other versions
  86.    of Delphi can ignore this file.
  87.  
  88.    If you like these components and find yourself using them please
  89.    consider making a donation to your favorite charity. I would also
  90.    be pleased if you would make acknowledgement in any projects that
  91.    make use of them.
  92.  
  93.    These components are supplied as is. The author disclaims all
  94.    warranties, expressed or implied, including, without limitation,
  95.    the warranties of merchantability and of fitness for any purpose.
  96.    The author assumes no liability for damages, direct or
  97.    consequential, which may result from their use.
  98.  
  99.            Copyright (c) 1998 Robert R. Marsh, S.J. &
  100.           the British Province of the Society of Jesus
  101.  
  102. Robert R. Marsh, S.J.
  103. January 6, 1998
  104.