|
StgCreateDocfile
Creates a new storage object using the OLE-provided compound file
implementation for the IStorage interface.
HRESULT 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
Points to the pathname of the compound file to create. 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
Specifies the access mode to use when opening the new storage object. For more
information, see the STGM enumeration.
reserved
Reserved for future use; must be zero.
ppstgOpen
Points to the location where the new storage object is placed.
Return Values
S_OK
Indicates the compound file was successfully created.
STG_E_ACCESSDENIED
Indicates the calling process does not have sufficient access. Attempt to open
file with conflicting permissions to a simultaneous open.
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.
Comments
This 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.
The StgCreateDocfile function 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).
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.
The absence of STGM_TRANSACTED in the grfMode parameter indicates the file is to be created and opened in direct access
mode. Any existing file with the same name is destroyed before creating the new
file.
The StgCreateDocfile function 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.
Note By default, a Windows application can have 20 file handles open at one time.
Each storage object opened in transacted mode uses three file handles. To
increase the number of file handles the application has available, applications
often call the Windows SetHandleCount function. However, the SetHandleCount function affects C run-time libraries (those statically linked to the
application) that are hard-coded to expect only 20 file handles. There is no check on
overflow, so if the application already has a few compound files open and it
then uses a C run-time library (for example, fopen or sopen), the application corrupts memory past the end of the file-handle array (low
in its data segment) if the library gets a file handle above 20.
To solve this problem, applications should reserve some number of file handles
on start up, making them available to the components that might be based on C
run-time libraries. If your application does not use any dynamic link libraries
that use the C run-time libraries, there is no need for any special
file-handle reservation code.
See Also
StgCreateDocFileOnILockBytes
| Last news from Greatis Software |
 |
|
Nostalgia .Net |
|
.Net is powerful, but not all-powerful, so sometimes we need to use Win32 API for our .Net applications. It's simple enough with Platform Invoke if you have Win32 skill, but we do not always have time to dig the ancient documentation, declare the special types that are compatible with Win32, find the values of the Win32's constants and so on. Nostalgia .Net offers several simple-to-use classes, and components that will allow you to forget about the headache of Win32 and just use the power of Win32 in your application the same way as you use the native. Net classes. More » |
| Recommended software for developers |
 |
|
Ultimate Pack |
|
Component pack for Delphi and C++ Builder that contains runtime form designer, runtime object inspector, print suite and much more for the very special price. More » |
 |
|
Form Designer .Net |
|
Unique runtime form design solution that allows to edit any form in .Net WinForms application at runtime with full source codes for only 300 euro! More » |
 |
|
Print Suite .Net |
|
Print Suite .Net is a set of components for easy printing texts, images and grids from your WinForms applications. Full C# source codes are available More » |
 |
|
Gradient Controls .Net |
|
Gradient Controls .Net offers controls with gradient background feature. Labels, panels and so on... Full C# source codes are available More » |
 |
|
Greatis iGrid |
|
iGrid plots drawing grid right over your desktop, so you can use it everywhere, with any drawing application without any special plugins for different graphic editors. More » |
All the contacts and projectsDmitry Vasiliev (just.dmitry)
Related LinksSoftware for Visual Studio .NET developers
Software for Delphi and C++ Builder developers
Software for Visual Basic 6 developers
Delphi Tips&Tricks
MegaDetailed.NET More Online Helps Win32 Programmer's Reference
Win32 Multimedia Programmer's Reference
OLE Programmer's Reference
Microsoft Windows Pen API Programmer's Reference
Microsoft Windows Sockets 2 Reference
Microsoft Windows Telephony API (TAPI) Programmer's Reference
Unix Manual Pages
|
