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] Can 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_SHAREVIOLATION

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.

This function can also return any file system errors, or Win32 errors wrapped in an HRESULT, or 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.

Windows CE: The StgCreateDocfileOnILockBytes and StgOpenStorageOnILockBytes functions are not available for the non-desktop compatible implementation via CESYSGEN.

Passing into this function any invalid and, under some circumstances, NULL pointers will result in unexpected termination of the application. For more information about handling exceptions, see Programming Considerations.

QuickInfo

  Windows NT: Use version 3.1 or later.
  Windows: Use Windows 95 or later.
  Windows CE: Use version 2.0 or later.
  Header: Declared in objbase.h.
  Import Library: Use ole32.lib.

See Also

StgOpenStorage, StgCreateDocfileOnILockBytes