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

Статья
03/14/2023

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

При вызове из приложения Магазина Windows CreateFile2 упрощается. Вы можете открывать только файлы или каталоги в каталогах ApplicationData.LocalFolder или Package.InstalledLocation. Нельзя открывать именованные каналы или почтовые ящики или создавать зашифрованные файлы (FILE_ATTRIBUTE_ENCRYPTED).

Примечание Здесь мы ссылаемся на локальную папку приложения и расположение установленного пакета, а не дополнительные пакеты в графе пакетов, например пакеты ресурсов. CreateFile2 не поддерживает открытие файлов в дополнительных пакетах на графе пакетов. Например, предположим, что приложение имеет зависимость от WinJS. Приложение может вызывать CreateFile2, чтобы открыть файл в пакете, но не в пакете WinJS.

Чтобы выполнить эту операцию как транзакцию, которая приводит к дескриптору, который может использоваться для транзакций ввода-вывода, используйте функцию CreateFileTransacted.

Синтаксис

HANDLE CreateFile2(
  [in]           LPCWSTR                           lpFileName,
  [in]           DWORD                             dwDesiredAccess,
  [in]           DWORD                             dwShareMode,
  [in]           DWORD                             dwCreationDisposition,
  [in, optional] LPCREATEFILE2_EXTENDED_PARAMETERS pCreateExParams
);

Параметры

[in] lpFileName

Имя файла или устройства, которое нужно создать или открыть.

Дополнительные сведения о специальных именах устройств см. в статье Определениеимени устройства MS-DOS.

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

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

[in] dwDesiredAccess

Запрошенный доступ к файлу или устройству, который можно суммировать как чтение, запись или ни один из них.

Наиболее часто используются значения GENERIC_READ, GENERIC_WRITEили обоих (GENERIC_READ | GENERIC_WRITE). Дополнительные сведения см. в универсальных прав доступа, прав доступа , константы прав доступа файлови ACCESS_MASK.

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

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

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

[in] dwShareMode

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

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

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

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

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

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

[in] dwCreationDisposition

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

Для устройств, отличных от файлов, этот параметр обычно имеет значение OPEN_EXISTING.

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

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

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

[in, optional] pCreateExParams

Указатель на необязательную структуру CREATEFILE2_EXTENDED_PARAMETERS.

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

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

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

Замечания

Чтобы скомпилировать приложение, использующее функцию CreateFile2, определите макрос _WIN32_WINNT как 0x0602 или более поздней версии. Дополнительные сведения см. в разделе Использование заголовков Windows.

CreateFile2 поддерживает взаимодействие с файлами и большинство других типов устройств ввода-вывода и механизмов, доступных разработчикам Windows. В этом разделе рассматриваются различные проблемы, которые могут возникнуть при использовании CreateFile2 в разных контекстах и с различными типами ввода-вывода. Текст пытается использовать слово файл только при ссылке на данные, хранящиеся в фактическом файле в файловой системе. Однако некоторые виды использования файла могут ссылаться на объект ввода-вывода, поддерживающий механизмы, подобные файлам. Это либеральное использование термина файла особенно распространено в постоянных именах и именах параметров из-за ранее упомянутых исторических причин.

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

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

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

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

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

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

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

поведение символьного канала

Если вызов этой функции создает файл, изменения в поведении не изменяются. Кроме того, рассмотрим следующие сведения о флаге FILE_FLAG_OPEN_REPARSE_POINT для dwFileFlags члена структуры CREATEFILE2_EXTENDED_PARAMETERS, переданной в параметре pCreateExParams:

Если указан 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, затронутый файлом является целевой объект.

файлы

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

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

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

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

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

файловых потоков

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

Каталоги

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

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

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

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

физических дисков и томов

Прямой доступ к диску или тому ограничен.

