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

Статья
06/02/2023

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

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

Чтобы выполнить эту операцию как нетрансляционную операцию или получить доступ к объектам, отличным от файлов (например, именованные каналы, физические устройства, почтовые объекты), используйте функцию CreateFile .

Дополнительные сведения о транзакциях см. в разделе Примечания этого раздела.

Синтаксис

HANDLE CreateFileTransactedA(
  [in]           LPCSTR                lpFileName,
  [in]           DWORD                 dwDesiredAccess,
  [in]           DWORD                 dwShareMode,
  [in, optional] LPSECURITY_ATTRIBUTES lpSecurityAttributes,
  [in]           DWORD                 dwCreationDisposition,
  [in]           DWORD                 dwFlagsAndAttributes,
  [in, optional] HANDLE                hTemplateFile,
  [in]           HANDLE                hTransaction,
  [in, optional] PUSHORT               pusMiniVersion,
                 PVOID                 lpExtendedParameter
);

Параметры

[in] lpFileName

Имя создаваемого или открываемого объекта.

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

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

Совет

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

Чтобы создать файловый поток, укажите имя файла, двоеточие, а затем имя потока. Дополнительные сведения см. в разделе Файловые потоки.

[in] dwDesiredAccess

Доступ к объекту , который можно обобщить как чтение, запись, оба или ни один (нуль). Чаще всего используются значения GENERIC_READ, GENERIC_WRITE или и то, и другое | (GENERIC_READGENERIC_WRITE). Дополнительные сведения см. в разделах Универсальные права доступа и Безопасность файлов и Права доступа.

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

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

[in] dwShareMode

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

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

Нельзя запросить режим общего доступа, который конфликтует с режимом доступа, указанным в открытом запросе с открытым дескриптором, так как это приведет к следующему нарушению общего доступа: ERROR_SHARING_VIOLATION. Дополнительные сведения см. в разделе Создание и открытие файлов.

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

Примечание Параметры общего доступа для каждого открытого дескриптора остаются в силе, пока этот дескриптор не будет закрыт, независимо от контекста процесса.

Значение	Значение
0 0x00000000	Отключает последующие операции открытия объекта для запроса любого типа доступа к объекту.
FILE_SHARE_DELETE 0x00000004	Позволяет последующим операциям открытия объекта запрашивать доступ к удалению. В противном случае другие процессы не смогут открыть объект, если они запрашивают удаление доступа. Если этот флаг не указан, но объект был открыт для удаления доступа, функция завершается ошибкой.
FILE_SHARE_READ 0x00000001	Позволяет последующим операциям открытия объекта запрашивать доступ на чтение. В противном случае другие процессы не смогут открыть объект, если они запрашивают доступ на чтение. Если этот флаг не указан, но объект был открыт для чтения, функция завершается ошибкой.
FILE_SHARE_WRITE 0x00000002	Позволяет последующим операциям открытия объекта запрашивать доступ на запись. В противном случае другие процессы не смогут открыть объект, если они запрашивают доступ на запись. Если этот флаг не указан, но объект был открыт для доступа на запись или имеет сопоставление файлов с доступом на запись, функция завершается сбоем.

[in, optional] lpSecurityAttributes

Указатель на структуру SECURITY_ATTRIBUTES , которая содержит необязательный дескриптор безопасности , а также определяет, может ли возвращаемый дескриптор наследоваться дочерними процессами. Параметр может иметь значение NULL.

Если параметр lpSecurityAttributes имеет значение NULL, дескриптор, возвращаемый CreateFileTransacted , не может быть унаследован дочерними процессами, которые может создать приложение, и объект, связанный с возвращенным дескриптором, получает дескриптор безопасности по умолчанию.

Член структуры bInheritHandle указывает, можно ли наследовать возвращенный дескриптор.

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

Если элемент lpSecurityDescriptor имеет значение NULL, объекту, связанному с возвращенным дескриптором, назначается дескриптор безопасности по умолчанию.

