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

Статья
11/20/2024

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

Чтобы выполнить эту операцию как транзакционная операция, используйте функцию CreateDirectoryTransacted.

Синтаксис

BOOL CreateDirectoryExA(
  [in]           LPCSTR                lpTemplateDirectory,
  [in]           LPCSTR                lpNewDirectory,
  [in, optional] LPSECURITY_ATTRIBUTES lpSecurityAttributes
);

Параметры

[in] lpTemplateDirectory

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

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

Кончик

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

[in] lpNewDirectory

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

Кончик

[in, optional] lpSecurityAttributes

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

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

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

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

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

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

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

Замечания

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

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

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

Для поддержки функций наследования, запрашивающих дескриптор безопасности этого объекта, можно эвристически определить и сообщить о том, что наследование действует. Дополнительные сведения см. в автоматическом распространении наследуемых.

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

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

Заметка

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

Требования

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