[This is preliminary documentation and subject to change.]
Creates a new compound-file, storage object using the COM-provided compound file implementation for the IStorage interface.
HRESULT StgCreateStorageEx(
const WCHAR * pwcsName, //Points to path of compound file to
// create
DWORD grfMode, //Specifies the access mode for opening the
// storage 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.
StgCreateStorageEx is a superset of the StgCreateDocfile function, and should be used by new code. Future enhancements to structured storage will be exposed through this function.
The StgCreateStorageEx function creates a new storage object using one of the system-provided, structured storage implementations. The name of the open compound file can be retrieved by calling the IStorage::Stat method.
When a new file is created, the storage implementation used depends on what STGFMT flag you specify and what type of drive the file is stored on. For more information, see the STGFMT enumeration.
StgCreateStorageEx creates the file if it does not exist. If it does exist, the use of the STGM_CREATE, STGM_CONVERT, and STGM_FAILIFTHERE flags in the grfMode parameter indicate how to proceed. For more information on these values, see the STGM enumeration.
You can use the StgCreateStorageEx function to get access to the root storage of a structured storage document, the content stream of a flat file, or the property set storage of any file that supports property sets. See the STGFMT documentation for information about which IIDs are supported for the different STGFMT values. For information on the interfaces supported by each STGFMT value, see the STGM enumeration.
When you create a file using the STGFMT_FILE flag, the native property set implementation is used for any property sets. When you use the STGFMT_DOCFILE flag, the compound-file, property-set implementation is used. When you use the STGFMT_STORAGE flag, the NTFS, structured-storage, property-set implementation is used.
If the calling process lacks write permissions to the existing file (because of access control in the file system), the grfMode parameter can only specify STGM_READ and not STGM_WRITE or STGM_READWRITE. The resulting new open compound file can still be written to, but a subsequent commit operation fails (in transacted mode, write permissions are enforced at commit time).
Specifying STGM_SIMPLE provides a much faster implementation of a compound file object in a limited, but frequently-used case involving applications that require a compound file implementation with multiple streams and no storages. The simple mode does not support all of the methods on IStorage. For more information, refer to the STGM enumeration.
If the grfMode parameter specifies STGM_TRANSACTED and no file yet exists with the name specified by the pwcsName parameter, the file is created immediately. In an access-controlled file system, the caller must have write permissions for the file system directory in which the compound file is created. If STGM_TRANSACTED is not specified, and STGM_CREATE is specified, an existing file with the same name is destroyed before creating the new file.
You can also use StgCreateStorageEx to create a temporary compound file by passing a NULL value for the pwcsName parameter. However, these files are temporary only in the sense that they have a unique system-provided name – one that is probably meaningless to the user. The caller is responsible for deleting the temporary file when finished with it, unless STGM_DELETEONRELEASE was specified for the grfMode parameter.
Windows NT: Use version 5.0 or later.
Windows: Unsupported.
Windows CE: Unsupported.
Header: Declared in objbase.h.
Import Library: Included as a resource in ole32.dll.
StgCreateDocFileOnILockBytes ; StgCreateDocfile, STGM, STGFMT