CreateFileTransacted игнорирует элемент lpSecurityDescriptor при открытии существующего файла, но продолжает использовать элемент bInheritHandle .

Дополнительные сведения см. в разделе Примечания этого раздела.

[in] dwCreationDisposition

Действие для выполнения с файлами, которые существуют и не существуют.

Дополнительные сведения см. в разделе Примечания этого раздела.

Этот параметр должен иметь одно из следующих значений, которые нельзя объединить.

Значение	Значение
CREATE_ALWAYS 2	Всегда создает новый файл. Если указанный файл существует и доступен для записи, функция усекает файл, функция выполняется успешно, а для кода последней ошибки задано значение ERROR_ALREADY_EXISTS (183). Если указанный файл не существует и является допустимым путем, создается новый файл, функция завершается успешно, а код последней ошибки равен нулю. Дополнительные сведения см. в разделе Примечания этого раздела.
CREATE_NEW 1	Создает новый файл, только если он еще не существует. Если указанный файл существует, функция завершается сбоем, а для кода последней ошибки задано значение ERROR_FILE_EXISTS (80). Если указанный файл не существует и является допустимым путем к расположению, доступному для записи, создается новый файл.
OPEN_ALWAYS 4	Всегда открывает файл. Если указанный файл существует, функция выполняется успешно, а для кода последней ошибки задано значение ERROR_ALREADY_EXISTS (183). Если указанный файл не существует и является допустимым путем к расположению, доступному для записи, функция создает файл, а для кода последней ошибки задано значение 0.
OPEN_EXISTING 3	Открывает файл или устройство, только если они существуют. Если указанный файл не существует, функция завершается ошибкой, и для кода последней ошибки задано значение ERROR_FILE_NOT_FOUND (2). Дополнительные сведения см. в разделе Примечания этого раздела.
TRUNCATE_EXISTING 5	Открывает файл и усекает его таким образом, чтобы его размер был равен нулю байт, только если он существует. Если указанный файл не существует, функция завершается ошибкой, и для кода последней ошибки задано значение ERROR_FILE_NOT_FOUND (2). Вызывающий процесс должен открыть файл с GENERIC_WRITE битом, заданным как часть параметра dwDesiredAccess .

[in] dwFlagsAndAttributes

Атрибуты и флаги файла , FILE_ATTRIBUTE_NORMAL являются наиболее распространенным значением по умолчанию.

Этот параметр может включать любое сочетание доступных атрибутов файла (FILE_ATTRIBUTE_*). Все остальные атрибуты файла переопределяют FILE_ATTRIBUTE_NORMAL.

Этот параметр также может содержать сочетания флагов (FILE_FLAG_) для управления поведением буферизации, режимами доступа и другими флагами специального назначения. Они объединяются со значениями FILE_ATTRIBUTE_ .

Этот параметр также может содержать сведения о качестве обслуживания системы безопасности (SQOS), указав флаг SECURITY_SQOS_PRESENT . Дополнительные сведения о флагах, связанных с SQOS, представлены в таблице после таблиц атрибутов и флагов.

Примечание

Когда CreateFileTransacted открывает существующий файл, он обычно объединяет флаги файла с атрибутами существующего файла и игнорирует все атрибуты файла, предоставленные в составе dwFlagsAndAttributes. Особые случаи описаны в статье Создание и открытие файлов.

Следующие атрибуты и флаги файлов используются только для файловых объектов, а не для объектов других типов, которые открывает CreateFileTransacted (дополнительные сведения можно найти в разделе Примечания этой статьи). Более расширенный доступ к атрибутам файла см. в разделе SetFileAttributes. Полный список всех атрибутов файла с их значениями и описаниями см. в разделе Константы атрибутов файлов.

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