Функцию CreateFile2 можно использовать для открытия физического диска или тома, который возвращает дескриптор прямого доступа к устройству хранения (DASD), который можно использовать с функцией DeviceIoControl. Это позволяет получить доступ к диску или тому напрямую, например к таким метаданным диска, как таблица секций. Однако этот тип доступа также предоставляет диск или том потенциальной потере данных, так как неправильное запись на диск с помощью этого механизма может сделать его содержимое недоступным для операционной системы. Чтобы обеспечить целостность данных, обязательно ознакомитесь с DeviceIoControl и как другие API работают по-разному с дескриптором прямого доступа, а не с дескриптором файловой системы.

Для успешного выполнения такого вызова необходимо выполнить следующие требования:

Вызывающий объект должен иметь права администратора. Дополнительные сведения см. в разделе Выполнение с специальными привилегиями.
Параметр dwCreationDisposition должен иметь флаг OPEN_EXISTING.
При открытии тома или диска floppy параметр dwShareMode должен иметь флаг FILE_SHARE_WRITE.

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

При открытии физического диска x:строка lpFileName должна быть следующей формой: "\\.\.\PhysicalDriveX". Номера жестких дисков начинаются с нуля. В следующей таблице показаны некоторые примеры строк физического диска.

Струна	Значение
"\\.\PhysicalDrive0"	Открывает первый физический диск.
"\\.\PhysicalDrive2"	Открывает третий физический диск.

Чтобы получить идентификатор физического диска для тома, откройте дескриптор тома и вызовите функцию DeviceIoControl с IOCTL_VOLUME_GET_VOLUME_DISK_EXTENTS. Этот код элемента управления возвращает номер диска и смещение для каждого из одного или нескольких экстентов тома; Том может охватывать несколько физических дисков.

Пример открытия физического диска см. в разделе вызовов DeviceIoControl.

При открытии тома или съемных носителей (например, дискового диска или диска флэш-памяти) строка lpFileName должна быть следующей формой: "\\.\X:". Не используйте конечную обратную косую черту (\), которая указывает корневой каталог диска. В следующей таблице показаны некоторые примеры строк диска.

Струна	Значение
"\\.\A:"	Открывает диск floppy A.
"\\.\C:"	Открывает том C:
"\\.\C:\"	Открывает файловую систему тома C:

Вы также можете открыть том, ссылаясь на его имя тома. Дополнительные сведения см. в разделе Именование тома.

Том содержит одну или несколько подключенных файловых систем. Дескриптор тома можно открывать как некшированные по усмотрению конкретной файловой системы, даже если параметр без кэширования не указан в CreateFile2. Следует предположить, что все файловые системы Майкрософт открывают тома как некашированные. Ограничения на некачивание операций ввода-вывода для файлов также применяются к томам.

Файловая система может или не требует выравнивания буфера, даже если данные не кэшируются. Однако если параметр без кэширования указан при открытии тома, выравнивание буфера применяется независимо от файловой системы тома. Рекомендуется использовать для всех файловых систем, которые вы открываете тома как некашированные, и следуйте ограничениям ввода-вывода без кэширования.

Примечание Для чтения или записи в последние несколько секторов тома необходимо вызвать DeviceIoControl и указать FSCTL_ALLOW_EXTENDED_DASD_IO. Это сигнализирует драйверу файловой системы не выполнять никаких проверок границ ввода-вывода для вызовов чтения или записи секций. Вместо этого проверки границ выполняются драйвером устройства.

устройство changer

Коды управления IOCTL_CHANGER_* для DeviceIoControl принимают дескриптор на устройство изменения. Чтобы открыть устройство изменения, используйте имя файла следующей формы: "\\.\\Changerx", где x — это число, указывающее, какое устройство нужно открыть, начиная с нуля. Чтобы открыть устройство с изменением нуля в приложении, написанном на C или C++, используйте следующее имя файла: "\\\\.\\Changer0".

ленточные диски

