StgCreateDocfile 函数 (coml2api.h)

StgCreateDocfile 函数使用 COM 提供的 IStorage 接口的复合文件实现创建新的复合文件存储对象。

注意 应用程序应使用新函数 StgCreateStorageEx（而不是 StgCreateDocfile）来利用增强的结构化存储功能。 为了与 Windows 2000 兼容，此函数 StgCreateDocfile 仍然存在。

 

语法

HRESULT StgCreateDocfile(
  [in]  const WCHAR *pwcsName,
  [in]  DWORD       grfMode,
  [in]  DWORD       reserved,
  [out] IStorage    **ppstgOpen
);

参数

[in] pwcsName

指向正在创建的复合文件的以 null 结尾的 Unicode 字符串名称的指针。 它未解释地传递到文件系统。 这可以是相对名称或 NULL。 如果 为 NULL，则使用唯一名称分配临时复合文件。

[in] grfMode

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

[in] reserved

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

[out] ppstgOpen

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

返回值

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

注解

StgCreateDocfile 函数使用适用于 IStorage 接口的 COM 提供的复合文件实现创建新的存储对象。 可以通过调用 IStorage：：Stat 方法检索打开的复合文件的名称。

如果文件不存在，StgCreateDocfile 将创建该文件。 如果它确实存在，则在 grfMode 参数中使用STGM_CREATE、STGM_CONVERT和STGM_FAILIFTHERE标志指示如何继续操作。 有关详细信息，请参阅 STGM 常量。

如果在事务处理模式下打开复合文件 (grfMode 参数指定STGM_TRANSACTED) 并且已存在具有此名称的文件，则在提交所有未完成的更改之前，不会更改现有文件。 如果调用进程由于文件系统) 中的访问控制而对现有文件 (缺少写入访问权限， 则 grfMode 参数只能指定STGM_READ，而不能指定STGM_WRITE或STGM_READWRITE。 生成的新打开复合文件仍然可以写入，但后续提交操作将失败 (事务处理模式下，写入权限在提交时) 强制执行。

指定STGM_SIMPLE在有限但经常使用的情况下，可以更快地实现复合文件对象。 这可由需要具有多个流且没有存储的复合文件实现的应用程序使用。 简单模式不支持 IStorage 上的所有方法。 有关详细信息，请参阅 STGM 常量。

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

StgCreateDocfile 可用于通过为 pwcsName 参数传递 NULL 值来创建临时复合文件。 但是，这些文件只是暂时性的，因为它们具有系统提供的唯一名称（可能对用户没有意义）。 调用方负责在完成临时文件时删除临时文件，除非为 grfMode 参数指定了STGM_DELETEONRELEASE。

要求

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

另请参阅

STGM 常量

StgCreateDocFileOnILockBytes

StgCreateStorageEx