StgOpenStorageEx function (coml2api.h)
The StgOpenStorageEx function opens an existing root storage object in the file system. Use this function to open Compound Files and regular files. To create a new file, use the StgCreateStorageEx function.
Syntax
HRESULT StgOpenStorageEx(
[in] const WCHAR *pwcsName,
[in] DWORD grfMode,
[in] DWORD stgfmt,
[in] DWORD grfAttrs,
[in, out] STGOPTIONS *pStgOptions,
[in] PSECURITY_DESCRIPTOR pSecurityDescriptor,
[in] REFIID riid,
[out] void **ppObjectOpen
);
Parameters
[in] pwcsName
A pointer to the path of the null-terminated Unicode string file that contains the storage object. This string size cannot exceed MAX_PATH characters.
Windows Server 2003 and Windows XP/2000: Unlike the CreateFile function, the MAX_PATH limit cannot be exceeded by using the "\?" prefix.
[in] grfMode
A value that specifies the access mode to open the new storage object. For more information, see STGM Constants. If the caller specifies transacted mode together with STGM_CREATE or STGM_CONVERT, the overwrite or conversion occurs when the commit operation is called for the root storage. If IStorage::Commit is not called for the root storage object, previous contents of the file will be restored. STGM_CREATE and STGM_CONVERT cannot be combined with the STGM_NOSNAPSHOT flag, because a snapshot copy is required when a file is overwritten or converted in transacted mode.
If the storage object is opened in direct mode (STGM_DIRECT) with access to either STGM_WRITE or STGM_READWRITE, the sharing mode must be STGM_SHARE_EXCLUSIVE unless the STGM_DIRECT_SWMR mode is specified. For more information, see the Remarks section. If the storage object is opened in direct mode with access to STGM_READ, the sharing mode must be either STGM_SHARE_EXCLUSIVE or STGM_SHARE_DENY_WRITE, unless STGM_PRIORITY or STGM_DIRECT_SWMR is specified. For more information, see the Remarks section.
The mode in which a file is opened can affect implementation performance. For more information, see Compound File Implementation Limits.
[in] stgfmt
A value that specifies the storage file format. For more information, see the STGFMT enumeration.
[in] grfAttrs
A value that depends upon the value of the stgfmt parameter.
STGFMT_DOCFILE must be zero (0) or FILE_FLAG_NO_BUFFERING. For more information about this value, see CreateFile. If the sector size of the file, specified in pStgOptions, is not an integer multiple of the physical sector size of the underlying disk, then this operation will fail. All other values of stgfmt must be zero.
[in, out] pStgOptions
A pointer to an STGOPTIONS structure that contains data about the storage object opened. The pStgOptions parameter is valid only if the stgfmt parameter is set to STGFMT_DOCFILE. The usVersion member must be set before calling StgOpenStorageEx. For more information, see the STGOPTIONS structure.
[in] pSecurityDescriptor
Reserved; must be zero.
[in] riid
A value that specifies the GUID of the interface pointer to return. Can also be the header-specified value for IID_IStorage to obtain the IStorage interface or for IID_IPropertySetStorage to obtain the IPropertySetStorage interface.
[out] ppObjectOpen
The address of an interface pointer variable that receives a pointer for an interface on the storage object opened; contains NULL if operation failed.
Return value
This function can also return any file system errors or system errors wrapped in an HRESULT. For more information, see Error Handling Strategies and Handling Unknown Errors.
Remarks
StgOpenStorageEx is a superset of the StgOpenStorage function, and should be used by new code. Future enhancements to structured storage will be exposed through this function. For more information about supported platforms, see the Requirements section.
The
StgOpenStorageEx function opens the specified root storage object according to the access mode in the grfMode parameter, and, if successful, supplies an interface pointer for the opened storage object in the ppObjectOpen parameter. This function can be used to obtain an IStorage compound file implementation, an IPropertySetStorage compound file implementation, or an
NTFS file system implementation of IPropertySetStorage.
When you open a file, the system selects a structured storage implementation depending on which STGFMT flag you specify on the file type and on the type of drive where the file is stored.
Use the StgOpenStorageEx function to access the root storage of a structured storage document or the property set storage of any file that supports property sets. For more information about which interface identifiers (IIDs) are supported for the different STGFMT values, see STGFMT.
When a file is opened with this function to access the NTFS property set implementation, special sharing rules apply. For more information, see IPropertySetStorage-NTFS Implementation.
If a compound file is opened in transacted mode, by specifying STGM_TRANSACTED, and read-only mode, by specifying STGM_READ, it is possible to change the returned storage object. For example, it is possible to call IStorage::CreateStream. However, it is not possible to commit those changes by calling IStorage::Commit. Therefore, such changes will be lost.
It is not valid to use the STGM_CREATE, STGM_DELETEONRELEASE, or STGM_CONVERT flags in the grfMode parameter for this function.
To support the simple mode for saving a storage object with no substorages, the StgOpenStorageEx function accepts one of the following two flag combinations as valid modes in the grfMode parameter:
STGM_SIMPLE | STGM_READWRITE | STGM_SHARE_EXCLUSIVE
STGM_SIMPLE | STGM_READ | STGM_SHARE_EXCLUSIVE
To support the single-writer, multireader, direct mode, the first flag combination is the valid grfMode parameter for the writer. The second flag combination is valid for readers.
STGM_DIRECT_SWMR | STGM_READWRITE | STGM_SHARE_DENY_WRITE
STGM_DIRECT_SWMR | STGM_READ | STGM_SHARE_DENY_NONE
For more information about simple mode and single-writer/multiple-reader modes, see STGM Constants.
Requirements
| Requirement | Value |
|---|---|
| Minimum supported client | Windows 2000 Professional [desktop apps | UWP apps] |
| Minimum supported server | Windows 2000 Server [desktop apps | UWP apps] |
| Target Platform | Windows |
| Header | coml2api.h (include Objbase.h) |
| Library | Ole32.lib |
| DLL | Ole32.dll |