Функция StgCreateStorageEx (coml2api.h)
Функция StgCreateStorageEx создает новый объект хранилища с помощью предоставленной реализации для интерфейсов IStorage или IPropertySetStorage. Чтобы открыть существующий файл, используйте вместо этого функцию stgOpenStorageEx.
Приложения, написанные для Windows 2000, Windows Server 2003 и Windows XP должны использовать StgCreateStorageEx вместо StgCreateDocfile, чтобы воспользоваться расширенными функциями Windows 2000 и Windows XP Structured Storage.
Синтаксис
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 символов.
[in] grfMode
Значение, указывающее режим доступа, используемый при открытии нового объекта хранилища. Дополнительные сведения см. в констант STGM. Если вызывающий объект задает режим транзакций вместе с STGM_CREATE или STGM_CONVERT, при вызове операции фиксации для корневого хранилища происходит перезапись или преобразование. Если IStorage::Commit не вызывается для корневого объекта хранилища, будет восстановлено предыдущее содержимое файла. STGM_CREATE и STGM_CONVERT нельзя объединить с флагом STGM_NOSNAPSHOT, так как копия моментального снимка требуется при перезаписи или преобразовании файла в режиме транзакций.
[in] stgfmt
Значение, указывающее формат файла хранилища. Дополнительные сведения см. в перечислении STGFMT.
[in] grfAttrs
Значение, зависящее от значения параметра stgfmt.
| Значения параметров | Значение |
|---|---|
|
0 или FILE_FLAG_NO_BUFFERING. Дополнительные сведения см. в разделе CreateFile. Если размер сектора файла, указанный в pStgOptions, не является целым числом физического сектора базового диска, эта операция завершится ошибкой. |
|
Должно быть 0. |
[in] pStgOptions
Параметр
[in] pSecurityDescriptor
Позволяет задавать списки управления доступом при создании файла. Если не значение NULL, необходимо указывать на структуру SECURITY_ATTRIBUTES. Сведения о настройке списков управления доступом для файлов см. в CreateFile.
Windows Server 2003, Windows 2000 Server, Windows XP и Windows 2000 Профессиональный: значение должно быть NULL.
[in] riid
Значение, указывающее идентификатор интерфейса (IID) возвращаемого указателя интерфейса. Этот идентификатор iiD может быть для интерфейса
[out] ppObjectOpen
Указатель на переменную указателя интерфейса, которая получает указатель для интерфейса в новом объекте хранилища; содержит значение NULL, если операция завершилась ошибкой.
Возвращаемое значение
Эта функция также может возвращать любые ошибки файловой системы или системные ошибки, упакованные в HRESULT. Дополнительные сведения см. в статье Стратегии обработки ошибок и обработки неизвестных ошибок.
Замечания
При изменении файла приложение обычно создает копию исходного файла. Функция StgCreateStorageEx является одним из способов создания копии. Эта функция косвенно работает с API дублирования файловой системы шифрования (EFS). При использовании этой функции необходимо задать параметры хранилища файлов в структуре STGOPTIONS.
StgCreateStorageEx является супермножеством функции StgCreateDocfile и должна использоваться новым кодом. Будущие улучшения структурированного хранилища будут предоставляться с помощью функции StgCreateStorageEx. Дополнительные сведения о поддерживаемых платформах см. в следующем разделе "Требования".
Функция StgCreateStorageEx создает новый объект хранилища с помощью одной из системных реализаций структурированного хранилища. Эту функцию можно использовать для получения
реализацию составного файла IStorage, реализацию составного файла IPropertySetStorage илидля получения реализации NTFS IPropertySetStorage.
При создании нового файла используемая реализация хранилища зависит от указанного флага и типа диска, на котором хранится файл. Дополнительные сведения см. в перечислении STGFMT.
StgCreateStorageEx создает файл, если он не существует. Если он существует, использование флагов STGM_CREATE, STGM_CONVERT и STGM_FAILIFTHERE в параметре grfMode указывает, как продолжить. Дополнительные сведения об этих значениях см. в констант STGM. Недопустимо в прямом режиме, чтобы указать режим STGM_READ в параметре grfMode (прямой режим указывается без указания флага STGM_TRANSACTED). Эту функцию нельзя использовать для открытия существующего файла; вместо этого используйте функцию stgOpenStorageEx.
Функцию StgCreateStorageEx можно использовать для получения доступа к корневому хранилищу структурированного документа или хранилища набора свойств любого файла, поддерживающего наборы свойств. Сведения о том, какие идентификаторы IID поддерживаются для различных значений STGFMT, см. в документации по STGFMT.
При создании файла с этой функцией для доступа к реализации набора свойств NTFS применяются специальные правила общего доступа. Дополнительные сведения см.
Если составной файл создается в режиме транзакций (указав STGM_TRANSACTED) и режим только для чтения (указав STGM_READ), можно внести изменения в возвращаемый объект хранилища. Например, можно вызвать IStorage::CreateStream. Однако невозможно зафиксировать эти изменения путем вызова IStorage::Commit. Поэтому такие изменения будут потеряны.
Указание STGM_SIMPLE обеспечивает гораздо более быструю реализацию составного объекта файла в ограниченном, но часто используемом случае с участием приложений, требующих составной реализации файлов с несколькими потоками и без хранилищ. Дополнительные сведения см. в констант STGM. Недопустимо указать, что STGM_TRANSACTED, если указан STGM_SIMPLE.
Простой режим не поддерживает все методы IStorage. В частности, в простом режиме поддерживаются методы IStorageCreateStream, Commitи SetClass, а также методы 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] |
| целевая платформа | Виндоус |
| заголовка | coml2api.h (include Objbase.h) |
| библиотеки |
Ole32.lib |
| DLL | Ole32.dll |
См. также
константы STGM