StgCreateDocfile

Creates a new compound file storage object using the OLE-provided compound file implementation for the IStorage interface.

WINOLEAPI StgCreateDocfile(

const WCHAR * pwcsName,

//Points to pathname of compound file to create

DWORD grfMode,

//Specifies the access mode for opening the storage object

DWORD reserved,

//Reserved; must be zero

IStorage ** ppstgOpen

//Points to location for returning the new storage object

);

Parameters

pwcsName: [in] Points to the pathname 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.
reserved: [in] Reserved for future use; must be zero.
ppstgOpen: [out] Points to the location of the IStorage pointer to the new storage object.

Return Values

S_OK: Indicates the compound file was successfully created.
STG_E_ACCESSDENIED: Access denied because the caller has insufficient permission, or another caller has the file open and locked.
STG_E_LOCKVIOLATION: Access denied because another caller has the file open and locked.
STG_E_FILEALREADYEXISTS: Indicates the compound file already exists and grfMode is set to STGM_FAILIFTHERE.
STG_S_CONVERTED: Indicates the specified file was successfully converted to Storage format.
STG_E_INSUFFICIENTMEMORY: Indicates the compound file was not created due to a lack of memory.
STG_E_INVALIDNAME: Indicates bad name in the pwcsName parameter.
STG_E_INVALIDPOINTER: Indicates bad pointer in the pwcsName parameter or the ppStgOpen parameter.
STG_E_INVALIDFLAG: Indicates bad flag combination in the grfMode pointer.
STG_E_TOOMANYOPENFILES: Indicates the compound file was not created due to a lack of file handles.

See also any file system errors for other error return values.

Remarks

The StgCreateDocfile function creates a new storage object using the OLE-provided, compound-file implementation for the IStorage interface. The name of the open compound file can be retrieved by calling the IStorage::Stat method.

StgCreateDocfile 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. See the STGM enumeration for more information on these values.

If the compound file is opened in transacted mode (the grfMode parameter specifies STGM_TRANSACTED) and a file with this name already exists, the existing file is not altered until all outstanding changes are committed. If the calling process lacks write access 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 commit operation will fail (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. This can be used by 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 in 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.

StgCreateDocfile can be used 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 system-provided unique name likely one that is 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.

See Also

StgCreateDocFileOnILockBytes

const WCHAR * pwcsName,	//Points to pathname of compound file to create
DWORD grfMode,	//Specifies the access mode for opening the storage object
DWORD reserved,	//Reserved; must be zero
IStorage ** ppstgOpen	//Points to location for returning the new storage object
);