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

Статья
08/22/2023

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

Если объект хранилища открыт в прямом режиме (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 , содержащую данные об открытом объекте хранилища. Параметр pStgOptions действителен , только если параметру stgfmt присвоено значение STGFMT_DOCFILE. Перед вызовом StgOpenStorageEx необходимо задать элемент usVersion. Дополнительные сведения см. в разделе Структура STGOPTIONS .

[in] pSecurityDescriptor

Защищены; значение должно быть равно нулю.

[in] riid

Значение типа , указывающее GUID возвращаемого указателя интерфейса. Может также быть заданным заголовком значением для IID_IStorage для получения интерфейса IStorage или для IID_IPropertySetStorage для получения интерфейса IPropertySetStorage .

[out] ppObjectOpen

Адрес переменной указателя интерфейса, которая получает указатель на интерфейс в открытом объекте хранилища; содержит ЗНАЧЕНИЕ NULL , если операция завершилась сбоем.

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

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

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

Функция StgOpenStorageEx открывает указанный корневой объект хранилища в соответствии с режимом доступа в параметре grfMode и в случае успешного выполнения предоставляет указатель интерфейса для открытого объекта хранилища в параметре ppObjectOpen . Эта функция может использоваться для получения реализации составного файла IStorage, реализации составного файла IPropertySetStorage или
Реализация файловой системы NTFS для IPropertySetStorage.

При открытии файла система выбирает реализацию структурированного хранилища в зависимости от того, какой флаг STGFMT указан в типе файла и типе диска, на котором хранится файл.

Используйте функцию StgOpenStorageEx для доступа к корневому хранилищу структурированного документа хранилища или хранилищу наборов свойств любого файла, поддерживающего наборы свойств. Дополнительные сведения о том, какие идентификаторы интерфейса (IID) поддерживаются для различных значений STGFMT , см. в разделе STGFMT.

При открытии файла с помощью этой функции для доступа к реализации набора свойств NTFS применяются специальные правила общего доступа. Дополнительные сведения см. в разделе Реализация IPropertySetStorage-NTFS.

Если составной файл открывается в режиме транзакций, указав STGM_TRANSACTED и режим только для чтения, указав STGM_READ, можно изменить возвращаемый объект хранилища. Например, можно вызвать IStorage::CreateStream. Однако невозможно зафиксировать эти изменения путем вызова IStorage::Commit. Таким образом, такие изменения будут потеряны.

Недопустимо использовать флаги STGM_CREATE, STGM_DELETEONRELEASE или STGM_CONVERT в параметре grfMode для этой функции.

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

Требования

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