Функция SetFileAttributesW (fileapi.h)

Статья
06/02/2023

Задает атрибуты для файла или каталога.

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

Синтаксис

BOOL SetFileAttributesW(
  [in] LPCWSTR lpFileName,
  [in] DWORD   dwFileAttributes
);

Параметры

[in] lpFileName

Имя файла, атрибуты которого необходимо задать.

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

Кончик

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

[in] dwFileAttributes

Атрибуты файла, заданные для файла.

Этот параметр может быть одним или несколькими значениями, объединенными с помощью побитового оператора OR. Однако все остальные значения переопределяются FILE_ATTRIBUTE_NORMAL.

Не все атрибуты поддерживаются этой функцией. Дополнительные сведения см. в разделе "Примечания".

Ниже приведен список поддерживаемых значений атрибутов.

Ценность	Значение
FILE_ATTRIBUTE_ARCHIVE 32 (0x20)	Файл или каталог, который является архивным файлом или каталогом. Приложения обычно используют этот атрибут для пометки файлов для резервного копирования или удаления.
FILE_ATTRIBUTE_HIDDEN 2 (0x2)	Файл или каталог скрыт. Он не включен в обычный список каталогов.
FILE_ATTRIBUTE_NORMAL 128 (0x80)	Файл, который не имеет других атрибутов. Этот атрибут действителен только при использовании в одиночку.
FILE_ATTRIBUTE_NOT_CONTENT_INDEXED 8192 (0x2000)	Файл или каталог не индексируются службой индексирования контента.
FILE_ATTRIBUTE_OFFLINE 4096 (0x1000)	Данные файла недоступны немедленно. Этот атрибут указывает, что данные файла физически перемещаются в автономное хранилище. Этот атрибут используется удаленным хранилищем, который является программным обеспечением управления иерархическим хранилищем. Приложения не должны произвольно изменять этот атрибут.
FILE_ATTRIBUTE_READONLY 1 (0x1)	Файл, доступный только для чтения. Приложения могут считывать файл, но не могут записывать в него или удалять его. Этот атрибут не учитывается в каталогах. Дополнительные сведения см. в статье "Невозможно просмотреть или изменить только для чтения или системные атрибуты папок в Windows Server 2003, в Windows XP или в Windows Vista.
FILE_ATTRIBUTE_SYSTEM 4 (0x4)	Файл или каталог, который операционная система использует часть или использует исключительно.
FILE_ATTRIBUTE_TEMPORARY 256 (0x100)	Файл, используемый для временного хранилища. Файловые системы не записывать данные обратно в массовое хранилище, если доступно достаточное количество памяти кэша, так как обычно приложение удаляет временный файл после закрытия дескриптора. В этом сценарии система может полностью избежать записи данных. В противном случае данные записываются после закрытия дескриптора.

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

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

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

Замечания

В следующей таблице описывается, как задать атрибуты, которые нельзя задать с помощью SetFileAttributes. Полный список всех значений атрибутов файла и их описания см. вконстанты атрибутов файла.

Атрибут	Настройка
FILE_ATTRIBUTE_COMPRESSED 0x800	Чтобы задать состояние сжатия файла, используйте функцию DeviceIoControl с операцией FSCTL_SET_COMPRESSION.
FILE_ATTRIBUTE_DEVICE 0x40	Скрытный; не используйте.
FILE_ATTRIBUTE_DIRECTORY 0x10	Файлы нельзя преобразовать в каталоги. Чтобы создать каталог, используйте функцию CreateDirectory или CreateDirectoryEx.
FILE_ATTRIBUTE_ENCRYPTED 0x4000	Чтобы создать зашифрованный файл, используйте функцию CreateFile с атрибутом FILE_ATTRIBUTE_ENCRYPTED. Чтобы преобразовать существующий файл в зашифрованный файл, используйте функцию EncryptFile.
FILE_ATTRIBUTE_REPARSE_POINT 0x400	Чтобы связать точку повторного определения с файлом или каталогом, используйте функцию DeviceIoControl с операцией FSCTL_SET_REPARSE_POINT.
FILE_ATTRIBUTE_SPARSE_FILE 0x200	Чтобы задать разреженный атрибут файла, используйте функцию DeviceIoControl с операцией FSCTL_SET_SPARSE.

операции с транзакцией

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

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

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

Примеры

Пример см. в разделе получения и изменения атрибутов файла.

Заметка

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

Требования

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