IStorage::OpenStorage

Opens an existing storage object with the specified name according to the specified access mode.

HRESULT OpenStorage(

const wchar_t * pwcsName,	//Points to the name of the storage object to open
IStorage * pstgPriority,	//Points to previous opening of the storage object
DWORD grfMode,	//Access mode for the new storage object
SNB snbExclude,	//Points to a block of stream names in the storage object
DWORD reserved,	//Reserved; must be zero
IStorage ** ppstg	//Points to opened storage object
);

Parameters
pwcsName

[in]Points to the name of the storage object to open. It is ignored if pstgPriority is non-NULL.

pstgPriority

[in]If the pstgPriority parameter is not NULL, it is a pointer to a previous opening of an element of the storage object, usually one that was opened in priority mode. The storage object should be closed and re-opened according to grfMode. When the IStorage::OpenStorage method returns, pstgPriority is no longer valid. Use the value returned in the ppstg parameter. If the pstgPriority parameter is NULL, it is ignored.

grfMode

[in]Specifies the access mode to use when opening the storage object. See the STGM enumeration values for descriptions of the possible values.

snbExclude

[in]Either NULL or a non-NULL value that points to a block of stream names in this storage object that are to be emptied as the object is opened. This exclusion happens independent of whether a snapshot copy happens on the open.

reserved

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

ppstg

[out]Points to the location where the IStorage interface pointer is returned; only valid if the operation is successful. This parameter is set to NULL if an error occurs.

Return Values
S_OK

The storage object was opened successfully.

STG_E_ACCESSDENIED

Insufficient permissions to open storage object.

STG_E_FILENOTFOUND

The storage object with the specified name does not exist.

STG_E_INSUFFICIENTMEMORY

The storage object was not opened due to a lack of memory.

STG_E_INVALIDFLAG

The value specified for the grfMode flag is not a valid STGM enumeration value.

STG_E_INVALIDFUNCTION

The specified combination of grfMode flags is not supported.

STG_E_INVALIDNAME

Invalid value for pwcsName.

STG_E_INVALIDPOINTER

The pointer specified for the storage object was invalid.

STG_E_INVALIDPARAMETER

One of the parameters was invalid.

STG_E_REVERTED

The object has been invalidated by a revert operation above it in the transaction tree.

STG_E_TOOMANYOPENFILES

The storage object was not created because there are too many open files.

STG_S_CONVERTED

The existing stream with the specified name was replaced with a new storage object containing a single stream called CONTENTS. The new storage object will be added.

Comments
Root storage objects can be opened with STGM_DELETEONRELEASE, in which case the object is destroyed when it receives its final release. This is useful for creating temporary storage objects.

Note to Callers
The OLE-provided compound file implementation of the IStorage::OpenStorage method does not support the following behaviors:

The STGM_PRIORITY flag is not supported for non-root storages.
Opening the same storage object more than once from the same parent storage is not supported. The STGM_SHARE_EXCLUSIVE flag must be specified.

Other implementations of IStorage might support these features.