IStorage-Compound File Implementation
The compound file implementation of IStorage allows you to create and manage substorages and streams within a storage object residing in a compound file object. To create a compound file object and get an IStorage pointer, call the API function StgCreateStorageEx. To open an existing compound file object and get its root IStorage pointer, call StgOpenStorageEx.
Applications that use compound storage should be registered in HKEY_CLASSES_ROOT\SystemFileAssociations and should provide their own property handlers. For more information, see the "Registering Verbs and Other File Association Information" section of Application Registration.
When to Use
Most applications use this implementation to create and manage storages and streams.
Methods
-
Creates and opens a stream object with the specified name contained in this storage object. The name must not exceed 31 characters in length (not including the string terminator). The 000 through 01f characters, serving as the first character of the stream/storage name, are reserved for use by OLE. This is a compound file restriction, not a structured storage restriction. The COM-provided compound file implementation of the IStorage::CreateStream method does not support the following behaviors:
- The STGM_DELETEONRELEASE flag is not supported.
- Transacted mode (STGM_TRANSACTED) is not supported for stream objects.
- Opening the same stream more than once from the same storage is not supported. The STGM_SHARE_EXCLUSIVE sharing-mode flag must be specified in the grfMode parameter.
-
Opens an existing stream object within this storage object using the access modes specified in the grfMode parameter. The 000 through 01f characters, serving as the first character of the stream/storage name, are reserved for use by OLE. This is a compound file restriction, not a structured storage restriction. The COM-provided compound file implementation of the IStorage::OpenStream method does not support the following behavior:
- The STGM_DELETEONRELEASE flag.
- Transacted mode (STGM_TRANSACTED) for stream objects.
- Opening the same stream more than once from the same storage. The STGM_SHARE_EXCLUSIVE flag must be specified.
-
Creates and opens a new storage object with the specified name in the specified access mode. The name must not exceed 31 characters in length (not including the string terminator). The 000 through 01f characters, serving as the first character of the stream/storage name, are reserved for use by OLE. This is a compound file restriction, not a structured storage restriction. The COM-provided compound file implementation of the IStorage::CreateStorage method does not support the following behavior:
- The STGM_PRIORITY flag for nonroot storages.
- Opening the same storage object more than once from the same parent storage. The STGM_SHARE_EXCLUSIVE flag must be specified.
- The STGM_DELETEONRELEASE flag. If this flag is specified, the function returns STG_E_INVALIDFLAG.
-
Opens an existing storage object with the specified name in the specified access mode. The 000 through 01f characters, serving as the first character of the stream/storage name, are reserved for use by OLE. This is a compound file restriction, not a structured storage restriction. The COM-provided compound file implementation of the IStorage::OpenStorage method does not support the following behavior:
- The STGM_PRIORITY flag for nonroot storages.
- Opening the same storage object more than once from the same parent storage. The STGM_SHARE_EXCLUSIVE flag must be specified.
- The STGM_DELETEONRELEASE flag. If this flag is specified, the function returns STG_E_INVALIDFUNCTION.
-
Copies only the substorages and streams of this open storage object into another storage object. The rgiidExclude parameter can be set to IID_IStream to copy only substorages, or to IID_IStorage to copy only streams.
-
Copies or moves a substorage or stream from this storage object to another storage object.
-
Ensures that any changes made to a storage object open in transacted mode are reflected in the parent storage; for a root storage, reflects the changes in the actual device; for example, a file on disk. For a root storage object opened in direct mode, this method has no effect except to flush all memory buffers to the disk. For nonroot storage objects in direct mode, this method has no effect.
The COM-provided compound files implementation uses a two-phase commit process unless STGC_OVERWRITE is specified in the grfCommitFlags parameter. This two-phase process ensures the robustness of data, in case the commit operation fails. First, all new data is written to unused space in the underlying file. If necessary, new space is allocated to the file. After this step has been completed, a table in the file is updated using a single-sector write operation to indicate that the new data is to be used in place of the old. The old data becomes free space to be used at the next commit operation. Thus, the old data is available and can be restored if an error occurs when committing changes. If STGC_OVERWRITE is specified, a single phase commit operation is used. For more information about transacted mode flags, see STGC enumeration.
-
Discards all changes that have been made to the storage object since the last commit operation.
-
Creates and retrieves a pointer to an enumerator object that can be used to enumerate the storage and stream objects contained within this storage object. The COM-provided compound file implementation takes a snapshot of that information. Therefore, changes to the streams and storages are not reflected in the enumerator until a new enumerator is obtained.
-
Removes the specified element (substorage or stream) from this storage object.
-
Renames the specified substorage or stream in this storage object. The 000 through 01f characters, serving as the first character of the stream/storage name, are reserved for use by OLE. This is a compound file restriction, not a structured storage restriction.
-
Sets the modification, access, and creation times of the specified storage element. The COM-provided compound-file implementation maintains modification and change times for internal storage objects. Root storage objects support whatever is supported by the underlying file system (or by ILockBytes). The compound file implementation does not maintain any time stamps for internal streams. Unsupported time stamps are reported as zero, which allows the caller to test for support.
-
Assigns the specified CLSID to this storage object.
-
Stores up to 32 bits of state information in this storage object. The state set by this method is for external use only. The COM-provided compound file implementation does not perform any action based on the state.
-
Retrieves the STATSTG structure for this open storage object.
Remarks
If the storage object is opened in simple mode, use of the above methods is restricted. A storage is in simple mode if it is opened with the STGM_SIMPLE element specified in the grfMode parameter of the StgCreateStorageEx or StgOpenStorageEx function. For more information about simple-mode storages, see STGM Constants. If the simple-mode storage object was obtained from the StgCreateStorageEx function, then the CreateStream method can be called but the OpenStream method cannot. If the simple mode storage object was obtained from the StgOpenStorageEx function, then the OpenStream method can be called but the CreateStream method cannot.
When a simple-mode storage object is used to create a stream, the minimum size of that stream typically is 4096 bytes. If less data is written to the stream, the size is rounded up to 4096 bytes.
Related topics
Feedback
Coming soon: Throughout 2024 we will be phasing out GitHub Issues as the feedback mechanism for content and replacing it with a new feedback system. For more information see: https://aka.ms/ContentUserFeedback.
Submit and view feedback for