Функция StgOpenStorage (coml2api.h)

Статья
08/22/2023

Функция StgOpenStorage открывает существующий корневой объект хранилища в файловой системе. Используйте эту функцию для открытия составных файлов. Не используйте его для открытия каталогов, файлов или сводных каталогов. Вложенные объекты хранилища можно открыть только с помощью родительского метода IStorage::OpenStorage .

Примечание Приложения должны использовать новую функцию StgOpenStorageEx вместо StgOpenStorage, чтобы воспользоваться преимуществами функций расширенного и структурированного хранилища Windows. Эта функция StgOpenStorage по-прежнему существует для обеспечения совместимости с приложениями, работающими в Windows 2000.

Синтаксис

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

Параметры

[in] pwcsName

Указатель на путь к строкового файла Юникода, завершаемого значением NULL, который содержит открываемый объект хранилища. Этот параметр игнорируется, если параметр pstgPriority не имеет значения NULL.

[in] pstgPriority

Указатель на интерфейс IStorage , который должен иметь значение NULL. Если значение не равно NULL, этот параметр используется, как описано ниже в разделе Примечания.

После возврата StgOpenStorage объект хранилища, указанный в pStgPriority , может быть освобожден и больше не должен использоваться.

[in] grfMode

Указывает режим доступа, используемый для открытия объекта хранилища.

[in] snbExclude

Если значение не равно NULL, указатель на блок элементов в хранилище, который будет исключен при открытии объекта хранилища. Исключение происходит независимо от того, происходит ли копирование snapshot на открытом. Может иметь значение NULL.

[in] reserved

Указывает, зарезервировано для использования в будущем; значение должно быть равно нулю.

[out] ppstgOpen

Указатель на переменную указателя IStorage*, которая получает указатель интерфейса на открытое хранилище.

Возвращаемое значение

Функция StgOpenStorage также может возвращать любые ошибки файловой системы или системные ошибки, заключенные в HRESULT. Дополнительные сведения см. в разделах Стратегии обработки ошибок и Обработка неизвестных ошибок.

Функция StgOpenStorage открывает указанный корневой объект хранилища в соответствии с режимом доступа в параметре grfMode и в случае успешного выполнения предоставляет указатель IStorage на открытый объект хранения в параметре ppstgOpen .

Для поддержки простого режима для сохранения объекта хранилища без вложенных журналов функция 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 должен snapshot всего объекта хранилища.

Приложения часто пытаются открыть объекты хранилища со следующими разрешениями доступа. Если приложение завершается успешно, ему не нужно создавать snapshot копию.

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

Приложение может отменить изменения использовать разрешения и создать snapshot копию, если предыдущие разрешения на доступ не удается. Приложение должно запрашивать у пользователя перед созданием копии, отнимающей много времени.

STGM_READWRITE 
    // transacted versus direct mode omitted for exposition

Если семантика общего доступа к документам, подразумеваемая режимами доступа, подходит, приложение может попытаться открыть хранилище следующим образом. В этом случае при успешном выполнении приложения копия snapshot не будет выполнена (так как STGM_SHARE_DENY_WRITE была указана, что запрещает другим пользователям доступ на запись).

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

Примечание Чтобы сократить затраты на копирование snapshot, приложения могут открывать объекты хранилища в режиме приоритета (grfMode указывает STGM_PRIORITY).

Параметр snbExclude указывает набор имен элементов в этом объекте хранилища, которые должны быть очищены при открытии объекта хранилища: потоки имеют нулевую длину; Все элементы объектов хранилища удалены. За счет исключения определенных потоков затраты на создание snapshot копии можно значительно сократить. Почти всегда этот подход используется после первого открытия объекта хранилища в режиме приоритета, а затем полного считывания исключенных элементов в память. Это более раннее открытие объекта хранилища в режиме приоритета должно быть передано через параметр pstgPriority , чтобы удалить исключение, подразумеваемое режимом приоритета. Вызывающее приложение отвечает за перезапись содержимого исключенных элементов перед фиксацией. Таким образом, этот метод, скорее всего, полезен только для приложений, документы которых не требуют постоянного доступа к объектам хранилища, пока они активны.

Параметр pstgPriority предназначен для удобства для вызывающих объектов, заменяющих существующий объект хранилища, часто открытый в режиме приоритета, новым объектом хранения, открытым в том же файле, но в другом режиме. Если pstgPriority не имеет значение NULL, он используется для указания имени файла вместо pwcsName, которое игнорируется. Однако рекомендуется, чтобы приложения всегда передавали значение NULL для pstgPriority , так как StgOpenStorage освобождает объект при определенных обстоятельствах и не освобождает его при других обстоятельствах. В частности, если функция возвращает результат сбоя, вызывающий объект не может определить, был ли освобожден объект хранилища.

Функциональность параметра pstgPriority может дублироваться вызывающим абонентом более безопасным образом, как показано в следующем примере:

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

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

Требования

Требование	Значение
Минимальная версия клиента	Windows 2000 Профессиональная [классические приложения \| Приложения UWP]
Минимальная версия сервера	Windows 2000 Server [классические приложения \| Приложения UWP]
Целевая платформа	Windows
Header	coml2api.h (включая Objbase.h)
Библиотека	Ole32.lib
DLL	Ole32.dll

См. также раздел

IStorage

StgCreateDocfile

StgOpenStorageEx