StgCreateStorageEx

[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
);
 

Parameters

pwcsName

[in] Points to the path of the compound file to create. It is passed uninterpreted to the file system. This can be a relative name or NULL. If NULL, a temporary compound file is allocated with a unique name.

grfMode

[in] Specifies the access mode to use when opening the new storage object. For more information, see the STGM enumeration. If the caller specifies transacted mode together with STGM_CREATE or STGM_CONVERT, the overwrite or conversion takes place at the time the storage object is opened and therefore is not revertible.

stgfmt

[in] Specifies the storage file format. For more information, see the STGFMT enumeration.

grfAttrs

[in] Reserved for future use; must be zero.

reserved1

[in] Reserved for future use; must be zero.

reserved2

[in] Reserved for future use; must be zero.

riid

[in] Specifies the GUID of the interface pointer to return.

ppObjectOpen

[out] Address of an interface pointer variable that receives a pointer for an interface on the new storage object; contains NULL if operation failed.

Return Values

S_OK

Indicates the compound file was successfully created.

STG_E_INVALIDPOINTER

Indicates a bad pointer in the ppObjectOpen parameter.

STG_E_INVALIDPARAMETER

Indicates an invalid value for the grfAttrs, reserved1, reserved2, grfMode, or stgfmt parameters.

STG_E_INVALIDFLAG

Indicates a bad flag combination in the grfMode pointer.

STG_E_INVALIDNAME

Indicates a bad name in the pwcsName parameter.

STG_E_FILEALREADYEXISTS

Indicates the compound file already exists and grfMode is set to STGM_FAILIFTHERE.

STG_E_LOCKVIOLATION

Access denied because another caller has the file open and locked.

STG_E_SHAREVIOLATION

Access denied because another caller has the file open and locked.

STG_E_NOTIMPL

Indicates the StgCreateStorageEx function is not implemented by the operating system. In this case, use the StgCreateDocfile function.

This function can also return any file system errors or Win32 errors wrapped in an HRESULT.

Remarks

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.

QuickInfo

  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.

See Also

StgCreateDocFileOnILockBytes ; StgCreateDocfile, STGM, STGFMT