Функция StgOpenStorageEx (coml2api.h)
Функция StgOpenStorageEx открывает существующий корневой объект хранилища в файловой системе. Используйте эту функцию для открытия составных и обычных файлов. Чтобы создать файл, используйте функцию StgCreateStorageEx .
Синтаксис
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.
Требования
| Требование | Значение |
|---|---|
| Минимальная версия клиента | Windows 2000 Профессиональная [классические приложения | Приложения UWP] |
| Минимальная версия сервера | Windows 2000 Server [классические приложения | Приложения UWP] |
| Целевая платформа | Windows |
| Header | coml2api.h (включая Objbase.h) |
| Библиотека | Ole32.lib |
| DLL | Ole32.dll |
См. также раздел
Обратная связь
Ожидается в ближайшее время: в течение 2024 года мы постепенно откажемся от GitHub Issues как механизма обратной связи для контента и заменим его новой системой обратной связи. Дополнительные сведения см. в разделе https://aka.ms/ContentUserFeedback.
Отправить и просмотреть отзыв по