[This is preliminary documentation and subject to change.]
Opens an existing root storage object in the file system. You can use this function to open compound files and regular files. Nested storage objects can only be opened using their parent's IStorage::OpenStorage method.
HRESULT StgOpenStorageEx(
const WCHAR * pwcsName, //Points to the path of the file
// containing storage object
DWORD grfMode, //Specifies the access mode for the object
STGFMT stgfmt, //Specifies the storage file format
DWORD grfAttrs, //Reserved; must be zero
void * reserved1, //Reserved; must be zero
void * reserved2, //Reserved; must be zero
REFIID riid, //Specifies the GUID of the interface pointer
void ** ppObjectOpen, //Address of an interface pointer
);
This function can also return any file system errors or Win32 errors wrapped in an HRESULT.
StgOpenStorageEx is a superset of the StgOpenStorage function, and should be used by new code. Future enhancements to Windows structured storage will be exposed through this function.
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.
When you open a file, the system selects a structured storage implementation depending on what STGFMT flag you specify and on what type of drive the file is stored. See the STGFMT documentation for more information.
You can use the StgOpenStorageEx function to get access to the root storage of a structured storage document, the contents stream of a flat file, or the property set storage of any file that supports property sets. For information about which interface identifiers (IIDs) are supported for the different STGFMT values, see the STGFMT enumeration.
To support the simple mode for saving a storage object with no substorages, the StgOpenStorageEx function accepts the following flag combinations as valid modes in the grfMode parameter: STGM_SIMPLE|STGM_READWRITE|STGM_SHARE_EXCLUSIVE and STGM_SIMPLE|STGM_READ|STGM_SHARE_EXCLUSIVE.
To support the Single-Writer/Multi-Reader Direct mode, the StgOpenStorageEx function accepts the following flag combinations as valid modes in the grfMode parameter: STGM_READWRITE|STGM_SHARE_DENY_WRITE and STGM_READ|STGM_SHARE_DENY_NONE.
Note Opening a storage object in read and/or write mode without denying writer permissions to others (the grfMode parameter specifies STGM_SHARE_DENY_WRITE) can be a time-consuming operation since the StgOpenStorageEx call must make a snapshot copy of the entire storage object.
Applications often try to open storage objects with the following access permissions:
STGM_READ_WRITE | STGM_SHARE_DENY_WRITE
// transacted vs. direct mode omitted for exposition
If the application succeeds, it never needs to make a snapshot copy. If it fails, the application can revert to using the permissions and make a snapshot copy:
STGM_READ_WRITE
// transacted vs. direct mode omitted for exposition
In this case, the application should prompt the user before doing a time-consuming copy. Alternatively, if the document sharing semantics implied by the access modes are appropriate, the application could try to open the storage as follows:
STGM_READ | STGM_SHARE_DENY_WRITE
// transacted vs. direct mode omitted for exposition
In this case, if the application succeeds, a snapshot copy will not have been made (because STGM_SHARE_DENY_WRITE was specified, denying others write access).
To reduce the expense of making a snapshot copy, applications can open storage objects in priority mode (grfMode specifies STGM_PRIORITY).
Windows NT: Use version 5.0 or later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in objbase.h.
IStorage, StgCreateDocfile, StgCreateStorageEx, StgOpenStorage