Функция StgCreateStorageEx (coml2api.h)
Функция StgCreateStorageEx создает новый объект хранилища, используя предоставленную реализацию для интерфейсов IStorage или IPropertySetStorage . Чтобы открыть существующий файл, используйте вместо него функцию StgOpenStorageEx .
Приложения, написанные для Windows 2000, Windows Server 2003 и Windows XP, должны использовать StgCreateStorageEx , а не StgCreateDocfile , чтобы воспользоваться преимуществами расширенных функций структурированного хранилища Windows 2000 и Windows XP.
Синтаксис
HRESULT StgCreateStorageEx(
[in] const WCHAR *pwcsName,
[in] DWORD grfMode,
[in] DWORD stgfmt,
[in] DWORD grfAttrs,
[in] STGOPTIONS *pStgOptions,
[in] PSECURITY_DESCRIPTOR pSecurityDescriptor,
[in] REFIID riid,
[out] void **ppObjectOpen
);
Параметры
[in] pwcsName
Указатель на путь к создаваемому файлу. Он передается неинтерпретированным в файловую систему. Это может быть относительное имя или ЗНАЧЕНИЕ NULL. Если значение РАВНО NULL, временный файл выделяется с уникальным именем. Если значение не равно NULL, размер строки не должен превышать MAX_PATH символов.
Windows 2000: В отличие от функции CreateFile , нельзя превысить ограничение MAX_PATH с помощью префикса "\?".
[in] grfMode
Значение типа , указывающее режим доступа, используемый при открытии нового объекта хранилища. Дополнительные сведения см. в разделе Константы STGM. Если вызывающий объект задает режим транзакций вместе с STGM_CREATE или STGM_CONVERT, перезапись или преобразование выполняется при вызове операции фиксации для корневого хранилища. Если IStorage::Commit не вызывается для корневого объекта хранилища, предыдущее содержимое файла будет восстановлено. STGM_CREATE и STGM_CONVERT нельзя объединить с флагом STGM_NOSNAPSHOT, так как при перезаписи или преобразовании файла в режиме транзакций требуется копия snapshot.
[in] stgfmt
Значение типа , указывающее формат файла хранилища. Дополнительные сведения см. в перечислении STGFMT .
[in] grfAttrs
Значение , зависящее от значения параметра stgfmt .
| Значения параметров | Значение |
|---|---|
|
0 или FILE_FLAG_NO_BUFFERING. Дополнительные сведения см. в разделе CreateFile. Если размер сектора файла, указанный в pStgOptions, не является целым числом, кратным размеру физического сектора базового диска, эта операция завершится ошибкой. |
|
Должно быть равно 0. |
[in] pStgOptions
Параметр pStgOptions действителен , только если параметру stgfmt присвоено значение STGFMT_DOCFILE. Если параметру stgfmt присвоено значение STGFMT_DOCFILE, pStgOptions указывает на структуру STGOPTIONS , которая определяет признаки объекта хранения, такие как размер сектора. Этот параметр может иметь значение NULL, что создает объект хранилища с размером сектора по умолчанию 512 байт. Если значение не равно NULL, для элемента ulSectorSize необходимо задать значение 512 или 4096. Если задано значение 4096, STGM_SIMPLE может не быть указано в параметре grfMode . Перед вызовом StgCreateStorageEx необходимо задать элемент usVersion. Дополнительные сведения см. в разделе STGOPTIONS.
[in] pSecurityDescriptor
Позволяет задавать списки управления доступом при создании файла. Если значение не равно NULL, должен быть указателем на структуру SECURITY_ATTRIBUTES . Сведения о настройке списков управления доступом для файлов см. в разделе CreateFile .
Windows Server 2003, Windows 2000 Server, Windows XP и Windows 2000 Professional: Значение должно иметь значение NULL.
[in] riid
Значение типа , указывающее идентификатор интерфейса (IID) возвращаемого указателя интерфейса. Это может быть интерфейс IStorage или интерфейс IPropertySetStorage .
[out] ppObjectOpen
Указатель на переменную указателя интерфейса, которая получает указатель на интерфейс в новом объекте хранилища; содержит ЗНАЧЕНИЕ NULL , если операция завершилась сбоем.
Возвращаемое значение
Эта функция также может возвращать любые ошибки файловой системы или системные ошибки, заключенные в HRESULT. Дополнительные сведения см. в разделах Стратегии обработки ошибок и Обработка неизвестных ошибок.
Комментарии
Когда приложение изменяет свой файл, оно обычно создает копию исходного файла. Одним из способов создания копии является функция StgCreateStorageEx . Эта функция работает косвенно с API дублирования шифруемой файловой системы (EFS). При использовании этой функции необходимо задать параметры для хранения файлов в структуре STGOPTIONS .
StgCreateStorageEx является надмножеством функции StgCreateDocfile и должен использоваться в новом коде. Будущие усовершенствования структурированного хранилища будут доступны с помощью функции StgCreateStorageEx . Сведения о поддерживаемых платформах см. в следующем разделе Требования.
Функция StgCreateStorageEx создает новый объект хранилища с помощью одной из предоставляемых системой структурированных реализаций хранилища. Эту функцию можно использовать для получения
Реализация составного файла IStorage, реализация составного файла IPropertySetStorage или для получения реализации IPropertySetStorage NTFS.
При создании нового файла используемая реализация хранилища зависит от указанного флага и типа диска, на котором хранится файл. Дополнительные сведения см. в перечислении STGFMT .
StgCreateStorageEx создает файл, если он не существует. Если он существует, то использование флагов STGM_CREATE, STGM_CONVERT и STGM_FAILIFTHERE в параметре grfMode указывает, как продолжать работу. Дополнительные сведения об этих значениях см. в разделе Константы STGM. В прямом режиме недопустимо указывать режим STGM_READ в параметре grfMode (прямой режим обозначается без указания флага STGM_TRANSACTED). Эту функцию нельзя использовать для открытия существующего файла; вместо этого используйте функцию StgOpenStorageEx .
Функцию StgCreateStorageEx можно использовать для получения доступа к корневому хранилищу структурированного документа или к хранилищу набора свойств любого файла, поддерживающего наборы свойств. Сведения о том, какие идентификаторы IID поддерживаются для различных значений STGFMT, см. в документации по STGFMT.
При создании файла с помощью этой функции для доступа к реализации набора свойств NTFS применяются специальные правила общего доступа. Дополнительные сведения см. в разделе Реализация IPropertySetStorage-NTFS.
Если составной файл создается в режиме транзакций (путем указания STGM_TRANSACTED) и режиме только для чтения (путем указания STGM_READ), можно внести изменения в возвращаемый объект хранилища. Например, можно вызвать IStorage::CreateStream. Однако невозможно зафиксировать эти изменения путем вызова IStorage::Commit. Таким образом, такие изменения будут потеряны.
Указание STGM_SIMPLE обеспечивает гораздо более быструю реализацию объекта составного файла в ограниченном, но часто используемом случае с приложениями, для которых требуется реализация составного файла с несколькими потоками и без хранилищ. Дополнительные сведения см. в разделе Константы STGM. Недопустимо указывать этот STGM_TRANSACTED, если указан STGM_SIMPLE.
Простой режим не поддерживает все методы в IStorage. В частности, в простом режиме поддерживаются методы IStorageCreateStream, Commit и SetClass , а также методы COM IUnknownqueryInterface, AddRef и Release. Кроме того, SetElementTimes поддерживается с именем NULL , что позволяет приложениям задавать время в корневом хранилище. Все остальные методы IStorage возвращают STG_E_INVALIDFUNCTION.
Если параметр grfMode указывает STGM_TRANSACTED и файл с именем, указанным параметром pwcsName , еще не существует, файл создается немедленно. В файловой системе с управлением доступом вызывающий объект должен иметь разрешения на запись для каталога файловой системы, в котором создается составной файл. Если STGM_TRANSACTED не указан, а STGM_CREATE указан, существующий файл с тем же именем удаляется перед созданием нового файла.
StgCreateStorageEx также можно использовать для создания временного составного файла, передав значение NULL для параметра pwcsName. Однако эти файлы являются временными только в том смысле, что они имеют уникальное системное имя, которое, вероятно, бессмысленно для пользователя. Вызывающий объект отвечает за удаление временного файла по завершении работы с ним, если для параметра grfMode не было указано STGM_DELETEONRELEASE. Дополнительные сведения об этих флагах см. в разделе Константы 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.
Отправить и просмотреть отзыв по