StgOpenStorage 函数 (coml2api.h)

项目
08/22/2023

StgOpenStorage 函数打开文件系统中的现有根存储对象。使用此函数打开复合文件。请勿使用它打开目录、文件或摘要目录。嵌套存储对象只能使用其父 IStorage：：OpenStorage 方法打开。

注意应用程序应使用新函数 StgOpenStorageEx，而不是 StgOpenStorage，以利用增强和 Windows 结构化存储功能。为了与 Windows 2000 上运行的应用程序兼容，此函数 StgOpenStorage 仍然存在。

语法

HRESULT StgOpenStorage(
  [in]  const WCHAR *pwcsName,
  [in]  IStorage    *pstgPriority,
  [in]  DWORD       grfMode,
  [in]  SNB         snbExclude,
  [in]  DWORD       reserved,
  [out] IStorage    **ppstgOpen
);

参数

[in] pwcsName

指向包含要打开的存储对象的 以 null 结尾的 Unicode 字符串文件的路径的指针。如果 pstgPriority 参数不为 NULL，则忽略此参数。

[in] pstgPriority

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

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

[in] grfMode

指定用于打开存储对象的访问模式。

[in] snbExclude

如果不是 NULL，则指向在打开存储对象时要排除的存储中的元素块的指针。无论打开时是否发生快照复制，都会发生排除。可以为 NULL。

[in] reserved

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

[out] ppstgOpen

指向 IStorage* 指针变量的指针，该变量接收指向打开的存储的接口指针。

返回值

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

注解

StgOpenStorage 函数根据 grfMode 参数中的访问模式打开指定的根存储对象，如果成功，则会在 ppstgOpen 参数中提供指向打开的存储对象的 IStorage 指针。

为了支持保存没有子存储的存储对象的简单模式， StgOpenStorage 函数接受以下两个标志组合之一作为 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_DIRECT | STGM_READWRITE | STGM_SHARE_EXCLUSIVE

    STGM_DIRECT | STGM_READ | STGM_SHARE_DENY_WRITE

    STGM_DIRECT | STGM_READ | STGM_SHARE_EXCLUSIVE

注意在读/写模式下打开存储对象而不拒绝对其他人的写入权限 (grfMode 参数指定STGM_SHARE_DENY_WRITE) 可能是一个耗时的操作，因为 StgOpenStorage 调用必须对整个存储对象进行快照。

应用程序通常会尝试使用以下访问权限打开存储对象。如果应用程序成功，则无需创建快照副本。

STGM_READWRITE | STGM_SHARE_DENY_WRITE 
    // transacted versus direct mode omitted for exposition

如果以前的访问权限失败，应用程序可以还原使用权限并创建快照副本。在进行耗时的副本之前，应用程序应提示用户。

STGM_READWRITE 
    // transacted versus direct mode omitted for exposition

如果访问模式隐含的文档共享语义合适，则应用程序可以尝试按如下所示打开存储。在这种情况下，如果应用程序成功，则不会 (进行快照复制，因为指定了STGM_SHARE_DENY_WRITE，) 拒绝其他人的写入访问权限。

STGM_READ | STGM_SHARE_DENY_WRITE 
    // transacted versus direct mode omitted for exposition

注意为了减少创建快照复制的费用，应用程序可以在 grfMode 指定STGM_PRIORITY) ( 优先级模式下打开存储对象。

snbExclude 参数指定此存储对象中的一组元素名称，这些名称将在打开存储对象时清空：将流设置为零的长度;存储对象删除了其所有元素。通过排除某些流，可以显著降低复制快照的费用。在先在优先级模式下打开存储对象，然后将现在排除的元素完全读取到内存中后，几乎总是使用此方法。应通过 pstgPriority 参数传递存储对象的早期优先级模式打开，以删除优先级模式所暗示的排除项。调用应用程序负责在提交之前重写已排除项的内容。因此，此方法很可能仅适用于文档在活动时不需要持续访问其存储对象的应用程序。

pstgPriority 参数旨在方便调用方将现有存储对象（通常是在优先级模式下打开的存储对象）替换为在同一文件上打开但在不同模式下打开的新存储对象。当 pstgPriority 不为 NULL 时，它将用于指定文件名，而不是 忽略 pwcsName。但是，建议应用程序始终为 pstgPriority 传递 NULL，因为 StgOpenStorage 在某些情况下会释放对象，而在其他情况下不会释放它。具体而言，如果函数返回失败结果，则调用方无法确定存储对象是否已释放。

调用方可以更安全的方式复制 pstgPriority 参数的功能，如以下示例所示：

// Replacement for:
// HRESULT hr = StgOpenStorage(
//         NULL, pstgPriority, grfMode, NULL, 0, &pstgNew);

STATSTG statstg;
HRESULT hr = pstgPriority->Stat(&statstg, 0);
pStgPriority->Release();
pStgPriority = NULL;
if (SUCCEEDED(hr))
{
    hr = StgOpenStorage(statstg.pwcsName, NULL, grfMode, NULL, 0, &pstgNew);
}

要求

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

另请参阅

IStorage

StgCreateDocfile

StgOpenStorageEx

通过

StgOpenStorage 函数 (coml2api.h)

语法

参数

返回值

注解

要求

另请参阅

反馈

其他资源