StgOpenStorageOnILockBytes
Opens an
existing storage object that does not reside in a disk file, but instead has an
underlying byte array provided by the caller.
WINOLEAPI StgOpenStorageOnILockBytes(
|
ILockBytes * plkbyt, |
//Points
to the ILockBytes interface on the underlying byte array |
|
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 |
//Points
to location for returning the storage object |
|
); |
|
Parameters
plkbyt
[in] ILockBytes
pointer to the underlying byte array object that contains the storage object to
be opened.
pStgPriority
[in] Most
often NULL. If not NULL, this parameter is used instead of the plkbyt
parameter to specify the storage object to open. In this case, it points to the
IStorage interface on a previously opened root storage object, most
often one that was opened in priority mode.
After the StgOpenStorageOnILockBytes
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] May be
NULL. 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. .
reserved
[in]
Indicates reserved for future use; must be zero.
ppstgOpen
[out] Points
to the location of an IStorage pointer to the opened storage on
successful return.
Return Values
S_OK
The storage
object was successfully opened.
STG_E_FILENOTFOUND
The specified
byte array 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
The byte
array exists but is not a storage object.
STG_E_TOOMANYOPENFILES
The storage
object was not opened because there are too many open files.
STG_E_INSUFFICIENTMEMORY
The storage
object was not opened due to a lack of memory.
STG_E_INVALIDNAME
Either pwcsName or snbExclude contains
an invalid name.
STG_E_INVALIDPOINTER
Either snbExclude,
pwcsName, pstgPriority, or ppStgOpen contains an invalid
pointer.
STG_E_INVALIDFLAG
The grfMode
parameter contains a bad flag combination.
STG_E_INVALIDFUNCTION
The access
mode STGM_DELETEONRELEASE was specified in the grfMode parameter.
STG_E_OLDDLL
The DLL being
used to open this storage object is a version prior to the one used to create
it.
STG_E_OLDFORMAT
The storage
object being opened was created by the Beta 1 storage provider. This format is
no longer supported.
File system
error return values.
ILockBytes interface error return values.
Remarks
StgOpenStorageOnILockBytes opens the specified root storage object. The storage
object is opened according to the access mode in the grfMode parameter;
a pointer to the IStorage interface on the opened storage object is supplied
through the ppstgOpen parameter.
The storage
object must have been previously created by the StgCreateDocfileOnILockBytes function.
Except for
specifying a programmer-provided byte-array object, StgOpenStorageOnILockBytes
is similar to the StgOpenStorage function. For more information, refer
to StgOpenStorage.
See Also