структура FSRTL_ADVANCED_FCB_HEADER (ntifs.h)

Статья
12/21/2024

Структура FSRTL_ADVANCED_FCB_HEADER содержит сведения о контексте, которые файловая система поддерживает в файле.

Синтаксис

typedef struct _FSRTL_ADVANCED_FCB_HEADER {
  FSRTL_COMMON_FCB_HEADER          DUMMYSTRUCTNAME;
  PFAST_MUTEX                      FastMutex;
  LIST_ENTRY                       FilterContexts;
  EX_PUSH_LOCK                     PushLock;
  PVOID                            *FileContextSupportPointer;
  union {
    OPLOCK Oplock;
    PVOID  ReservedForRemote;
  };
  PVOID                            AePushLock;
  PVOID                            ReservedContextLegacy;
  ULONG                            BypassIoOpenCount;
  struct _FSRTL_PER_STREAM_CONTEXT *ReservedContext;
} FSRTL_ADVANCED_FCB_HEADER;

Члены

DUMMYSTRUCTNAME

Неименованный элемент, содержащий структуру типа FSRTL_COMMON_FCB_HEADER.

FastMutex

Указатель на инициализированный быстрый мьютекс, используемый для синхронизации доступа к следующим членам DUMMYSTRUCTNAME:

Выделение
FileSize
ValidDataLength

При наличии элемент PushLock используется для синхронизации доступа к элементу FilterContexts; в противном случае используется FastMutex.

FilterContexts

Указатель на голову списка всех структур контекста, связанных с файлом. Драйверы фильтров могут выполнять поиск по этому списку путем вызова FsRtlLookupPerStreamContext и изменения путем вызова FsRtlInsertPerStreamContext и FsRtlRemovePerStreamContext.

PushLock

Блокировка push-уведомлений, используемая для синхронизации доступа к списку filterContexts . Это поле доступно только начиная с Windows Vista (т. е. если версия битовой части структуры FSRTL_COMMON_FCB_HEADER больше или равно FSRTL_FCB_HEADER_V1).

FileContextSupportPointer

Указатель на поле указателя, используемое библиотекой среды выполнения файловой системы (FSRTL) для отслеживания контекстов файлов. Если не значение NULL, этот элемент должен быть указателем на переменную PVOID внутри структуры файлов для файловой системы, создающей структуру. Если nullконтексты файлов не поддерживаются. Этот элемент доступен только начиная с Windows Vista (т. е. если версия битовой части структуры FSRTL_COMMON_FCB_HEADER больше или равно FSRTL_FCB_HEADER_V1).

Oplock

Оплок для файла или каталога. Это поле доступно только начиная с Windows 8 (т. е. если версия битовой части структуры FSRTL_COMMON_FCB_HEADER больше или равно FSRTL_FCB_HEADER_V2).

ReservedForRemote

Если файловая система удалена, это поле зарезервировано. Она доступна только начиная с Windows 8 (то есть если версии битовое поле структуры FSRTL_COMMON_FCB_HEADER больше или равно FSRTL_FCB_HEADER_V2).

AePushLock

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

AePushlock доступна начиная с Windows 10 версии 20H2 (т. е. если битовое поле структуры FSRTL_COMMON_FCB_HEADER больше или равно FSRTL_FCB_HEADER_V3), и его необходимо инициализировать путем вызова FsRtlSetupAdvancedHeaderEx2.

ReservedContextLegacy

Это поле зарезервировано для использования системы. Он используется только в Windows 8.1 до Windows 10 версии 1803 (если версия битовой части структуры FSRTL_COMMON_FCB_HEADER больше или равно FSRTL_FCB_HEADER_V3).

BypassIoOpenCount

Отслеживает, сколько дескрипторов в настоящее время открыто с помощью BypassIO включен в этом потоке.

Это поле доступно начиная с Windows 11 (то есть, если версия битовой части структуры FSRTL_COMMON_FCB_HEADER больше или равно FSRTL_FCB_HEADER_V4).

ReservedContext

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

Это поле доступно начиная с Windows 11 версии 22H2 (то есть, если версия битовой структуры FSRTL_COMMON_FCB_HEADER больше или равно FSRTL_FCB_HEADER_V5).

Замечания

Структура FSRTL_ADVANCED_FCB_HEADER — это супермножество структуры FSRTL_COMMON_FCB_HEADER. Файловые системы (включая устаревшие фильтры и драйверы минифильтра, при необходимости) должны использовать структуру FSRTL_ADVANCED_FCB_HEADER.

Файловые системы должны использовать один из следующих макросов для инициализации структуры FSRTL_ADVANCED_FCB_HEADER:

FsRtlSetupAdvancedHeader
FsRtlSetupAdvancedHeaderEx
FsRtlSetupAdvancedHeaderEx2, доступной начиная с Windows 10 версии 20H2.

Следующие флаги задаются этими макросами.

Флаг	Значение
FSRTL_FLAG_ADVANCED_HEADER	Установите в элементе Flags структуры FSRTL_COMMON_FCB_HEADER, этот флаг указывает на поддержку драйверов файловой системы для структур FSRTL_ADVANCED_FCB_HEADER. Этот флаг не следует изменять.
FSRTL_FLAG2_SUPPORTS_FILTER_CONTEXTS	Установите в элементе FSRTL_COMMON_FCB_HEADERфлагов флагов 2, этот флаг указывает на поддержку контекстов драйвера фильтра. Этот флаг можно очистить только для разбиения по страницам (см. сведения после таблицы).

Файловые системы должны задать FsContext член каждого объекта файла, чтобы указать FSRTL_ADVANCED_FCB_HEADER структуру. Эта структура может быть внедрена в структуру объекта контекста, относящуюся к потоку файловой системы (оставшаяся часть структуры зависит от файловой системы). Как правило, эта структура является блоком управления файлами (FCB). Однако в некоторых файловых системах, поддерживающих несколько потоков данных, таких как NTFS, это блок управления потоками (SCB). Обратите внимание, что ФКБ и SCB для всех классов открытых запросов, включая запросы на открытие томов, должны включать эту структуру.

Если файл является файлом разбиения по страницам, структура FSRTL_ADVANCED_FCB_HEADER должна быть выделена из непагрегированного пула. В противном случае его можно выделить из страничного или неспеченного пула.

Все файловые системы Майкрософт отключают поддержку контекста потока для разбиения файлов, очищая флаг FSRTL_FLAG2_SUPPORTS_FILTER_CONTEXTS в FSRTL_COMMON_FCB_HEADER элементе Flags2 после вызова FsRtlSetupAdvancedHeader. (См. функцию FatCreateFcb в Strucsup.c для примера FASTFAT WDK.) Настоятельно рекомендуется сделать то же самое в файловой системе или системах, чтобы операционная система действовала согласованно во всех файловых системах.

Автоматическое развертывание блокировок push-уведомлений

В Windows 10 версии 20H2 появились автоматические блокировки push-уведомлений. Когда блокировки диспетчера фильтров были первоначально разработаны, крупные многопроцессорные системы были очень редкими, и ОЗУ было драгоценным. В таких системах теперь распространены и ОЗУ не так ограничены, автоматическое развертывание push-блокировки обеспечивает полезный компромисс между потреблением памяти и скоростью.

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