Функция CreateFileTransactedA (winbase.h)
[Корпорация Майкрософт настоятельно рекомендует разработчикам использовать альтернативные средства для достижения потребностей вашего приложения. Многие сценарии, для которые 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_READ | GENERIC_WRITE). Дополнительные сведения см. в
Если этот параметр равен нулю, приложение может запрашивать файл, каталог или атрибуты устройства без доступа к этому файлу или устройству. Дополнительные сведения см. в разделе "Примечания" этой статьи.
Невозможно запросить режим доступа, который конфликтует с режимом общего доступа, указанным в открытом запросе, который имеет открытый дескриптор. Дополнительные сведения см. в создании и открытии файлов.
[in] dwShareMode
Режим общего доступа объекта, который может быть считываем, записывать и удалять, все из них или нет (см. следующую таблицу).
Если этот параметр равен нулю и CreateFileTransacted выполнен успешно, объект нельзя открыть повторно, пока не будет закрыт дескриптор. Дополнительные сведения см. в разделе "Примечания" этой статьи.
Невозможно запросить режим общего доступа, который конфликтует с режимом доступа, указанным в открытом запросе с открытым дескриптором, так как это приведет к следующему нарушению общего доступа: ERROR_SHARING_VIOLATION. Дополнительные сведения см. в создании и открытии файлов.
Чтобы включить общий доступ к объекту, а другой процесс открыт, используйте сочетание одного или нескольких следующих значений, чтобы указать режим доступа, который он может запросить, чтобы открыть объект.
[in, optional] lpSecurityAttributes
Указатель на структуру SECURITY_ATTRIBUTES, содержащую необязательный дескриптор безопасности, а также определяет, можно ли наследовать возвращенный дескриптор дочерними процессами. Параметр может быть null.
Если параметр
Элемент bInheritHandle структуры указывает, можно ли наследовать возвращенный дескриптор.
Элемент структуры
Если элемент lpSecurityDescriptor NULL, объект, связанный с возвращенным дескриптором безопасности, назначается дескриптор безопасности по умолчанию.
CreateFileTransacted игнорирует элемент lpSecurityDescriptor при открытии существующего файла, но продолжает использовать элемент bInheritHandle.
Дополнительные сведения см. в разделе "Примечания" этой статьи.
[in] dwCreationDisposition
Действие, которое необходимо предпринять для файлов, которые существуют и не существуют.
Дополнительные сведения см. в разделе "Примечания" этой статьи.
Этот параметр должен быть одним из следующих значений, которые нельзя объединить.
[in] dwFlagsAndAttributes
Атрибуты и флаги файла, FILE_ATTRIBUTE_NORMAL является наиболее распространенным значением по умолчанию.
Этот параметр может включать любое сочетание доступных атрибутов файла (FILE_ATTRIBUTE_*). Все остальные атрибуты файла переопределяют FILE_ATTRIBUTE_NORMAL.
Этот параметр также может содержать сочетания флагов (FILE_FLAG_) для управления поведением буферизации, режимами доступа и другими флагами специального назначения. Они объединяются с любыми значениями FILE_ATTRIBUTE_.
Этот параметр также может содержать сведения о качестве обслуживания (SQOS), указав флаг SECURITY_SQOS_PRESENT. Дополнительные сведения о флагах, связанных с SQOS, представлены в таблице ниже атрибутов и таблиц флагов.
Когда CreateFileTransacted открывает существующий файл, он обычно объединяет флаги файлов с атрибутами файла существующего файла и игнорирует атрибуты файлов, предоставленные в рамках dwFlagsAndAttributes. Специальные случаи подробно описаны в создании и открытии файлов.
| Флаг | Значение |
|---|---|
|
Файл открывается или создается для операции резервного копирования или восстановления. Система гарантирует, что вызывающий процесс переопределяет проверку безопасности файлов при SE_BACKUP_NAME и привилегиях SE_RESTORE_NAME. Дополнительные сведения см. в разделе Изменение привилегий вмаркера.
Этот флаг необходимо задать для получения дескриптора в каталог. Дескриптор каталога можно передать некоторым функциям вместо дескриптора файлов. Дополнительные сведения см. в разделе Дескрипторы каталогов. |
|
Файл должен быть удален сразу после закрытия последнего дескриптора транзакционного модуля записи в файл, если транзакция по-прежнему активна. Если файл помечен для удаления и дескриптор записи транзакций по-прежнему открыт после завершения транзакции, файл не будет удален.
Если в файле есть открытые дескрипторы, вызов завершается ошибкой, если они не были открыты с режимом общего доступа FILE_SHARE_DELETE. Последующие открытые запросы для файла завершаются ошибкой, если не указан режим общего доступа FILE_SHARE_DELETE. |
|
Файл открывается без кэширования системы. Этот флаг не влияет на кэширование жесткого диска или сопоставленные с памятью файлы. При сочетании с FILE_FLAG_OVERLAPPEDфлаг обеспечивает максимальную асинхронную производительность, так как операции ввода-вывода не зависят от синхронных операций диспетчера памяти.
Однако некоторые операции ввода-вывода занимают больше времени, так как данные не хранятся в кэше. Кроме того, метаданные файла могут кэшироваться. Чтобы очистить метаданные на диск, используйте функцию FlushFileBuffers.
Приложение должно соответствовать определенным требованиям при работе с файлами, открывающимися с помощью FILE_FLAG_NO_BUFFERING:
Приложение может определить размер сектора томов, вызвав функцию GetDiskFreeSpace. |
|
Запрашивается файл, но он должен продолжать находиться в удаленном хранилище. Его не следует передавать обратно в локальное хранилище. Этот флаг предназначен для использования в системах удаленного хранения. |
|
Обычное перепарировать точку не будет выполняться; CreateFileTransacted попытается открыть точку повторного выполнения. При открытии файла возвращается дескриптор файла, независимо от того, работает ли фильтр, который управляет точкой повторного выполнения. Этот флаг нельзя использовать с флагом CREATE_ALWAYS. Если файл не является точкой перепарирования, этот флаг игнорируется. |
|
Файл открывается или создается для асинхронного ввода-вывода. После завершения операции событие, указанное в структуре OVERLAPPED, устанавливается в сигнальное состояние. Операции, которые занимают значительное время для обработки возврата ERROR_IO_PENDING.
Если этот флаг указан, файл можно использовать для одновременных операций чтения и записи. Система не поддерживает указатель на файл, поэтому необходимо передать положение файла функциям чтения и записи в структуре OVERLAPPED или обновить указатель файла. Если этот флаг не указан, операции ввода-вывода сериализуются, даже если вызовы функций чтения и записи указывают структуру OVERLAPPED. |
|
Доступ к файлу осуществляется в соответствии с правилами POSIX. Это включает в себя разрешение нескольких файлов с именами, отличающимися только в случае, для файловой системы, поддерживающей это именование. Используйте осторожность при использовании этого параметра, так как файлы, созданные с помощью этого флага, могут быть недоступны приложениями, написанными для MS-DOS или 16-разрядных Windows. |
|
Доступ к файлу осуществляется случайным образом. Система может использовать это в качестве указания для оптимизации кэширования файлов. |
|
Файл или устройство открывается с помощью осведомленности о сеансе. Если этот флаг не указан, то для каждого сеанса (например, устройства с использованием перенаправления USB RemoteFX) невозможно открыть процессами, выполняемыми в сеансе 0.
Этот флаг не действует для вызывающих абонентов в сеансе 0. Этот флаг поддерживается только в выпусках сервера Windows.
Windows Server 2008 R2 и Windows Server 2008: этот флаг не поддерживается до Windows Server 2012. |
|
Доступ к файлу осуществляется последовательно с начала до конца. Система может использовать это в качестве указания для оптимизации кэширования файлов. Если приложение перемещает указатель на файл для случайного доступа, оптимальное кэширование может не произойти. Однако правильная операция по-прежнему гарантируется.
Указание этого флага может повысить производительность приложений, которые считывают большие файлы с помощью последовательного доступа. Повышение производительности может быть еще более заметным для приложений, которые считывают большие файлы в основном последовательно, но иногда пропускают небольшие диапазоны байтов. Этот флаг не действует, если файловая система не поддерживает кэшированные операции ввода-вывода и FILE_FLAG_NO_BUFFERING. |
|
Операции записи не будут проходить через промежуточный кэш, они будут переходить непосредственно на диск.
Если FILE_FLAG_NO_BUFFERING не указано, поэтому кэширование системы действует, данные записываются в системный кэш, но сбрасываются на диск без задержки. Если FILE_FLAG_NO_BUFFERING также указан, поэтому кэширование системы не действует, данные немедленно сбрасываются на диск без прохождения системного кэша. Операционная система также запрашивает кэш жесткого диска на постоянный носитель. Однако не все оборудование поддерживает эту возможность записи. |
Параметр
[in, optional] hTemplateFile
Допустимый дескриптор файла шаблона с правом доступа GENERIC_READ. Файл шаблона предоставляет атрибуты файла и расширенные атрибуты для создаваемого файла. Этот параметр может быть NULL.
При открытии существующего файла CreateFileTransacted игнорирует файл шаблона.
При открытии нового зашифрованного файла EFS файл наследует DACL из родительского каталога.
[in] hTransaction
Дескриптор транзакции. Этот дескриптор возвращается функцией CreateTransaction.
[in, optional] pusMiniVersion
Миниверсия, открываемая. Если транзакция, указанная в hTransaction, не является транзакцией, изменяющей файл, этот параметр должен быть null. В противном случае этот параметр может быть идентификатором миниверсии, возвращаемым кодом элемента управления FSCTL_TXFS_CREATE_MINIVERSION или одним из следующих значений.
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 для файла, приложение получает доступ только в том случае, если открытый файл либо не заблокирован транзакцией, либо заблокирован транзакцией, либо заблокирован транзакцией, и приложение уже является трансактированным средством чтения для этого файла.
Полный описание транзакционных операций см. в NTFS.
Используйте функцию CloseHandle, чтобы закрыть дескриптор объекта, возвращаемый CreateFileTransacted, если дескриптор больше не нужен, а до фиксации или отката транзакции.
Некоторые файловые системы, такие как файловая система NTFS, поддерживают сжатие или шифрование отдельных файлов и каталогов. В томах, отформатированных для такой файловой системы, новый файл наследует атрибуты сжатия и шифрования своего каталога.
Нельзя использовать CreateFileTransacted для управления сжатием файла или каталога. Дополнительные сведения см. в
Поведение символьной связи. Если вызов этой функции создает новый файл, в поведении нет изменений.
Если указан FILE_FLAG_OPEN_REPARSE_POINT:
- Если существующий файл открыт и является символьной ссылкой, возвращенный дескриптором является дескриптор символьной ссылкой.
- Если указаны TRUNCATE_EXISTING или FILE_FLAG_DELETE_ON_CLOSE, затронутый файлом является символьная ссылка.
- Если существующий файл открыт и является символьной ссылкой, возвращенный дескриптором является дескриптор целевого объекта.
- Если указаны CREATE_ALWAYS, TRUNCATE_EXISTINGили FILE_FLAG_DELETE_ON_CLOSE, затронутый файлом является целевой объект.
Как упоминалось ранее, если параметр lpSecurityAttributes имеет значение NULL, то дескриптор, возвращаемый CreateFileTransacted, не может быть унаследован любым дочерним процессом, который может создать приложение. Следующие сведения об этом параметре также применяются:
- Если bInheritHandle не FALSE, что является любым ненулевом значением, то дескриптор может быть унаследован. Поэтому важно правильно инициализировать этот элемент структуры для FALSE, если дескриптор не будет наследуемым.
- Списки управления доступом (ACL) в дескрипторе безопасности по умолчанию для файла или каталога наследуются от родительского каталога.
- Целевая файловая система должна поддерживать безопасность файлов и каталогов для lpSecurityDescriptor, чтобы иметь влияние на них, которые можно определить с помощью GetVolumeInformation
| Технологии | Поддержанный |
|---|---|
| Протокол SMB 3.0 | Нет |
| Отработка отказа SMB 3.0 (TFO) | Нет |
| SMB 3.0 с масштабируемыми общими папками (SO) | Нет |
| Файловая система общего тома кластера (CSVFS) | Нет |
| Отказоустойчивая файловая система (ReFS) | Нет |
Обратите внимание, что SMB 3.0 не поддерживает TxF.
файлы
Если вы попытаетесь создать файл на диске с флоппи-диском, который не имеет диска floppy или диска CD-ROM, который не имеет компакт-диска, система отображает сообщение для пользователя, чтобы вставить диск или компакт-диск. Чтобы предотвратить отображение этого сообщения системой, вызовите функцию SetErrorMode с SEM_FAILCRITICALERRORS.Дополнительные сведения см. в создании и открытии файлов.
Если вы переименовываете или удаляете файл, а затем восстанавливаете его в ближайшее время, система выполняет поиск в кэше сведений о файлах для восстановления. Кэшированные сведения включают в себя пару коротких и длинных имен и время создания.
При вызове CreateFileTransacted в файле, ожидающем удаления в результате предыдущего вызова DeleteFile, функция завершается ошибкой. Операционная система задерживает удаление файлов до закрытия всех дескрипторов файла. GetLastError возвращает ERROR_ACCESS_DENIED.
Параметр dwDesiredAccess может быть нулевым, что позволяет приложению запрашивать атрибуты файлов без доступа к файлу, если приложение работает с соответствующими параметрами безопасности. Это полезно для проверки существования файла, не открывая его для доступа на чтение и (или) запись, или получить другую статистику о файле или каталоге. См. получение и настройка сведений о файлах и GetFileInformationByHandle.
Когда приложение создает файл в сети, лучше использовать GENERIC_READ | GENERIC_WRITE, чем использовать только GENERIC_WRITE. Результирующий код быстрее, так как перенаправитель может использовать диспетчер кэша и отправлять меньше SMOB-объектов с большим количеством данных. Это сочетание также позволяет избежать проблемы, при которой запись в файл в сети может иногда возвращать ERROR_ACCESS_DENIED.
файловых потоков
В файловых системах NTFS можно использовать CreateFileTransacted для создания отдельных потоков в файле.Дополнительные сведения см. в разделе файловых потоков.
Каталоги
Приложение не может создать каталог с помощью CreateFileTransacted, поэтому только значение OPEN_EXISTING допустимо для dwCreationDisposition для этого варианта использования. Чтобы создать каталог, приложение должно вызвать 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 [только классические приложения] |
| целевая платформа | Виндоус |
| заголовка | winbase.h (включая Windows.h) |
| библиотеки |
Kernel32.lib |
| DLL | Kernel32.dll |
См. также
права на безопасность и доступ к файлам
Функции
разделах обзора
Рекомендации по программированию транзакций NTFS