StgCreateDocfileOnILockBytes 函数 (coml2api.h)

  • 项目

StgCreateDocfileOnILockBytes 函数在调用方提供的字节数组对象之上创建并打开一个新的复合文件存储对象。 存储对象支持 COM 提供的 IStorage 接口复合文件实现。

语法

HRESULT StgCreateDocfileOnILockBytes(
  [in]  ILockBytes *plkbyt,
  [in]  DWORD      grfMode,
  [in]  DWORD      reserved,
  [out] IStorage   **ppstgOpen
);

参数

[in] plkbyt

指向要创建复合文件的基础字节数组对象上的 ILockBytes 接口的指针。

[in] grfMode

指定打开新的复合文件时要使用的访问模式。 有关详细信息，请参阅下面的 STGM 常量 和备注部分。

[in] reserved

留待将来使用；必须为零。

[out] ppstgOpen

指向新存储对象上 IStorage 指针位置的指针。

返回值

StgCreateDocfileOnILockBytes 函数还可以返回任何文件系统错误、包装在 HRESULT 中的系统错误或 ILockBytes 接口错误返回值。 有关详细信息，请参阅 错误处理策略 和 处理未知错误。

注解

StgCreateDocfileOnILockBytes 函数使用 IStorage 接口的 COM 提供的复合文件实现在字节数组对象之上创建存储对象。 StgCreateDocfileOnILockBytes 可用于将文档存储在任意数据存储中，例如内存或关系数据库。 字节数组 (pLkbyt 参数指示，该参数指向对象上的 ILockBytes 接口，) 用于基础存储来代替磁盘文件。

除了指定程序员提供的字节数组对象外， StgCreateDocfileOnILockBytes 类似于 StgCreateDocfile 函数。

根据 grfMode 参数中的访问模式打开新创建的复合文件，但存在以下限制：

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

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

出于转换目的，该文件被视为已存在。 因此，使用 STGM_FAILIFTHERE 值没有用，因为它会导致返回错误。 但是，STGM_CREATE和STGM_CONVERT仍然有用。

提供在字节数组对象上生成复合文件的功能，以支持将数据 (在 IStorage 和 IStream 树结构下) 位于非持久性空间中。 如果具有此功能，则没有任何内容可阻止存储在文件中的文档使用此功能。 例如，容器可能会执行此操作，以最大程度地减少采用 COM 对其文件格式的影响。 但是，建议 COM 文档对其自己的外部级别存储采用 IStorage 接口。 这中思路具有以下优势：

  • 文档的存储结构与其作为嵌入对象时的存储结构相同，从而减少了应用程序需要处理的情况数。
  • 可以编写工具来访问文档中的 OLE 嵌入和链接对象，而无需特别了解文档的文件格式。 此类工具的一个示例是复制实用工具，用于复制包含链接对象的容器中包含的所有文档。 此类复制实用工具需要访问包含的链接，以确定要复制的文件的范围。
  • IStorage 实现解决了如何将更改提交到文件的问题。 使用 ILockBytes 接口的应用程序必须自行处理这些问题。

要求

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

另请参阅

StgCreateDocfile