stgOpenStorageEx 函数 (coml2api.h)

项目
02/24/2024

StgOpenStorageEx 函数打开文件系统中的现有根存储对象。使用此函数可打开复合文件和常规文件。若要创建新文件，请使用 StgCreateStorageEx 函数。

注意若要使用增强功能，所有 Windows 2000、Windows XP 和 Windows Server 2003 应用程序都应调用 StgOpenStorageEx，而不是 StgOpenStorage。 StgOpenStorage 函数用于与 Windows 2000 及更早版本的应用程序兼容。

语法

HRESULT StgOpenStorageEx(
  [in]      const WCHAR          *pwcsName,
  [in]      DWORD                grfMode,
  [in]      DWORD                stgfmt,
  [in]      DWORD                grfAttrs,
  [in, out] STGOPTIONS           *pStgOptions,
  [in]      PSECURITY_DESCRIPTOR pSecurityDescriptor,
  [in]      REFIID               riid,
  [out]     void                 **ppObjectOpen
);

参数

[in] pwcsName

指向包含存储对象的以 null 结尾的 Unicode 字符串文件的路径的指针。此字符串大小不能超过 MAX_PATH 个字符。

Windows Server 2003 和 Windows XP/2000： 与 CreateFile 函数不同，使用“\？”前缀不能超过 MAX_PATH 限制。

[in] grfMode

一个值，该值指定用于打开新存储对象的访问模式。有关详细信息，请参阅 STGM 常量。如果调用方指定事务处理模式以及 STGM_CREATE 或 STGM_CONVERT，则当为根存储调用提交操作时，将发生覆盖或转换。如果未为根存储对象调用 IStorage：：Commit ，则将还原文件的先前内容。 STGM_CREATE和STGM_CONVERT不能与 STGM_NOSNAPSHOT 标志结合使用，因为在事务处理模式下覆盖或转换文件时，需要快照副本。

如果存储对象以直接模式打开， (STGM_DIRECT) 访问 STGM_WRITE 或 STGM_READWRITE，则必须 STGM_SHARE_EXCLUSIVE 共享模式，除非指定 了STGM_DIRECT_SWMR 模式。有关详细信息，请参见“备注”部分。如果存储对象在直接模式下打开，并且可访问 STGM_READ，则共享模式必须是 STGM_SHARE_EXCLUSIVE 或 STGM_SHARE_DENY_WRITE，除非指定 了STGM_PRIORITY 或 STGM_DIRECT_SWMR 。有关详细信息，请参见“备注”部分。

打开文件的模式可能会影响实现性能。有关详细信息，请参阅复合文件实现限制。

[in] stgfmt

一个指定存储文件格式的值。有关详细信息，请参阅 STGFMT 枚举。

[in] grfAttrs

一个值，该值依赖于 stgfmt 参数的值。

STGFMT_DOCFILE 必须为零 (0) 或 FILE_FLAG_NO_BUFFERING。有关此值的详细信息，请参阅 CreateFile。如果 pStgOptions 中指定的文件的扇区大小不是基础磁盘物理扇区大小的整数倍，则此操作将失败。 stgfmt 的所有其他值必须为零。

[in, out] pStgOptions

指向 STGOPTIONS 结构的指针，该结构包含有关打开的存储对象的数据。仅当 stgfmt 参数设置为 STGFMT_DOCFILE 时，pStgOptions 参数才有效。在调用 StgOpenStorageEx 之前，必须设置 usVersion 成员。有关详细信息，请参阅 STGOPTIONS 结构。

[in] pSecurityDescriptor

保留;必须为零。

[in] riid

一个值，该值指定要返回的接口指针的 GUID。也可以是IID_IStorage获取 IStorage 接口或获取 IPropertySetStorage 接口的IID_IPropertySetStorage标头指定的值。

[out] ppObjectOpen

接口指针变量的地址，该变量接收打开的存储对象上的接口的指针;如果操作失败，则包含 NULL 。

返回值

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

注解

StgOpenStorageEx 是 StgOpenStorage 函数的超集，应由新代码使用。结构化存储的未来增强功能将通过此函数公开。有关支持的平台的详细信息，请参阅要求部分。

StgOpenStorageEx 函数根据 grfMode 参数中的访问模式打开指定的根存储对象，如果成功，将在 ppObjectOpen 参数中为打开的存储对象提供接口指针。此函数可用于获取 IStorage 复合文件实现、 IPropertySetStorage 复合文件实现或
IPropertySetStorage 的 NTFS 文件系统实现。

打开文件时，系统会根据你在文件类型和存储文件的驱动器类型上指定的 STGFMT 标志选择结构化存储实现。

使用 StgOpenStorageEx 函数访问结构化存储文档的根存储或支持属性集的任何文件的属性集存储。有关不同 STGFMT 值支持哪些接口标识符 (IID) ，请参阅 STGFMT。

使用此函数打开文件以访问 NTFS 属性集实现时，将应用特殊共享规则。有关详细信息，请参阅 IPropertySetStorage-NTFS 实现。

如果在事务处理模式下打开复合文件（通过指定STGM_TRANSACTED模式）和只读模式（通过指定STGM_READ），可以更改返回的存储对象。例如，可以调用 IStorage：：CreateStream。但是，无法通过调用 IStorage：：Commit 来提交这些更改。因此，此类更改将丢失。

在此函数的 grfMode 参数中使用STGM_CREATE、STGM_DELETEONRELEASE或STGM_CONVERT标志无效。

为了支持保存不带子存储的存储对象的简单模式， StgOpenStorageEx 函数接受以下两个标志组合之一作为 grfMode 参数中的有效模式：

    STGM_SIMPLE | STGM_READWRITE | STGM_SHARE_EXCLUSIVE

    STGM_SIMPLE | STGM_READ | STGM_SHARE_EXCLUSIVE

为了支持单编写器、多读取器、直接模式，第一个标志组合是编写器的有效 grfMode 参数。第二个标志组合对读取器有效。

    STGM_DIRECT_SWMR | STGM_READWRITE | STGM_SHARE_DENY_WRITE

    STGM_DIRECT_SWMR | STGM_READ | STGM_SHARE_DENY_NONE

有关简单模式和单编写器/多读取器模式的详细信息，请参阅 STGM 常量。

注意例如，grfMode 参数指定STGM_SHARE_DENY_WRITE) 可能很耗时，因为 StgOpenStorageEx 调用必须创建整个存储对象的快照副本，因此在读取和/或写入模式下打开事务模式存储对象而不拒绝 (对其他人的写入权限。

要求

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