StgCreateDocfile
Creates a new
compound file storage object using the OLE-provided compound file
implementation for the IStorage
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
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
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
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
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