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

Статья
03/03/2024

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

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

Синтаксис

BOOL CreateDirectoryExW(
  [in]           LPCWSTR               lpTemplateDirectory,
  [in]           LPCWSTR               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 структуры задает дескриптор безопасности для нового каталога.

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

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

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

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

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

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

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

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

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

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

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

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

Примечание

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

Требования

Требование	Значение
Минимальная версия клиента	Windows XP [только классические приложения]
Минимальная версия сервера	Windows Server 2003 [только классические приложения]
Целевая платформа	Windows
Header	winbase.h (включая Windows.h)
Библиотека	Kernel32.lib
DLL	Kernel32.dll