Функция CreateFile2 (fileapi.h)
Создает или открывает файл или устройство ввода-вывода. Наиболее часто используемые устройства ввода-вывода: файл, файловый поток, каталог, физический диск, том, буфер консоли, ленточный накопитель, ресурс связи, почтовый слопот и канал. Функция возвращает дескриптор, который можно использовать для доступа к файлу или устройству для различных типов операций ввода-вывода в зависимости от файла или устройства, а также указанных флагов и атрибутов.
При вызове из приложения Магазина 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). Дополнительные сведения см. в разделах Общие права доступа, Безопасность файлов и Права доступа, Константы прав доступа к файлам и ACCESS_MASK.
Если этот параметр равен нулю, приложение может запрашивать определенные метаданные, такие как атрибуты файла, каталога или устройства, без доступа к этому файлу или устройству, даже если GENERIC_READ доступ был бы запрещен.
Невозможно запросить режим доступа, конфликтующий с режимом общего доступа, заданным параметром dwShareMode в открытом запросе, который уже имеет открытый дескриптор.
Дополнительные сведения см. в разделе Примечания этого раздела и в разделе Создание и открытие файлов.
[in] dwShareMode
Запрошенный режим общего доступа к файлу или устройству, который можно читать, записывать, удалять, все или нет (см. следующую таблицу). Этот флаг не влияет на запросы доступа к атрибутам или расширенным атрибутам.
Если этот параметр равен нулю и CreateFile2 завершается успешно, файл или устройство нельзя предоставить к совместному доступу, и его нельзя будет открыть снова, пока не будет закрыт дескриптор файла или устройства. Дополнительные сведения см. в разделе «Примечания».
Невозможно запросить режим общего доступа, конфликтующий с режимом доступа, указанным в существующем запросе с открытым дескриптором. CreateFile2 завершится ошибкой, а функция GetLastError вернет ERROR_SHARING_VIOLATION.
Чтобы разрешить процессу предоставлять общий доступ к файлу или устройству, а другой процесс открывает файл или устройство, используйте совместимое сочетание одного или нескольких из следующих значений. Дополнительные сведения о допустимых сочетаниях этого параметра с параметром 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 | Да |
| Прозрачная отработка отказа (TFO) SMB 3.0 | Нет |
| 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 в одиночку. Результирующий код выполняется быстрее, так как перенаправитель может использовать диспетчер кэша и отправлять меньше SMB с большим объемом данных.
Это сочетание также позволяет избежать проблемы, из-за которой запись в файл по сети иногда может возвращать ERROR_ACCESS_DENIED.
Дополнительные сведения см. в разделе Создание и открытие файлов.
Потоки файлов
В файловых системах NTFS можно использовать CreateFile2 для создания отдельных потоков в файле. Дополнительные сведения см. в разделе Файловые потоки.Каталоги
Приложение не может создать каталог с помощью CreateFile2, поэтому для dwCreationDisposition в этом случае допустимо только значение OPEN_EXISTING. Чтобы создать каталог, приложение должно вызвать 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 .
- При открытии тома или дискеты параметр dwShareMode должен иметь флаг FILE_SHARE_WRITE .
| Строка | Значение |
|---|---|
| "\\.\PhysicalDrive0" | Открывает первый физический диск. |
| "\\.\PhysicalDrive2" | Открывает третий физический диск. |
Чтобы получить идентификатор физического диска для тома, откройте дескриптор тома и вызовите функцию DeviceIoControl с IOCTL_VOLUME_GET_VOLUME_DISK_EXTENTS. Этот управляющий код возвращает номер диска и смещение для каждого из экстентов тома; том может охватывать несколько физических дисков.
Пример открытия физического диска см. в разделе Вызов DeviceIoControl.
При открытии тома или съемного носителя (например, дисковод гибких дисков или флэш-памяти) строка lpFileName должна иметь следующий вид: "\.\X:". Не используйте обратную косую черту (\), которая указывает корневой каталог диска. В следующей таблице приведены примеры строк диска.
| Строка | Значение |
|---|---|
| "\\.\A:" | Открывает гибкий диск A. |
| "\\.\C:" | Открывает том C:. |
| "\\.\C:\" | Открывает файловую систему тома C: . |
Вы также можете открыть том, ссылаясь на его имя. Дополнительные сведения см. в разделе Именование тома.
Том содержит одну или несколько подключенных файловых систем. Дескриптор тома можно открыть без кэширования по усмотрению конкретной файловой системы, даже если параметр без кэширования не указан в CreateFile2. Следует предположить, что все открытые тома файловых систем Майкрософт обрабатываются как некэшированные. Ограничения на некэшированные операции ввода-вывода для файлов также применяются к томам.
Файловая система может требовать или не требовать выравнивания буфера, даже если данные не кешированы. Однако если при открытии тома указан параметр без кэширования, выравнивание буфера применяется независимо от файловой системы тома. Во всех файловых системах рекомендуется открывать дескриптор тома как без кэширования и следовать ограничениям некэшированных операций ввода-вывода.
Устройство 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.
Если вызывающий процесс наследует консоль или дочерний процесс должен иметь доступ к консоли, этот параметр должен иметь значение |
| DwCreationDisposition | При использовании CreateFile2 для открытия консоли следует указать OPEN_EXISTING. |
Задайте члены структуры 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 создаст его с помощью функции CreateMailSlot .Дополнительные сведения см. в разделе Mailslots.
Трубы
Если CreateFile2 открывает клиентский конец именованного канала, функция использует любой экземпляр именованного канала, который находится в состоянии прослушивания. Процесс открытия может дублировать дескриптор столько раз, сколько требуется, но после его открытия экземпляр именованного канала не может быть открыт другим клиентом. Доступ, указанный при открытии канала, должен быть совместим с доступом, указанным в параметре dwOpenMode функции CreateNamedPipe .Если функция CreateNamedPipe не была успешно вызвана на сервере до этой операции, канал не будет существовать, и CreateFile2 завершится сбоем с ERROR_FILE_NOT_FOUND.
Если имеется по крайней мере один активный экземпляр канала, но на сервере нет доступных каналов прослушивателя. Это означает, что все экземпляры канала подключены в данный момент, createFile2 завершается сбоем с ERROR_PIPE_BUSY.
Дополнительные сведения см. в разделе Каналы.
Требования
| Минимальная версия клиента | Windows 8 [классические приложения | Приложения UWP] |
| Минимальная версия сервера | Windows Server 2012 [классические приложения | Приложения UWP] |
| Целевая платформа | Windows |
| Header | fileapi.h (включая Windows.h) |
| Библиотека | Kernel32.lib |
| DLL | Kernel32.dll |
См. также
Сведения об управлении каталогами
Создание, удаление и обслуживание файлов
Управление вводом и выводом устройства (IOCTL)
Безопасность файлов и права доступа
Функции
Получение и настройка сведений о файле
Обзорные разделы
Обратная связь
Ожидается в ближайшее время: в течение 2024 года мы постепенно откажемся от GitHub Issues как механизма обратной связи для контента и заменим его новой системой обратной связи. Дополнительные сведения см. в разделе https://aka.ms/ContentUserFeedback.
Отправить и просмотреть отзыв по