StgOpenStorage
Opens an
existing root storage object in the file system. You can use this function to
open compound files, but you cannot use it to open directories, files, or
summary catalogs. Nested storage objects can only be opened using their
parent's IStorage::OpenStorage method.
WINOLEAPI StgOpenStorage(
|
const WCHAR * pwcsName, |
//Points
to the pathname of the file containing storage object |
|
IStorage * pstgPriority, |
//Points
to a previous opening of a root storage object |
|
DWORD grfMode, |
//Specifies
the access mode for the object |
|
SNB snbExclude, |
//Points
to an SNB structure specifying elements to be excluded |
|
DWORD reserved, |
//Reserved;
must be zero |
|
IStorage ** ppstgOpen |
//Indirect
IStorage pointer to the storage object on return |
|
); |
|
Parameters
pwcsName
[in] Points
to the pathname of the storage object to open. This parameter is ignored if the
pStgPriority parameter is not NULL.
pstgPriority
[in] Most
often NULL. If not NULL, this parameter is used instead of the pwcsName
parameter to specify the pointer to the IStorage interface on the
storage object to open. It points to a previous opening of a root storage
object, most often one that was opened in priority mode.
After the StgOpenStorage
function returns, the storage object specified in the pStgPriority parameter
on function entry is invalid, and can no longer be used. Use the one specified
in the ppStgOpen parameter instead.
grfMode
[in]
Specifies the access mode to use to open the storage object.
snbExclude
[in] If not
NULL, this parameter points to a block of elements in this storage that are to
be excluded as the storage object is opened. This exclusion occurs independent
of whether a snapshot copy happens on the open. May be NULL.
reserved
[in]
Indicates reserved for future use; must be zero.
ppstgOpen
[out] Points
to the location of the IStorage pointer on the opened storage.
Return Values
S_OK
Indicates the
storage object was successfully opened.
STG_E_FILENOTFOUND
Indicates the
specified file does not exist.
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
file exists but is not a storage object.
STG_E_TOOMANYOPENFILES
Indicates the
storage object was not opened because there are too many open files.
STG_E_INSUFFICIENTMEMORY
Indicates the
storage object was not opened due to a lack of memory.
STG_E_INVALIDNAME
Indicates bad
name in the pwcsName parameter.
STG_E_INVALIDPOINTER
Indicates bad
pointer in one of the parameters: snbExclude, pwcsName, pstgPriority,
or ppStgOpen.
STG_E_INVALIDFLAG
Indicates bad
flag combination in the grfMode parameter.
STG_E_INVALIDFUNCTION
Indicates
STGM_DELETEONRELEASE specified in the grfMode parameter.
STG_E_OLDFORMAT
Indicates the
storage object being opened was created by the Beta 1 storage provider. This
format is no longer supported.
STG_E_OLDDLL
Indicates the
DLL being used to open this storage object is a version prior to the one used
to create it.
STG_E_PATHNOTFOUND
Specified
pathname does not exist.
Remarks
The StgOpenStorage
function opens the specified root storage object according to the access mode
in the grfMode parameter, and, if successful, supplies an IStorage
pointer to the opened storage object in the ppstgOpen parameter.
Note Opening a
storage object in read and/or write mode without denying writer permission to
others (the grfMode parameter specifies STGM_SHARE_DENY_WRITE) can be a
time-consuming operation since the StgOpenStorage call must make a snapshot
of the entire storage object.
Applications
will often try to open storage objects with the following access permissions:
STGM_READ_WRITE | STGM_SHARE_DENY_WRITE
//
transacted vs. direct mode omitted for exposition
If the
application succeeds, it will never need to do a snapshot copy. If it fails,
the application can revert to using the permissions and make a snapshot copy:
STGM_READ_WRITE
//
transacted vs. direct mode omitted for exposition
In this case,
the application should prompt the user before doing a time-consuming copy. Alternatively,
if the document sharing semantics implied by the access modes are appropriate,
the application could try to open the storage as follows:
STGM_READ | STGM_SHARE_DENY_WRITE
//
transacted vs. direct mode omitted for exposition
In this case,
if the application succeeds, a snapshot copy will not have been made (because
STGM_SHARE_DENY_WRITE was specified, denying others write access).
To reduce the
expense of making a snapshot copy, applications can open storage objects in
priority mode (grfMode specifies STGM_PRIORITY).
The snbExclude
parameter specifies a set of element names in this storage object that are to
be emptied as the storage object is opened: streams are set to a length of
zero; storage objects have all their elements removed. By excluding certain
streams, the expense of making a snapshot copy can be significantly reduced.
Almost always, this approach will be used after first opening the storage
object in priority mode, then completely reading the now-excluded elements into
memory. This earlier priority mode opening of the storage object should be
passed through the pstgPriority parameter to remove the exclusion
implied by priority mode. The calling application is responsible for rewriting
the contents of excluded items before committing. Thus, this technique is most
likely only useful to applications whose documents do not require constant
access to their storage objects while they are active.
See Also