структура CREATEFILE2_EXTENDED_PARAMETERS (fileapi.h)
Содержит необязательные расширенные параметры для CreateFile2.
Синтаксис
typedef struct _CREATEFILE2_EXTENDED_PARAMETERS {
DWORD dwSize;
DWORD dwFileAttributes;
DWORD dwFileFlags;
DWORD dwSecurityQosFlags;
LPSECURITY_ATTRIBUTES lpSecurityAttributes;
HANDLE hTemplateFile;
} CREATEFILE2_EXTENDED_PARAMETERS, *PCREATEFILE2_EXTENDED_PARAMETERS, *LPCREATEFILE2_EXTENDED_PARAMETERS;
Члены
dwSize
Содержит размер этой структуры , sizeof(CREATEFILE2_EXTENDED_PARAMETERS).
dwFileAttributes
Атрибуты и флаги файла или устройства , FILE_ATTRIBUTE_NORMAL являются наиболее распространенным значением по умолчанию для файлов.
Этот параметр может включать любое сочетание доступных атрибутов файла (FILE_ATTRIBUTE_*). Все остальные атрибуты файла переопределяют FILE_ATTRIBUTE_NORMAL.
Примечание
Когда CreateFile2 открывает существующий файл, он обычно объединяет флаги файла с атрибутами существующего файла и игнорирует все атрибуты файла, предоставленные в составе dwFlagsAndAttributes. Особые случаи описаны в разделе Создание и открытие файлов.
Некоторые из следующих атрибутов и флагов файлов могут применяться только к файлам, а не ко всем другим типам устройств, которые может открывать CreateFile2 . Дополнительные сведения см. в разделе Примечания страницы справочника CreateFile2 и в разделе Создание и открытие файлов.
Дополнительные сведения о расширенном доступе к атрибутам файлов см. в разделе SetFileAttributes. Полный список всех атрибутов файла с их значениями и описаниями см. в разделе File Attribute Constants.
| attribute | Значение |
|---|---|
|
Файл должен быть заархивирован. Приложения используют этот атрибут, чтобы отмечать файлы для резервного копирования или удаления. |
|
Файл или каталог зашифрован. Для файла это означает, что все данные в файле зашифрованы. Для каталога это означает, что шифрование используется по умолчанию для вновь созданных файлов и подкаталогов. Дополнительные сведения см. в разделе Шифрование файлов.
Этот флаг не действует, если также указан FILE_ATTRIBUTE_SYSTEM . Этот флаг не поддерживается в выпусках Windows Home, Home Premium, Starter или ARM. Этот флаг не поддерживается при вызове из приложения Магазина Windows. |
|
Файл скрыт. Не включайте его в обычный список каталогов. |
|
Файл или каталог с настроенной целостностью. Для файла все потоки данных в файле имеют целостность. Для каталога по умолчанию для вновь созданных файлов и подкаталогов используется целостность, если вызывающий объект не указывает иное.
Этот флаг поддерживается только в файловой системе ReFS. |
|
В файле не заданы другие атрибуты. При использовании этого атрибута не допускается использование других атрибутов. |
|
Данные файла доступны не сразу. Этот атрибут указывает, что данные файлов физически перемещаются в автономное хранилище. Этот атрибут используется удаленным хранилищем, программным обеспечением для управления иерархическим хранилищем. Приложения не должны произвольно изменять этот атрибут. |
|
Файл доступен только для чтения. Приложения могут считывать файл, но не могут записывать или удалять его. |
|
Файл является частью операционной системы или используется исключительно в ней. |
|
Файл используется для временного хранения.
Дополнительные сведения см. в разделе Поведение кэширования этой статьи. |
dwFileFlags
Этот параметр может содержать сочетания флагов (FILE_FLAG_*) для управления поведением кэширования файлов или устройств, режимов доступа и других специальных флагов.
| Flag | Значение |
|---|---|
|
Файл открывается или создается для резервного копирования или восстановления. Система гарантирует, что вызывающий процесс переопределяет проверки безопасности файлов, если у процесса есть SE_BACKUP_NAME и SE_RESTORE_NAME привилегии. Дополнительные сведения см. в разделе Изменение привилегий в токене.
Этот флаг необходимо задать, чтобы получить дескриптор каталога. Дескриптор каталога можно передать некоторым функциям вместо дескриптора файла. Дополнительные сведения см. в разделе «Примечания». |
|
Файл будет удален сразу после закрытия всех его дескрипторов, включая указанный дескриптор и другие открытые или дублирующиеся дескрипторы.
Если для файла имеются открытые дескрипторы, вызов завершается ошибкой, если только они не были открыты в режиме общего доступа FILE_SHARE_DELETE . Последующие запросы на открытие файла завершатся сбоем, если только не указан режим совместного использования FILE_SHARE_DELETE. |
|
Сопоставление устройств — это сопоставление между именами устройств DOS и устройствами в системе и используется при разрешении имен DOS. Для каждого пользователя в системе существуют отдельные карты устройств, и пользователи могут управлять своими картами устройств. Обычно во время олицетворения используется карта устройства олицетворенного пользователя. Однако при установке этого флага вместо него используется сопоставление устройств пользователя процесса. |
|
Файл или устройство открывается без системного кэширования для операций чтения и записи данных. Этот флаг не влияет на кэширование жесткого диска или сопоставленные файлы в памяти.
Существуют строгие требования к успешной работе с файлами, открытыми с помощью CreateFile2 с помощью флага FILE_FLAG_NO_BUFFERING . Дополнительные сведения см. в разделе Буферизация файлов. |
|
Данные файла запрашивается, но они должны по-прежнему находиться в удаленном хранилище. Его не следует переносить обратно в локальное хранилище. Этот флаг предназначен для использования системами удаленного хранения. |
|
Обычная обработка точек повторного обработки не выполняется; CreateFile2 попытается открыть точку повторного извлечения. При открытии файла возвращается дескриптор файла, независимо от того, работает ли фильтр, управляющий точкой повторного определения.
Этот флаг нельзя использовать с флагом CREATE_ALWAYS . Если файл не является точкой повторного извлечения, этот флаг игнорируется. Дополнительные сведения см. в разделе «Примечания». |
|
Файл открывается и запрашивается оппортунистическая блокировка (oplock) файла в виде одной атомарной операции. Файловая система проверяет наличие блокировок перед выполнением операции создания и завершит создание ошибкой с кодом последней ошибки ERROR_CANNOT_BREAK_OPLOCK , если результатом будет прерывание существующей блокировки операции.
Если вы используете этот флаг и вызов функции CreateFile2 успешно возвращается, первая операция, которую необходимо выполнить с дескриптором файла, — запросить блокировку, вызвав функцию DeviceIOControl , а затем передать FSCTL_REQUEST_OPLOCK или одну из других операций opportunistic lock. При выполнении других операций файловой системы с дескриптором файла перед запросом блокировки может возникнуть взаимоблокировка. Примечание Вы можете безопасно вызвать функцию CloseHandle для дескриптора файла без предварительного запроса oplock.
|
|
Файл или устройство открывается или создается для асинхронного ввода-вывода.
После завершения последующих операций ввода-вывода для этого дескриптора событие, указанное в структуре OVERLAPPED , будет установлено в состояние сигнала. Если этот флаг указан, файл можно использовать для одновременных операций чтения и записи. Если этот флаг не указан, операции ввода-вывода сериализуются, даже если вызовы функций чтения и записи указывают структуру OVERLAPPED . Сведения об использовании дескриптора файла, созданного с помощью этого флага, см. в разделе Синхронные и асинхронные дескрипторы ввода-вывода этой статьи. |
|
Доступ будет осуществляться в соответствии с правилами POSIX. Это включает в себя разрешение нескольких файлов с именами, отличающимися только в случае, для файловой системы, поддерживающей такое именование. Будьте внимательны при использовании этого параметра, так как файлы, созданные с этим флагом, могут быть недоступны приложениям, написанным для MS-DOS или 16-разрядной версии Windows. |
|
Доступ должен быть случайным. Система может использовать это в качестве указания для оптимизации кэширования файлов.
Этот флаг не действует, если файловая система не поддерживает кэшированные ввод-вывод и FILE_FLAG_NO_BUFFERING. Дополнительные сведения см. в разделе Поведение кэширования этой статьи. |
|
Файл или устройство открывается с поддержкой сеанса. Если этот флаг не указан, то устройства для каждого сеанса (например, устройства, использующие перенаправление USB RemoteFX) не могут быть открыты процессами, запущенными в сеансе 0. Этот флаг не действует для вызывающих абонентов, не в сеансе 0. Этот флаг поддерживается только в серверных выпусках Windows.
Windows Server 2008 R2 и Windows Server 2008: Этот флаг не поддерживается до Windows Server 2012. |
|
Доступ должен быть последовательным от начала до конца. Система может использовать это в качестве указания для оптимизации кэширования файлов.
Этот флаг не следует использовать, если будет использоваться режим чтения программной части (то есть сканирование в обратном направлении). Этот флаг не действует, если файловая система не поддерживает кэшированные ввод-вывод и FILE_FLAG_NO_BUFFERING. Дополнительные сведения см. в разделе Поведение кэширования этой статьи. |
|
Операции записи не будут проходить через промежуточный кэш, они будут отправляться непосредственно на диск.
Дополнительные сведения см. в разделе Поведение кэширования этой статьи. |
dwSecurityQosFlags
Параметр dwSecurityQosFlags указывает сведения о SQOS. Дополнительные сведения см. в разделе Уровни олицетворения.
lpSecurityAttributes
Указатель на структуру SECURITY_ATTRIBUTES , содержащую два отдельных, но связанных элемента данных: необязательный дескриптор безопасности и логическое значение, определяющее, может ли возвращаемый дескриптор наследоваться дочерними процессами.
Этот параметр может принимать значение NULL.
Если этот параметр имеет значение NULL, дескриптор, возвращаемый CreateFile2 , не может быть унаследован никакими дочерними процессами, которые может создать приложение, и файл или устройство, связанное с возвращенным дескриптором, получает дескриптор безопасности по умолчанию.
Элемент lpSecurityDescriptor структуры задает SECURITY_DESCRIPTOR для файла или устройства. Если этот элемент имеет значение NULL, файлу или устройству, связанным с возвращенным дескриптором, назначается дескриптор безопасности по умолчанию.
CreateFile2 игнорирует элемент lpSecurityDescriptor при открытии существующего файла или устройства, но продолжает использовать элемент bInheritHandle .
Член структуры bInheritHandle указывает, можно ли наследовать возвращенный дескриптор.
Дополнительные сведения см. в разделе Примечания раздела CreateFile2 .
hTemplateFile
Допустимый дескриптор файла шаблона с правом доступа GENERIC_READ . Файл шаблона предоставляет атрибуты файла и расширенные атрибуты для создаваемого файла.
Этот параметр может принимать значение NULL.
При открытии существующего файла CreateFile2 игнорирует этот параметр.
При открытии нового зашифрованного файла файл наследует список управления доступом на уровне пользователей из родительского каталога. Дополнительные сведения см. в разделе Шифрование файлов.
Комментарии
Чтобы скомпилировать приложение, использующее структуру CREATEFILE2_EXTENDED_PARAMETERS , определите макрос _WIN32_WINNT как 0x0602 или более поздней версии. Дополнительные сведения см. в разделе Использование заголовков Windows.
Режим кэширования
Некоторые из возможных значений элемента dwFileFlags используются для управления или влияния на то, как данные, связанные с дескриптором, кэшируются системой. К ним относятся:
- FILE_FLAG_NO_BUFFERING
- FILE_FLAG_RANDOM_ACCESS
- FILE_FLAG_SEQUENTIAL_SCAN
- FILE_FLAG_WRITE_THROUGH
- FILE_ATTRIBUTE_TEMPORARY
Если ни один из этих флагов не указан, система использует схему кэширования общего назначения по умолчанию. В противном случае системное кэширование будет работать так, как указано для каждого флага.
Некоторые из этих флагов не следует объединять. Например, объединение FILE_FLAG_RANDOM_ACCESS с FILE_FLAG_SEQUENTIAL_SCAN является саморазумным.
Указание флага FILE_FLAG_SEQUENTIAL_SCAN может повысить производительность приложений, которые считывают большие файлы с помощью последовательного доступа. Повышение производительности может быть еще более заметным для приложений, которые считывают большие файлы в основном последовательно, но иногда пропускают вперед в небольших диапазонах байтов. Если приложение перемещает указатель на файл для произвольного доступа, оптимальная производительность кэширования, скорее всего, не будет. Тем не менее, правильная операция по-прежнему гарантируется.
Флаги FILE_FLAG_WRITE_THROUGH и FILE_FLAG_NO_BUFFERING являются независимыми и могут быть объединены.
Если используется FILE_FLAG_WRITE_THROUGH , но FILE_FLAG_NO_BUFFERING также не указан, поэтому системное кэширование действует, данные записываются в системный кэш, но сбрасываются на диск без задержки.
Если указаны FILE_FLAG_WRITE_THROUGH и FILE_FLAG_NO_BUFFERING , чтобы системное кэширование не действовало, данные немедленно сбрасываются на диск, не проходя через системный кэш Windows. Операционная система также запрашивает запись локального аппаратного кэша жесткого диска на постоянный носитель.
Примечание
Эта возможность поддерживается не всем оборудованием жестких дисков.
Правильное использование флага FILE_FLAG_NO_BUFFERING требует особых рекомендаций по приложениям. Дополнительные сведения см. в разделе Буферизация файлов.
Запрос на запись через FILE_FLAG_WRITE_THROUGH также приводит к тому, что NTFS очищает любые изменения метаданных, такие как обновление метки времени или операция переименования, которые возникают в результате обработки запроса. По этой причине флаг FILE_FLAG_WRITE_THROUGH часто используется вместе с флагом FILE_FLAG_NO_BUFFERING в качестве замены для вызова функции FlushFileBuffers после каждой записи, что может привести к ненужным ограничениям производительности. Использование этих флагов вместе позволяет избежать этих штрафов. Общие сведения о кэшировании файлов и метаданных см. в разделе Кэширование файлов.
При сочетании FILE_FLAG_NO_BUFFERING с FILE_FLAG_OVERLAPPED флаги обеспечивают максимальную асинхронную производительность, так как операции ввода-вывода не зависят от синхронных операций диспетчера памяти. Однако некоторые операции ввода-вывода занимают больше времени, так как данные не хранятся в кэше. Кроме того, метаданные файла могут по-прежнему кэшироваться (например, при создании пустого файла). Чтобы обеспечить очистку метаданных на диск, используйте функцию FlushFileBuffers .
Указание атрибута FILE_ATTRIBUTE_TEMPORARY приводит к тому, что файловые системы не будут записывать данные обратно в массовое хранилище, если доступно достаточно памяти кэша, так как приложение удаляет временный файл после закрытия дескриптора. В этом случае система может полностью избежать записи данных. Хотя он напрямую не управляет кэшированием данных так же, как упомянутые ранее флаги, атрибут FILE_ATTRIBUTE_TEMPORARY указывает системе хранить как можно больше данных в системном кэше без записи и, следовательно, может быть проблемой для некоторых приложений.
Синхронные и асинхронные дескрипторы ввода-вывода
CreateFile2 позволяет создать дескриптор файла или устройства, который является синхронным или асинхронным. Синхронный дескриптор ведет себя таким образом, что вызовы функции ввода-вывода, использующие этот дескриптор, блокируются до их завершения, а асинхронный дескриптор файла позволяет системе немедленно возвращать данные из вызовов функции ввода-вывода независимо от того, завершена ли операция ввода-вывода или нет. Как упоминалось ранее, это синхронное и асинхронное поведение определяется указанием FILE_FLAG_OVERLAPPED в элементе dwFileFlagsструктуры CREATEFILE2_EXTENDED_PARAMETERS , переданной в параметре pCreateExParams . Существует несколько сложностей и потенциальных ошибок при использовании асинхронных операций ввода-вывода; Дополнительные сведения см. в разделе Синхронный и асинхронный ввод-вывод.
Требования
| Минимальная версия клиента | Windows 8 [классические приложения | Приложения UWP] |
| Минимальная версия сервера | Windows Server 2012 [классические приложения | Приложения UWP] |
| Верхняя часть | fileapi.h (включая Windows.h) |
См. также раздел
Обратная связь
Ожидается в ближайшее время: в течение 2024 года мы постепенно откажемся от GitHub Issues как механизма обратной связи для контента и заменим его новой системой обратной связи. Дополнительные сведения см. в разделе https://aka.ms/ContentUserFeedback.
Отправить и просмотреть отзыв по