StgOpenStorageOnILockBytes function (coml2api.h)

Article
10/13/2021

The StgOpenStorageOnILockBytes function opens an existing storage object that does not reside in a disk file, but instead has an underlying byte array provided by the caller.

Syntax

HRESULT StgOpenStorageOnILockBytes(
  [in]  ILockBytes *plkbyt,
  [in]  IStorage   *pstgPriority,
  [in]  DWORD      grfMode,
  [in]  SNB        snbExclude,
  [in]  DWORD      reserved,
  [out] IStorage   **ppstgOpen
);

Parameters

[in] plkbyt

ILockBytes pointer to the underlying byte array object that contains the storage object to be opened.

[in] pstgPriority

A pointer to the IStorage interface that should be NULL. If not NULL, this parameter is used as described below in the Remarks section.

After StgOpenStorageOnILockBytes returns, the storage object specified in pStgPriority may have been released and should no longer be used.

[in] grfMode

Specifies the access mode to use to open the storage object. For more information, see STGM Constants and the Remarks section below.

[in] snbExclude

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 independently of whether a snapshot copy happens on the open.

[in] reserved

Indicates reserved for future use; must be zero.

[out] ppstgOpen

Points to the location of an IStorage pointer to the opened storage on successful return.

Return value

The StgOpenStorageOnILockBytes function can also return any file system errors, or system errors wrapped in an HRESULT, or ILockBytes interface error return values. See Error Handling Strategies and Handling Unknown Errors.

Remarks

StgOpenStorageOnILockBytes opens the specified root storage object. 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. The storage object is opened according to the access modes in the grfMode parameter, subject to the following restrictions:

Sharing mode behavior and transactional isolation depend on the ILockBytes implementation supporting LockRegion and UnlockRegion with LOCK_ONLYONCE semantics. Implementations can indicate to structured storage they support this functionality by setting the LOCK_ONLYONCE bit in the grfLocksSupported member of STATSTG. If an ILockBytes implementation does not support this functionality, sharing modes will not be enforced, and root-level transactional commits will not coordinate properly with other transactional instances opened on the same byte array. Applications that use an ILockBytes implementation that does not support region locking, such as the CreateStreamOnHGlobal implementation, should avoid opening multiple concurrent instances on the same byte array.

StgOpenStorageOnILockBytes does not support simple mode. The STGM_SIMPLE flag, if present, is ignored.

The pStgPriority parameter is intended as a convenience for callers replacing an existing storage object, often one opened in priority mode, with a new storage object opened on the same byte array. Unlike the pStgPriority parameter of StgOpenStorage, this parameter does not affect the open operation performed by StgOpenStorageOnILockBytes and is simply an existing storage object the caller would like released. Callers should always pass NULL for this parameter because StgOpenStorageOnILockBytes releases the object under some circumstances, and does not release it under other circumstances. The use of the pStgPriority parameter can be duplicated by the caller in a safer manner by instead releasing the object before calling StgOpenStorageOnILockBytes, as shown in the following example:

// Replacement for:
// HRESULT hr = StgOpenStorageOnILockBytes(
//         plkbyt, pStgPriority, grfMode, NULL, 0, &amp;pstgNew);

pStgPriority-&gt;Release();
pStgPriority = NULL;
hr = StgOpenStorage(plkbyt, NULL, grfMode, NULL, 0, &amp;pstgNew);

For more information, refer to StgOpenStorage.

Requirements

Requirement	Value
Minimum supported client	Windows 2000 Professional [desktop apps \| UWP apps]
Minimum supported server	Windows 2000 Server [desktop apps \| UWP apps]
Target Platform	Windows
Header	coml2api.h (include Objbase.h)
Library	Ole32.lib
DLL	Ole32.dll