структура 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. Полный список всех атрибутов файла со своими значениями и описаниями см. в константы атрибутов файлов.
dwFileFlags
Этот параметр может содержать сочетания флагов (FILE_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 в дескрипторе файла, не запрашивая оплок.
|
|
Файл или устройство открываются или создаются для асинхронного ввода-вывода.
После завершения последующих операций ввода-вывода для этого дескриптора событие, указанное в структуре 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, не может наследоваться любым дочерним процессом, который может создать приложение, и файл или устройство, связанное с возвращенным дескриптором безопасности, получает дескриптор безопасности по умолчанию.
Элемент
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) |