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

Статья
06/02/2023

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

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

Синтаксис

BOOL SetFileAttributesTransactedA(
  [in] LPCSTR lpFileName,
  [in] DWORD  dwFileAttributes,
  [in] HANDLE hTransaction
);

Параметры

[in] lpFileName

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

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

Совет

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

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

[in] dwFileAttributes

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

Список значений атрибута файла и их описания см. в разделе Константы атрибутов файла. Этот параметр может быть одним или несколькими значениями, объединенными с помощью побитового оператора ИЛИ. Однако все остальные значения переопределяют 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))

FILE_ATTRIBUTE_SYSTEM (4 (0x4))

FILE_ATTRIBUTE_TEMPORARY (256 (0x100))

[in] hTransaction

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

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

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

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

attribute	Настройка
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 .

Дополнительные сведения о транзакциях см. в разделе Transactional NTFS.

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

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

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

Транзакция операций

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

Примечание

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

Требования

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