Flag	Значение
FILE_FLAG_BACKUP_SEMANTICS 0x02000000	Файл открывается или создается для операции резервного копирования или восстановления. Система гарантирует, что вызывающий процесс переопределяет проверки безопасности файлов, если процесс имеет SE_BACKUP_NAME и SE_RESTORE_NAME привилегии. Дополнительные сведения см. в разделе Изменение привилегий в токене. Этот флаг необходимо задать, чтобы получить дескриптор каталога. Дескриптор каталога можно передать некоторым функциям вместо дескриптора файла. Дополнительные сведения см. в разделе Дескрипторы каталогов.
FILE_FLAG_DELETE_ON_CLOSE 0x04000000	Файл удаляется сразу после закрытия последнего дескриптора записи транзакций в файл при условии, что транзакция по-прежнему активна. Если файл помечен для удаления, а дескриптор записи транзакций по-прежнему открыт после завершения транзакции, файл не будет удален. При наличии открытых дескрипторов для файла вызов завершается ошибкой, если только они не были открыты в режиме общего доступа FILE_SHARE_DELETE . Последующие запросы на открытие файла завершатся сбоем, если только не указан режим совместного использования FILE_SHARE_DELETE.
FILE_FLAG_NO_BUFFERING 0x20000000	Файл открывается без системного кэширования. Этот флаг не влияет на кэширование жесткого диска или сопоставленные файлы в памяти. В сочетании с FILE_FLAG_OVERLAPPED флаг обеспечивает максимальную асинхронную производительность, так как операции ввода-вывода не зависят от синхронных операций диспетчера памяти. Однако некоторые операции ввода-вывода занимают больше времени, так как данные не хранятся в кэше. Кроме того, метаданные файла по-прежнему могут кэшироваться. Чтобы очистить метаданные на диск, используйте функцию FlushFileBuffers . Приложение должно соответствовать определенным требованиям при работе с файлами, которые открываются с помощью FILE_FLAG_NO_BUFFERING: Доступ к файлу должен начинаться со смещений в байтах в файле, которые являются целыми числами, кратными размеру сектора тома. Доступ к файлу должен осуществляться для количества байтов, которые являются целыми числами, кратными размеру сектора тома. Например, если размер сектора составляет 512 байт, приложение может запрашивать чтение и запись 512, 1024, 1536 или 2048 байт, но не 335, 981 или 7171 байт. Буферные адреса для операций чтения и записи должны быть выровнены по секторам, что означает выравнивание по адресам в памяти, которые являются целочисленными, кратными размеру сектора тома. В зависимости от диска это требование может не применяться. Один из способов выравнивания буферов по целым числам, кратным размеру сектора тома, заключается в использовании VirtualAlloc для выделения буферов. Он выделяет память, выравниваемую по адресам, которые являются целыми числами, кратными размеру страницы памяти операционной системы. Так как размер страницы памяти и сектора тома равен 2, эта память также выравнивается по адресам, которые являются целыми числами, кратными размеру сектора тома. Размер страниц памяти — 4 или 8 КБ; Секторы имеют размер 512 байт (жесткие диски), 2048 байт (CD) или 4096 байт (жесткие диски), поэтому секторы тома никогда не могут быть больше страниц памяти. Приложение может определить размер сектора тома, вызвав функцию GetDiskFreeSpace .
FILE_FLAG_OPEN_NO_RECALL 0x00100000	Запрашивается файл данных, но они должны по-прежнему находиться в удаленном хранилище. Его не следует передавать обратно в локальное хранилище. Этот флаг предназначен для использования удаленными системами хранения данных.
FILE_FLAG_OPEN_REPARSE_POINT 0x00200000	Обычная обработка точек повторного обработки не выполняется; CreateFileTransacted попытается открыть точку повторного аналитики. При открытии файла возвращается дескриптор файла независимо от того, работает ли фильтр, который управляет точкой повторного определения. Этот флаг нельзя использовать с флагом CREATE_ALWAYS . Если файл не является точкой повторного аналитики, этот флаг игнорируется.
FILE_FLAG_OVERLAPPED 0x40000000	Файл открывается или создается для асинхронного ввода-вывода. После завершения операции событие, указанное в структуре OVERLAPPED , задается в состояние сигнального. Операции, которые занимают значительное количество времени для обработки возвращаемых ERROR_IO_PENDING. Если этот флаг указан, файл можно использовать для одновременных операций чтения и записи. Система не поддерживает указатель файла, поэтому необходимо передать положение файла в функции чтения и записи в структуре OVERLAPPED или обновить указатель файла. Если этот флаг не указан, операции ввода-вывода сериализуются, даже если вызовы функций чтения и записи указывают структуру OVERLAPPED .
FILE_FLAG_POSIX_SEMANTICS 0x01000000	Доступ к файлу осуществляется в соответствии с правилами POSIX. Сюда входит разрешение нескольких файлов с именами, отличающимися только в случае, для файловой системы, поддерживающей такое именование. Будьте внимательны при использовании этого параметра, так как файлы, созданные с этим флагом, могут быть недоступны приложениям, написанным для MS-DOS или 16-разрядной версии Windows.
FILE_FLAG_RANDOM_ACCESS 0x10000000	Доступ к файлу осуществляется случайным образом. Система может использовать это в качестве указания для оптимизации кэширования файлов.
FILE_FLAG_SESSION_AWARE 0x00800000	Файл или устройство открывается с пониманием сеанса. Если этот флаг не указан, то устройства для сеанса (например, устройства, использующие перенаправление USB RemoteFX) не могут быть открыты процессами, выполняемыми в сеансе 0. Этот флаг не действует для вызывающих абонентов, не в сеансе 0. Этот флаг поддерживается только в серверных выпусках Windows. Windows Server 2008 R2 и Windows Server 2008: Этот флаг не поддерживается до Windows Server 2012.
FILE_FLAG_SEQUENTIAL_SCAN 0x08000000	Доступ к файлу должен осуществляться последовательно от начала до конца. Система может использовать это в качестве указания для оптимизации кэширования файлов. Если приложение перемещает указатель файла для произвольного доступа, оптимальное кэширование может не произойти. Однако правильная операция по-прежнему гарантируется. Указание этого флага может повысить производительность приложений, которые считывают большие файлы с помощью последовательного доступа. Повышение производительности может быть еще более заметным для приложений, которые считывают большие файлы в основном последовательно, но иногда пропускают небольшие диапазоны байтов. Этот флаг не действует, если файловая система не поддерживает кэшированные ввод-вывод и FILE_FLAG_NO_BUFFERING.
FILE_FLAG_WRITE_THROUGH 0x80000000	Операции записи не будут проходить через промежуточный кэш, они будут отправляться непосредственно на диск. Если FILE_FLAG_NO_BUFFERING также не указан, чтобы системное кэширование действовало, данные записываются в системный кэш, но сбрасываются на диск без задержки. Если также указано FILE_FLAG_NO_BUFFERING , чтобы системное кэширование не действовало, данные немедленно сбрасываются на диск без прохождения системного кэша. Операционная система также запрашивает запись кэша жесткого диска на постоянный носитель. Однако не все оборудование поддерживает эту возможность записи.

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

