Author
Topic: About Structured Storage (Read 10812 times)

COM provides a set of services collectively called structured storage. Among the benefits of these services is the reduction of performance penalties and overhead associated with storing separate objects in a flat file. Instead of a flat file, COM stores the separate objects in a single, structured file consisting of two main elements: storage objects and stream objects. Together, they function like a file system within a file.

Structured storage solves performance problems by eliminating the need to totally rewrite a file to storage whenever a new object is added to a compound file, or an existing object increases in size. The new data is written to the next available location in permanent storage, and the storage object updates the table of pointers it maintains to track the locations of its storage objects and stream objects. At the same time, structured storage enables end users to interact and manage a compound file as if it were a single file rather than a nested hierarchy of separate objects.

Structured storage also has other benefits:

Incremental access. If a user needs access to an object within a compound file, the user can load and save only that object, rather than the entire file.

Multiple use. More than one end user or application can concurrently read and write information in the same compound file.

Transaction processing. Users can read or write to COM compound files in transacted mode, where changes made to the file are buffered and can subsequently either be committed to the file or reversed.

The following example Creates a property set, writes a property, closes and reopens the property set, and reads back the property. This sample application creates the file "WriteRead.stg" in the current directory. It creates property sets in a structure storage file, but a one-line change causes it to create NTFS file system property sets.

// Close and reopen everything. // By using the STGFMT_ANY flag in the StgOpenStorageEx call, // it does not matter if this is a Structured Storage // property set or an NTFS file system property set // (for more information see the StgCreateStorageEx // call above).

IF hr = %S_FALSE THEN MSGBOX "Property didn't exist after reopening the property set" ELSEIF propvarWrite.vt <> propvarRead.vt THEN MSGBOX "Property types didn't match after reopening the property set" ELSE ' If valid pointer... IF propvarRead.pwszVal THEN ' Get the length of the Unicode string bstrlen = lstrlenW(BYVAL propvarRead.pwszVal) IF bstrlen THEN ' Peek bstrlen * 2 bytes (Unicode is a two-byte encoding) strText = ACODE$(PEEK$(propvarRead.pwszVal, bstrlen * 2)) MSGBOX strText END IF END IF END IF

' Clear the PROPVARIANT PropVariantClear propvarRead

' ------------------------------------------------------------ ' Not included in the C++ example ' Retrieves the name for the %PID_DICTIONARY property ' ------------------------------------------------------------ LOCAL pName AS DWORD LOCAL buffer AS STRING

hr = pPropStg.ReadPropertyNames(1, propidDictionary, pName) IF SUCCEEDED(hr) THEN IF pName THEN bstrlen = lstrlenW(BYVAL pName) IF ISTRUE bstrlen THEN buffer = PEEK$(pName, bstrlen * 2) MSGBOX ACODE$(buffer) END IF ' Free the string CoTaskMemFree pName END IF END IF ' ------------------------------------------------------------

' Cleanup pPropSetStg = NOTHING pPropStg = NOTHING

END FUNCTION' ========================================================================================

' ########################################################################################' Demonstrates how to enumerate the streams contained in an storage compound file.' ########################################################################################

LOCAL hr AS LONG LOCAL pStorage AS IStorage LOCAL pEnum AS IEnumSTATSTG LOCAL pceltFetched AS DWORD LOCAL tStatStg AS STATSTG LOCAL wszName AS STRING LOCAL bstrlen AS LONG LOCAL strName AS STRING LOCAL strText AS STRING

' ########################################################################################' Demonstrates how to enumerate the properties stored in a property set storage file.' ########################################################################################

LOCAL hr AS LONG LOCAL pPropSetStg AS IPropertySetStorage LOCAL pPropStg AS IPropertyStorage LOCAL pEnum AS IEnumSTATPROPSTG LOCAL pceltFetched AS DWORD LOCAL tStatPropStg AS STATPROPSTG LOCAL wszName AS STRING LOCAL bstrlen AS LONG LOCAL strName AS STRING LOCAL strText AS STRING

' ########################################################################################' Demonstrates how to enumerate the property sets stored in a property set storage file.' The returned FMTID is a guid used in the IPropertySetStorage.Open function.' ########################################################################################

LOCAL hr AS LONG LOCAL pPropSetStg AS IPropertySetStorage LOCAL pEnum AS IEnumSTATPROPSETSTG LOCAL pceltFetched AS DWORD LOCAL tStatPropSetStg AS STATPROPSETSTG LOCAL wszName AS STRING LOCAL strText AS STRING

' ########################################################################################' Opens an excel file and retrieves some information about the Workbook.' ########################################################################################