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

Функция StgCreateDocfile создает новый объект хранилища составных файлов, используя предоставленную COM реализацию составного файла для интерфейса IStorage .

Синтаксис

HRESULT StgCreateDocfile(
  [in]  const WCHAR *pwcsName,
  [in]  DWORD       grfMode,
  [in]  DWORD       reserved,
  [out] IStorage    **ppstgOpen
);

Параметры

[in] pwcsName

Указатель на строковое имя Юникода, завершаемое null, для создаваемого составного файла. Он передается в файловую систему без интерпретации. Это может быть относительное имя или ЗНАЧЕНИЕ NULL. Если значение РАВНО NULL, временный составной файл выделяется с уникальным именем.

[in] grfMode

Указывает режим доступа, используемый при открытии нового объекта хранилища. Дополнительные сведения см. в разделе Константы STGM. Если вызывающий объект указывает режим транзакций вместе с STGM_CREATE или STGM_CONVERT, то при вызове операции фиксации для корневого хранилища выполняется перезапись или преобразование. Если iStorage::Commit не вызывается для корневого объекта хранилища, будет восстановлено предыдущее содержимое файла. STGM_CREATE и STGM_CONVERT нельзя объединить с флагом STGM_NOSNAPSHOT, так как при перезаписи или преобразовании файла в режиме транзакций требуется копия snapshot.

[in] reserved

Зарезервировано для будущего использования; должно иметь значение нуль.

[out] ppstgOpen

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

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

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

Комментарии

Функция StgCreateDocfile создает новый объект хранилища, используя предоставленную COM реализацию составного файла для интерфейса IStorage . Имя открытого составного файла можно получить, вызвав метод IStorage::Stat .

StgCreateDocfile создает файл, если он не существует. Если он существует, то использование флагов STGM_CREATE, STGM_CONVERT и STGM_FAILIFTHERE в параметре grfMode указывает, как продолжить. Дополнительные сведения см. в разделе Константы STGM.

Если составной файл открыт в режиме транзакций (параметр grfMode указывает STGM_TRANSACTED) и файл с таким именем уже существует, существующий файл не изменяется до тех пор, пока не будут зафиксированы все незавершенные изменения. Если вызывающий процесс не имеет доступа на запись к существующему файлу (из-за управления доступом в файловой системе), параметр grfMode может указывать только STGM_READ и не STGM_WRITE или STGM_READWRITE. Полученный новый открытый составной файл по-прежнему можно записать в, но последующая операция фиксации завершится ошибкой (в режиме транзакций разрешения на запись применяются во время фиксации).

Указание STGM_SIMPLE обеспечивает гораздо более быструю реализацию составного объекта файла в ограниченном, но часто используемом случае. Он может использоваться приложениями, которым требуется реализация составного файла с несколькими потоками и без хранилищ. Простой режим не поддерживает все методы в IStorage. Дополнительные сведения см. в разделе Константы STGM.

Если параметр grfMode указывает, STGM_TRANSACTED и файл с именем, указанным параметром pwcsName , еще не существует, файл создается немедленно. В файловой системе, управляемой доступом, вызывающий объект должен иметь разрешения на запись в каталоге файловой системы, в котором создается составной файл. Если STGM_TRANSACTED не указан, а STGM_CREATE указан, существующий файл с тем же именем удаляется перед созданием нового файла.

StgCreateDocfile можно использовать для создания временного составного файла, передав значение NULL для параметра pwcsName . Однако эти файлы являются временными только в том смысле, что у них есть предоставленное системой уникальное имя, которое, скорее всего, не имеет смысла для пользователя. Вызывающий объект отвечает за удаление временного файла после завершения работы с ним, если для параметра grfMode не указан STGM_DELETEONRELEASE.

Требования

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

Константы STGM

StgCreateDocFileOnILockBytes

StgCreateStorageEx