Флаг безопасности	Значение
SECURITY_ANONYMOUS	Олицетворяет клиента на уровне анонимного олицетворения.
SECURITY_CONTEXT_TRACKING	Режим отслеживания безопасности является динамическим. Если этот флаг не указан, режим отслеживания безопасности является статическим.
SECURITY_DELEGATION	Олицетворяет клиента на уровне олицетворения делегирования.
SECURITY_EFFECTIVE_ONLY	Серверу доступны только включенные аспекты контекста безопасности клиента. Если этот флаг не указан, будут доступны все аспекты контекста безопасности клиента. Это позволяет клиенту ограничить группы и привилегии, которые сервер может использовать при олицетворении клиента.
SECURITY_IDENTIFICATION	Олицетворяет клиента на уровне олицетворения идентификации.
SECURITY_IMPERSONATION	Олицетворение клиента на уровне олицетворения. Это поведение по умолчанию, если другие флаги не указаны вместе с флагом SECURITY_SQOS_PRESENT .

[in, optional] hTemplateFile

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

При открытии существующего файла CreateFileTransacted игнорирует файл шаблона.

При открытии нового файла с шифрованием EFS файл наследует список DACL от родительского каталога.

[in] hTransaction

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

[in, optional] pusMiniVersion

Открываемая миниверсия. Если транзакция, указанная в hTransaction , не является транзакцией, изменяющей файл, этот параметр должен иметь значение NULL. В противном случае этот параметр может быть идентификатором миниверсии, возвращаемым кодом элемента управления FSCTL_TXFS_CREATE_MINIVERSION , или одним из следующих значений.

