StgCreateStorageEx 函数 (coml2api.h)

项目
08/22/2023

StgCreateStorageEx 函数使用为 IStorage 或 IPropertySetStorage 接口提供的实现创建新的存储对象。若要打开现有文件，请改用 StgOpenStorageEx 函数。

为 Windows 2000、Windows Server 2003 和 Windows XP 编写的应用程序必须使用 StgCreateStorageEx 而不是 StgCreateDocfile 来利用增强的 Windows 2000 和 Windows XP 结构化存储功能。

语法

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

参数

[in] pwcsName

指向要创建的文件的路径的指针。它未解释地传递到文件系统。这可以是相对名称或 NULL。如果 为 NULL，则分配具有唯一名称的临时文件。如果不是 NULL，则字符串大小不能超过MAX_PATH个字符。

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

[in] grfMode

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

[in] stgfmt

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

[in] grfAttrs

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

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

[in] pStgOptions

仅当 stgfmt 参数设置为 STGFMT_DOCFILE 时，pStgOptions 参数才有效。如果 stgfmt 参数设置为 STGFMT_DOCFILE， 则 pStgOptions 指向 STGOPTIONS 结构，该结构指定存储对象的功能，例如扇区大小。此参数可以为 NULL，这将创建默认扇区大小为 512 字节的存储对象。如果不是 NULL，则必须将 ulSectorSize 成员设置为 512 或 4096。如果设置为 4096，则可能不会在 grfMode 参数中指定STGM_SIMPLE。在调用 StgCreateStorageEx 之前，必须设置 usVersion 成员。有关详细信息，请参阅 STGOPTIONS。

[in] pSecurityDescriptor

启用在创建文件时设置 ACL。如果不是 NULL，则需要是指向 SECURITY_ATTRIBUTES 结构的指针。有关如何在文件上设置 ACL 的信息，请参阅 CreateFile 。

Windows Server 2003、Windows 2000 Server、Windows XP 和 Windows 2000 Professional： 值必须为 NULL。

[in] riid

一个值，该值指定要返回的接口指针 (IID) 接口标识符。此 IID 可能适用于 IStorage 接口或 IPropertySetStorage 接口。

[out] ppObjectOpen

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

返回值

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

备注

当应用程序修改其文件时，它通常会创建原始文件的副本。 StgCreateStorageEx 函数是创建副本的一种方式。此函数间接使用加密文件系统 (EFS) 重复 API。使用此函数时，需要在 STGOPTIONS 结构中设置文件存储的选项。

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

StgCreateStorageEx 函数使用系统提供的结构化存储实现之一创建新的存储对象。此函数可用于获取
IStorage 复合文件实现、 IPropertySetStorage 复合文件实现或获取 IPropertySetStorage NTFS 实现。

创建新文件时，使用的存储实现取决于指定的标志和存储文件的驱动器类型。有关详细信息，请参阅 STGFMT 枚举。

StgCreateStorageEx 创建文件（如果该文件不存在）。如果它确实存在，则在 grfMode 参数中使用STGM_CREATE、STGM_CONVERT和STGM_FAILIFTHERE标志指示如何继续操作。有关这些值的详细信息，请参阅 STGM 常量。在直接模式下，在 grfMode 参数中指定STGM_READ模式是无效的， (直接模式是通过不指定STGM_TRANSACTED标志) 来指示的。此函数不能用于打开现有文件;请改用 StgOpenStorageEx 函数。

可以使用 StgCreateStorageEx 函数访问结构化存储文档的根存储或支持属性集的任何文件的属性集存储。有关不同 STGFMT 值支持哪些 IID 的信息，请参阅 STGFMT 文档。

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

如果通过指定STGM_READ) STGM_TRANSACTED) 模式和只读模式 ( (事务模式创建复合文件，则有可能对返回的存储对象进行更改。例如，可以调用 IStorage：：CreateStream。但是，无法通过调用 IStorage：：Commit 提交这些更改。因此，此类更改将丢失。

指定STGM_SIMPLE在有限但经常使用的案例中提供快速实现复合文件对象的速度，涉及需要具有多个流且没有存储的复合文件实现的应用程序。有关详细信息，请参阅 STGM 常量。如果指定了STGM_SIMPLE，则指定STGM_TRANSACTED无效。

简单模式不支持 IStorage 上的所有方法。具体而言，在简单模式下，支持的 IStorage 方法是 CreateStream、Commit 和 SetClass，以及 QueryInterface、AddRef 和 Release 的 COM IUnknown 方法。此外， SetElementTimes 支持 NULL 名称，允许应用程序在根存储上设置时间。 IStorage 的所有其他方法返回STG_E_INVALIDFUNCTION。

如果 grfMode 参数指定STGM_TRANSACTED并且尚不存在由 pwcsName 参数指定的名称的文件，则会立即创建该文件。在访问控制的文件系统中，调用方必须对在其中创建复合文件的文件系统目录具有写入权限。如果未指定STGM_TRANSACTED，并且指定了STGM_CREATE，则会在创建新文件之前销毁同名的现有文件。

还可以使用 StgCreateStorageEx 通过为 pwcsName 参数传递 NULL 值来创建临时复合文件。但是，这些文件只是暂时性的，因为它们具有唯一的系统提供的名称，而这个名称对用户来说可能毫无意义。调用方负责在完成临时文件时删除临时文件，除非为 grfMode 参数指定了STGM_DELETEONRELEASE。有关这些标志的详细信息，请参阅 STGM 常量。

要求


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