Вы можете открыть ленточные диски с помощью имени файла следующей формы: "\\.\TAPEx", где x — это число, указывающее, какой диск следует открыть, начиная с нуля ленточного диска. Чтобы открыть ленточный диск ноль в приложении, написанном на C или C++, используйте следующее имя файла: "\\\\.\\TAPE0".

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

ресурсы связи

Функция CreateFile2 может создать дескриптор для ресурса связи, например com1 последовательного порта. Для ресурсов связи параметр dwCreationDisposition должен быть OPEN_EXISTING, параметр dwShareMode должен быть равен нулю (монопольный доступ), а параметр hTemplateFileдолжен быть NULL. Можно указать доступ на чтение, запись или запись, а дескриптор можно открыть для перекрывающихся операций ввода-вывода.

Чтобы указать номер COM-порта больше 9, используйте следующий синтаксис: \.\COM10. Этот синтаксис подходит для всех номеров портов и оборудования, позволяющих указывать номера портов COM.

Дополнительные сведения об обмене данными см. в связи.

консоли

Функция CreateFile2 может создать дескриптор для входных данных консоли (CONIN$). Если процесс имеет открытый дескриптор в результате наследования или дублирования, он также может создать дескриптор активного буфера экрана (CONOUT$). Вызывающий процесс должен быть присоединен к унаследованной консоли или одному, выделенному функцией AllocConsole. Для дескрипторов консоли задайте параметры CreateFile2 следующим образом.

Параметры	Ценность
lpFileName	Используйте значение CONIN$ для указания входных данных консоли. Используйте значение CONOUT$ для указания выходных данных консоли. CONIN$ получает дескриптор входного буфера консоли, даже если функция setStdHandle перенаправляет стандартный дескриптор ввода. Чтобы получить стандартный дескриптор ввода, используйте функцию GetStdHandle. CONOUT$ получает дескриптор активного буфера экрана, даже если SetStdHandle перенаправляет стандартный дескриптор вывода. Чтобы получить стандартный дескриптор вывода, используйте GetStdHandle.
dwDesiredAccess	`GENERIC_READ \| GENERIC_WRITE` предпочтительнее, но любой из них может ограничить доступ.
dwShareMode	При открытии CONIN$укажите FILE_SHARE_READ. При открытии CONOUT$укажите FILE_SHARE_WRITE. Если вызывающий процесс наследует консоль или дочерний процесс должен иметь доступ к консоли, этот параметр должен быть `FILE_SHARE_READ \| FILE_SHARE_WRITE`.
dwCreationDisposition	Чтобы открыть консоль, необходимо указать OPEN_EXISTING при использовании CreateFile 2.

Задайте элементы структуры CREATEFILE2_EXTENDED_PARAMETERS, переданной в параметре pCreateExParams следующим образом.

Члены	Ценность
lpSecurityAttributes	Если требуется наследовать консоль, bInheritHandle член структуры SECURITY_ATTRIBUTES должен быть TRUE.
dwFileAttributes dwFileFlags dwSecurityQosFlags hTemplateFile	Игнорировать.

В следующей таблице показаны различные параметры dwDesiredAccess и lpFileName.

lpFileName	dwDesiredAccess	Результат
"CON"	GENERIC_READ	Открывает консоль для ввода.
"CON"	GENERIC_WRITE	Открывает консоль для выходных данных.
"CON"	`GENERIC_READ \| GENERIC_WRITE`	Вызывает сбой CreateFile2; GetLastError возвращает ERROR_FILE_NOT_FOUND.

Mailslots

Если CreateFile2 открывает конец почтового объекта, функция возвращает INVALID_HANDLE_VALUE, если клиент mailslot пытается открыть локальный почтовый слоток перед тем, как сервер mailslot создал его с помощью функции CreateMailSlot.

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

каналы

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

Если функция CreateNamedPipe не была успешно вызвана на сервере до этой операции, канал не будет существовать и CreateFile2 завершится ошибкой с ERROR_FILE_NOT_FOUND.

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

Дополнительные сведения см. в каналах.

Требования

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