Значение	Значение
TXFS_MINIVERSION_COMMITTED_VIEW 0x0000	Представление файла с момента его последней фиксации.
TXFS_MINIVERSION_DIRTY_VIEW 0xFFFF	Представление файла, изменяемого транзакцией.
TXFS_MINIVERSION_DEFAULT_VIEW 0xFFFE	Зафиксированное или грязное представление файла в зависимости от контекста. Транзакция, изменяющая файл, получает представление грязное, а транзакция, которая не изменяет файл, получает зафиксированное представление.

lpExtendedParameter

Этот параметр зарезервирован и должен иметь значение NULL.

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

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

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

При использовании дескриптора, возвращенного CreateFileTransacted, используйте транзакцийную версию функций файлового ввода-вывода вместо стандартных функций файлового ввода-вывода, где это необходимо. Дополнительные сведения см. в разделе Рекомендации по программированию для транзакционной NTFS.

При открытии дескриптора транзакций в каталоге этот дескриптор должен иметь разрешения FILE_WRITE_DATA (FILE_ADD_FILE) и FILE_APPEND_DATA (FILE_ADD_SUBDIRECTORY). Они включены в разрешения FILE_GENERIC_WRITE . Каталоги следует открывать с меньшим количеством разрешений, если вы просто используете дескриптор для создания файлов или подкаталогов; в противном случае могут возникнуть нарушения общего доступа.

Невозможно открыть файл с уровнем доступа FILE_EXECUTE , если этот файл является частью другой транзакции (то есть другое приложение открыло его путем вызова CreateFileTransacted). Это означает, что createFileTransacted завершается сбоем, если задан уровень доступа FILE_EXECUTE или FILE_ALL_ACCESS .

Когда приложение без транзакций вызывает CreateFileTransacted с MAXIMUM_ALLOWED , указанным для lpSecurityAttributes, дескриптор каждый раз открывается с тем же уровнем доступа. Когда транзакционное приложение вызывает CreateFileTransacted с MAXIMUM_ALLOWED , указанным для lpSecurityAttributes, открывается дескриптор с разными объемами доступа в зависимости от того, заблокирован ли файл транзакцией. Например, если вызывающее приложение имеет FILE_EXECUTE уровень доступа к файлу, приложение получает этот доступ только в том случае, если открываемый файл либо не заблокирован транзакцией, либо заблокирован транзакцией, а приложение уже является средством чтения для этого файла.

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

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

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

CreateFileTransacted нельзя использовать для управления сжатием файла или каталога. Дополнительные сведения см. в разделах Сжатие и распаковка файлов и Шифрование файлов.

Поведение символьной ссылки— если при вызове этой функции создается новый файл, поведение не изменяется.

Если указан FILE_FLAG_OPEN_REPARSE_POINT :

Если открывается существующий файл и это символьная ссылка, возвращенный дескриптор является дескриптором для символьной ссылки.
Если указаны TRUNCATE_EXISTING или FILE_FLAG_DELETE_ON_CLOSE , затронутый файл является символьной ссылкой.

Если FILE_FLAG_OPEN_REPARSE_POINT не указан:

Если открывается существующий файл и это символьная ссылка, возвращаемый дескриптор является дескриптором целевого объекта.
Если указаны CREATE_ALWAYS, TRUNCATE_EXISTING или FILE_FLAG_DELETE_ON_CLOSE , то целевым объектом является затронутый файл.

