StgOpenStorageOnILockBytes 函数 (coml2api.h)

  • 项目

StgOpenStorageOnILockBytes 函数会打开一个现有的存储对象，该对象不驻留在磁盘文件中，而是具有调用方提供的基础字节数组。

语法

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

参数

[in] plkbyt

指向基础字节数组对象的 ILockBytes 指针，该对象包含要打开的存储对象。

[in] pstgPriority

指向应为 NULL 的 IStorage 接口的指针。 如果不是 NULL，则使用此参数，如以下备注部分所述。

StgOpenStorageOnILockBytes 返回后，pStgPriority 中指定的存储对象可能已释放，不应再使用。

[in] grfMode

指定用于打开存储对象的访问模式。 有关详细信息，请参阅下面的 STGM 常量 和备注部分。

[in] snbExclude

可以为 NULL。 如果不是 NULL，则此参数指向此存储中的元素块，这些元素在打开存储对象时将被排除。 此排除的发生与快照复制是否在打开时发生无关。

[in] reserved

指示保留供将来使用;必须为零。

[out] ppstgOpen

指向成功返回时指向打开的存储的 IStorage 指针的位置。

返回值

StgOpenStorageOnILockBytes 函数还可以返回任何文件系统错误，或者包装在 HRESULT 或 ILockBytes 接口错误返回值中的系统错误。 请参阅 错误处理策略 和 处理未知错误。

注解

StgOpenStorageOnILockBytes 将打开指定的根存储对象。 指向打开的存储对象上的 IStorage 接口的指针通过 ppstgOpen 参数提供。

存储对象必须以前由 StgCreateDocfileOnILockBytes 函数创建。

除了指定程序员提供的字节数组对象外， StgOpenStorageOnILockBytes 类似于 StgOpenStorage 函数。 存储对象根据 grfMode 参数中的访问模式打开，但有以下限制：

共享模式行为和事务隔离取决于支持具有LOCK_ONLYONCE语义的 LockRegion 和 UnlockRegion 的 ILockBytes 实现。 实现可以通过在 STATSTG 的 grfLocksSupported 成员中设置LOCK_ONLYONCE位来指示它们支持此功能的结构化存储。 如果 ILockBytes 实现不支持此功能，则不会强制实施共享模式，并且根级事务提交将无法与在同一字节数组上打开的其他事务实例正确协调。 使用不支持区域锁定的 ILockBytes 实现（例如 CreateStreamOnHGlobal 实现）的应用程序应避免在同一字节数组上打开多个并发实例。

StgOpenStorageOnILockBytes 不支持简单模式。 忽略STGM_SIMPLE标志（如果存在）。

pStgPriority 参数旨在方便调用方将现有存储对象（通常是在优先级模式下打开的存储对象）替换为在同一字节数组上打开的新存储对象。 与 StgOpenStorage 的 pStgPriority 参数不同，此参数不会影响 StgOpenStorageOnILockBytes 执行的打开操作，只是调用方希望释放的现有存储对象。 调用方应始终为此参数传递 NULL ，因为 StgOpenStorageOnILockBytes 在某些情况下释放对象，而在其他情况下不会释放它。 调用方可以通过在调用 StgOpenStorageOnILockBytes 之前释放 对象，以更安全的方式复制 pStgPriority 参数的使用，如以下示例所示：

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

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

有关详细信息，请参阅 StgOpenStorage。

要求

要求 值
最低受支持的客户端 Windows 2000 专业版 [桌面应用 |UWP 应用]
最低受支持的服务器 Windows 2000 Server [桌面应用 |UWP 应用]
目标平台 Windows
标头 coml2api.h (包括 Objbase.h)
Library Ole32.lib
DLL Ole32.dll

另请参阅

StgCreateDocfileOnILockBytes

StgOpenStorage