Функция CreateFile2 (fileapi.h)
Создает или открывает файл или устройство ввода-вывода. Наиболее часто используемые устройства ввода-вывода: файл, поток файлов, каталог, физический диск, том, буфер консоли, ленточный диск, ресурс связи, mailslot и канал. Функция возвращает дескриптор, который можно использовать для доступа к файлу или устройству для различных типов операций ввода-вывода в зависимости от файла или устройства, а также флагов и атрибутов, указанных.
При вызове из приложения Магазина Windows CreateFile2 упрощается. Вы можете открывать только файлы или каталоги в каталогах ApplicationData.LocalFolder или Package.InstalledLocation. Нельзя открывать именованные каналы или почтовые ящики или создавать зашифрованные файлы (FILE_ATTRIBUTE_ENCRYPTED).
Синтаксис
HANDLE CreateFile2(
[in] LPCWSTR lpFileName,
[in] DWORD dwDesiredAccess,
[in] DWORD dwShareMode,
[in] DWORD dwCreationDisposition,
[in, optional] LPCREATEFILE2_EXTENDED_PARAMETERS pCreateExParams
);
Параметры
[in] lpFileName
Имя файла или устройства, которое нужно создать или открыть.
Дополнительные сведения о специальных именах устройств см. в статье Определениеимени устройства MS-DOS.
Чтобы создать поток файлов, укажите имя файла, двоеточие и имя потока. Дополнительные сведения см. в разделе файловых потоков.
[in] dwDesiredAccess
Запрошенный доступ к файлу или устройству, который можно суммировать как чтение, запись или ни один из них.
Наиболее часто используются значения GENERIC_READ, GENERIC_WRITEили обоих (GENERIC_READ | GENERIC_WRITE). Дополнительные сведения см. в
Если этот параметр равен нулю, приложение может запрашивать определенные метаданные, такие как файл, каталог или атрибуты устройства, без доступа к этому файлу или устройству, даже если GENERIC_READ доступ был бы отклонен.
Невозможно запросить режим доступа, который конфликтует с режимом общего доступа, указанным параметром dwShareMode в открытом запросе, который уже имеет открытый дескриптор.
Дополнительные сведения см. в разделе "Примечания" этого раздела и создание и открытие файлов.
[in] dwShareMode
Запрошенный режим общего доступа к файлу или устройству, который может быть считываем, записывать и удалять, все из них или нет (см. следующую таблицу). Запросы доступа к атрибутам или расширенным атрибутам не влияют на этот флаг.
Если этот параметр равен нулю и CreateFile2 выполнен успешно, файл или устройство невозможно открыть повторно, пока не будет закрыт дескриптор файла или устройства. Дополнительные сведения см. в разделе "Примечания".
Невозможно запросить режим общего доступа, который конфликтует с режимом доступа, указанным в существующем запросе с открытым дескриптором.
Чтобы включить общий доступ к файлу или устройству, а другой процесс открыт для файла или устройства, используйте совместимое сочетание одного или нескольких следующих значений. Дополнительные сведения о допустимых сочетаниях этого параметра с параметром dwDesiredAccess см. в разделе Создание и открытие файлов.
[in] dwCreationDisposition
Действие, выполняемое на файле или устройстве, которое существует или не существует.
Для устройств, отличных от файлов, этот параметр обычно имеет значение OPEN_EXISTING.
Дополнительные сведения см. в разделе "Примечания".
Этот параметр должен быть одним из следующих значений, которые нельзя объединить.
[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.
| Технологии | Поддержанный |
|---|---|
| Протокол 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.
| Струна | Значение |
|---|---|
| "\\.\PhysicalDrive0" | Открывает первый физический диск. |
| "\\.\PhysicalDrive2" | Открывает третий физический диск. |
Чтобы получить идентификатор физического диска для тома, откройте дескриптор тома и вызовите функцию DeviceIoControl
Пример открытия физического диска см. в разделе вызовов DeviceIoControl.
При открытии тома или съемных носителей (например, дискового диска или диска флэш-памяти) строка lpFileName должна быть следующей формой: "\\.\X:". Не используйте конечную обратную косую черту (\), которая указывает корневой каталог диска. В следующей таблице показаны некоторые примеры строк диска.
| Струна | Значение |
|---|---|
| "\\.\A:" | Открывает диск floppy A. |
| "\\.\C:" | Открывает том C: |
| "\\.\C:\" | Открывает файловую систему тома C: |
Вы также можете открыть том, ссылаясь на его имя тома. Дополнительные сведения см. в разделе Именование тома.
Том содержит одну или несколько подключенных файловых систем. Дескриптор тома можно открывать как некшированные по усмотрению конкретной файловой системы, даже если параметр без кэширования не указан в CreateFile2. Следует предположить, что все файловые системы Майкрософт открывают тома как некашированные. Ограничения на некачивание операций ввода-вывода для файлов также применяются к томам.
Файловая система может или не требует выравнивания буфера, даже если данные не кэшируются. Однако если параметр без кэширования указан при открытии тома, выравнивание буфера применяется независимо от файловой системы тома. Рекомендуется использовать для всех файловых систем, которые вы открываете тома как некашированные, и следуйте ограничениям ввода-вывода без кэширования.
устройство changer
Коды управления IOCTL_CHANGER_* для DeviceIoControl принимают дескриптор на устройство изменения. Чтобы открыть устройство изменения, используйте имя файла следующей формы: "\\.\\Changerx", где x — это число, указывающее, какое устройство нужно открыть, начиная с нуля. Чтобы открыть устройство с изменением нуля в приложении, написанном на C или C++, используйте следующее имя файла: "\\\\.\\Changer0".ленточные диски
Вы можете открыть ленточные диски с помощью имени файла следующей формы: "\\.\TAPEx", где x — это число, указывающее, какой диск следует открыть, начиная с нуля ленточного диска. Чтобы открыть ленточный диск ноль в приложении, написанном на C или C++, используйте следующее имя файла: "\\\\.\\TAPE0".Дополнительные сведения см. в разделе резервного копирования.
ресурсы связи
Функция CreateFile2 может создать дескриптор для ресурса связи, например com1 последовательного порта. Для ресурсов связи параметрЧтобы указать номер COM-порта больше 9, используйте следующий синтаксис: \.\COM10. Этот синтаксис подходит для всех номеров портов и оборудования, позволяющих указывать номера портов COM.
Дополнительные сведения об обмене данными см. в связи.
консоли
Функция CreateFile2 может создать дескриптор для входных данных консоли (CONIN$). Если процесс имеет открытый дескриптор в результате наследования или дублирования, он также может создать дескриптор активного буфера экрана (CONOUT$). Вызывающий процесс должен быть присоединен к унаследованной консоли или одному, выделенному функцией| Параметры | Ценность |
|---|---|
| lpFileName |
Используйте значение CONIN$ для указания входных данных консоли.
Используйте значение CONOUT$ для указания выходных данных консоли. CONIN$ получает дескриптор входного буфера консоли, даже если функция setStdHandle CONOUT$ получает дескриптор активного буфера экрана, даже если SetStdHandle перенаправляет стандартный дескриптор вывода. Чтобы получить стандартный дескриптор вывода, используйте GetStdHandle. |
| dwDesiredAccess |
GENERIC_READ | GENERIC_WRITE предпочтительнее, но любой из них может ограничить доступ.
|
| dwShareMode |
При открытии CONIN$укажите FILE_SHARE_READ. При открытии CONOUT$укажите 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 |
См. также
о управления каталогами
о управления томами
создание, удаление и обслуживание файлов
управления вводом и выводом устройств (IOCTL)
права на безопасность и доступ к файлам
Функции
Основные понятия ввода-вывода
получение и настройка сведений о файлах
разделах обзора