Запись в несколько секторов не гарантируется атомарной, если вы не используете транзакцию (т. е. созданный дескриптор является дескриптором транзакций). Запись с одним сектором является атомарной. Кэшированные записи в нескольких секторах не всегда могут быть записаны на диск; Поэтому укажите FILE_FLAG_WRITE_THROUGH , чтобы обеспечить запись всей многоканаловой записи на диск без кэширования.

Как упоминалось ранее, если параметр lpSecurityAttributes имеет значение NULL, дескриптор, возвращаемый командой CreateFileTransacted , не может наследоваться никакими дочерними процессами, которые может создать приложение. Также применяются следующие сведения об этом параметре:

Если параметр bInheritHandle не имеет значение FALSE, то дескриптор может быть унаследован. Поэтому крайне важно правильно инициализировать этот элемент структуры со значением FALSE , если дескриптор не должен быть наследуемым.
Списки управления доступом (ACL) в дескрипторе безопасности по умолчанию для файла или каталога наследуются от родительского каталога.
Целевая файловая система должна поддерживать безопасность файлов и каталогов, чтобы lpSecurityDescriptor влиял на них, что можно определить с помощью GetVolumeInformation.

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

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

Обратите внимание, что SMB 3.0 не поддерживает TxF.

Файлы

При попытке создать файл на диске, где нет гибких дисков, или дисководе компакт-дисков без компакт-диска, система отобразит сообщение о необходимости вставки диска или компакт-диска. Чтобы система не отображала это сообщение, вызовите функцию SetErrorMode с SEM_FAILCRITICALERRORS.

Дополнительные сведения см. в разделе Создание и открытие файлов.

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

Если вы вызываете CreateFileTransacted для файла, ожидающего удаления в результате предыдущего вызова DeleteFile, функция завершается ошибкой. Операционная система задерживает удаление файла, пока не будут закрыты все дескрипторы файла. GetLastError возвращает ERROR_ACCESS_DENIED.

Параметр dwDesiredAccess может быть равен нулю, что позволяет приложению запрашивать атрибуты файла без доступа к файлу, если приложение выполняется с соответствующими параметрами безопасности. Это полезно для проверки существования файла, не открывая его для чтения и (или) записи, а также для получения другой статистики о файле или каталоге. См. статьи Получение и настройка сведений о файле и GetFileInformationByHandle.

Когда приложение создает файл по сети, лучше использовать GENERIC_READ | GENERIC_WRITE , чем использовать только GENERIC_WRITE . Полученный код выполняется быстрее, так как перенаправитель может использовать диспетчер кэша и отправлять меньше SMB с большим объемом данных. Это сочетание также позволяет избежать проблем, из-за которых запись в файл по сети может иногда возвращать ERROR_ACCESS_DENIED.

Потоки файлов

В файловых системах NTFS можно использовать CreateFileTransacted для создания отдельных потоков в файле.

Дополнительные сведения см. в разделе Файловые потоки.

Каталоги

Приложение не может создать каталог с помощью CreateFileTransacted, поэтому для dwCreationDisposition в этом случае допустимо только значение OPEN_EXISTING. Чтобы создать каталог, приложение должно вызвать CreateDirectoryTransacted, CreateDirectory или CreateDirectoryEx.

Чтобы открыть каталог с помощью CreateFileTransacted, укажите флаг FILE_FLAG_BACKUP_SEMANTICS в составе dwFlagsAndAttributes. Соответствующие проверки безопасности по-прежнему применяются, если этот флаг используется без SE_BACKUP_NAME и SE_RESTORE_NAME привилегий.

При использовании CreateFileTransacted для открытия каталога во время дефрагментации тома файловой системы FAT или FAT32 не указывайте право доступа MAXIMUM_ALLOWED . В этом случае доступ к каталогу будет запрещен. Вместо этого укажите право доступа GENERIC_READ .

Дополнительные сведения см. в разделе Сведения об управлении каталогами.

Примечание

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

Требования

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