Функция CreateDirectoryTransactedA (winbase.h)

Статья
11/20/2024

[Корпорация Майкрософт настоятельно рекомендует разработчикам использовать альтернативные средства для достижения потребностей вашего приложения. Многие сценарии, для которые TxF был разработан, можно достичь с помощью более простых и более доступных методов. Кроме того, TxF может быть недоступна в будущих версиях Microsoft Windows. Дополнительные сведения и альтернативные варианты TxF см. в разделе Альтернативные варианты использования транзакционных NTFS.]

Создает новый каталог как транзакцию с атрибутами указанного каталога шаблона. Если базовая файловая система поддерживает безопасность файлов и каталогов, функция применяет указанный дескриптор безопасности к новому каталогу. Новый каталог сохраняет другие атрибуты указанного каталога шаблона.

Синтаксис

BOOL CreateDirectoryTransactedA(
  [in, optional] LPCSTR                lpTemplateDirectory,
  [in]           LPCSTR                lpNewDirectory,
  [in, optional] LPSECURITY_ATTRIBUTES lpSecurityAttributes,
  [in]           HANDLE                hTransaction
);

Параметры

[in, optional] lpTemplateDirectory

Путь к каталогу для использования в качестве шаблона при создании нового каталога. Этот параметр может быть NULL.

По умолчанию имя ограничено MAX_PATH символами. Чтобы расширить это ограничение до 32 767 расширенных символов, добавьте "\\?\" в путь. Дополнительные сведения см. в именовании файлов, путей и пространств имен.

Кончик

Начиная с Windows 10 версии 1607, вы можете отказаться от ограничения MAX_PATH без предустановки "\\?\". Дополнительные сведения см. в разделе "Ограничение максимальной длины пути" файлы именования, пути и пространства имен.

Каталог должен находиться на локальном компьютере; в противном случае функция завершается ошибкой, а для последнего кода ошибки задано значение ERROR_TRANSACTIONS_UNSUPPORTED_REMOTE.

[in] lpNewDirectory

Путь к созданному каталогу.

Кончик

[in, optional] lpSecurityAttributes

Указатель на структуру SECURITY_ATTRIBUTES. Элемент lpSecurityDescriptor указывает дескриптор безопасности для нового каталога.

Если lpSecurityAttributesNULL, каталог получает дескриптор безопасности по умолчанию. Списки управления доступом (ACL) в дескрипторе безопасности по умолчанию для каталога наследуются от родительского каталога.

Целевая файловая система должна поддерживать безопасность файлов и каталогов, чтобы этот параметр повлиял. Это указывает, когда GetVolumeInformation возвращает FS_PERSISTENT_ACLS.

[in] hTransaction

Дескриптор транзакции. Этот дескриптор возвращается функцией CreateTransaction.

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

Если функция выполнена успешно, возвращаемое значение ненулевое.

Если функция завершается ошибкой, возвращаемое значение равно нулю (0). Чтобы получить расширенные сведения об ошибке, вызовите GetLastError. Возможные ошибки включают следующие.

Возвращаемый код	Описание
ERROR_ALREADY_EXISTS	Указанный каталог уже существует.
ERROR_EFS_NOT_ALLOWED_IN_TRANSACTION	Невозможно создать дочерний каталог с родительским каталогом, который отключил шифрование.
ERROR_PATH_NOT_FOUND	Один или несколько промежуточных каталогов не существуют. Эта функция создает только окончательный каталог в пути.

Замечания

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

Некоторые файловые системы, такие как файловая система NTFS, поддерживают сжатие или шифрование отдельных файлов и каталогов. В томах, отформатированных для такой файловой системы, новый каталог наследует атрибуты сжатия и шифрования родительского каталога.

Эта функция завершается ошибкой ERROR_EFS_NOT_ALLOWED_IN_TRANSACTION, если вы пытаетесь создать дочерний каталог с родительским каталогом, который отключил шифрование.

Вы можете получить дескриптор в каталог, вызвав функцию createFileTransacted с набором флагов FILE_FLAG_BACKUP_SEMANTICS.

В Windows 8 и Windows Server 2012 эта функция поддерживается следующими технологиями.

Технологии	Поддержанный
Протокол SMB 3.0	Нет
Отработка отказа SMB 3.0 (TFO)	Нет
SMB 3.0 с масштабируемыми общими папками (SO)	Нет
Файловая система общего тома кластера (CSVFS)	Нет
Отказоустойчивая файловая система (ReFS)	Нет

SMB 3.0 не поддерживает TxF.

Заметка

Заголовок winbase.h определяет CreateDirectoryTransacted как псевдоним, который автоматически выбирает версию ANSI или Юникод этой функции на основе определения константы препроцессора ЮНИКОДа. Сочетание использования псевдонима, нейтрального для кодирования, с кодом, не зависящим от кодирования, может привести к несоответствиям, которые приводят к ошибкам компиляции или среды выполнения. Дополнительные сведения см. в соглашениях о прототипах функций.

Требования

Требование	Ценность
минимальные поддерживаемые клиентские	Windows Vista [только классические приложения]
минимальный поддерживаемый сервер	Windows Server 2008 [только классические приложения]
целевая платформа	Виндоус
заголовка	winbase.h (включая Windows.h)
библиотеки	Kernel32.lib
DLL	Kernel32.dll