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

Статья
08/07/2023

Устаревший драйвер фильтра файловой системы может использовать структуру FSRTL_PER_FILE_CONTEXT для связывания контекстных сведений о конкретном драйвере с открытым файлом.

Синтаксис

typedef struct _FSRTL_PER_FILE_CONTEXT {
  LIST_ENTRY     Links;
  PVOID          OwnerId;
  PVOID          InstanceId;
  PFREE_FUNCTION FreeCallback;
} FSRTL_PER_FILE_CONTEXT, *PFSRTL_PER_FILE_CONTEXT;

Члены

Links

Ссылка на эту структуру в списке всех контекстных структур для каждого файла, связанных с тем же файлом. FsRtlInsertPerFileContext вставляет этот элемент в список всех структур контекста для каждого файла.

OwnerId

Указатель на буфер, выделенный драйвером фильтра, который однозначно идентифицирует владельца структуры контекста для каждого файла. Формат этой переменной зависит от драйвера фильтра. Драйверы фильтров должны задать для этого элемента значение, отличное от NULL .

InstanceId

Указатель на буфер, выделенный драйвером фильтра, который можно использовать для различения структур контекста для каждого файла, созданных одним и тем же драйвером фильтра. Формат этой переменной зависит от драйвера фильтра. Драйверы фильтров могут присвоить этому члену значение NULL.

FreeCallback

Указатель на подпрограмму обратного вызова , которая освобождает структуру контекста для каждого файла. Драйверы фильтров должны задать для этого элемента значение, отличное от NULL .

Чтобы связать контекстные сведения с файлом, устаревший драйвер фильтра сначала выделяет структуру FSRTL_PER_FILE_CONTEXT и инициализирует ее с помощью FsRtlInsertPerFileContext. Затем драйвер использует FsRtlInsertPerFileContext , чтобы связать этот объект FSRTL_PER_FILE_CONTEXT с файлом. Когда система удаляет объект контекста файла для файла, она вызывает FsRtlTeardownPerFileContexts , который вызывает подпрограмму FreeCallback , указанную в объекте FSRTL_PER_FILE_CONTEXT . Этот обратный вызов должен освободить объект контекста, зависящий от драйвера.

Модули записи фильтров должны выбрать значение OwnerID , которое является понятным и удобным, например адрес объекта драйвера или объекта устройства.

Модули записи фильтров должны выбрать значение InstanceID , которое является понятным и удобным, например адрес объекта контекста файла для файла. Используйте макрос FsRtlGetPerFileContextPointer , чтобы получить этот адрес из объекта файла.

Структуру FSRTL_PER_FILE_CONTEXT можно использовать как есть или внедрять в определяемую драйвером структуру контекста для каждого файла.

Структура FSRTL_PER_FILE_CONTEXT может быть выделена из выгружаемого или невыгружаемого пула.

Макрос FsRtlInitPerFileContext инициализирует структуру FSRTL_PER_FILE_CONTEXT.

Параметры

FileContext

FSRTL_PER_FILE_CONTEXT

Инициализируемый объект FSRTL_PER_FILE_CONTEXT.

OwnerId

PVOID

Указатель на переменную, выделенную драйвером фильтра, которая однозначно определяет владельца структуры контекста для каждого файла. Формат зависит от драйвера фильтра. Этот параметр должен иметь значение, отличное от NULL .

InstanceId

PVOID

FreeCallback

PFREE_FUNCTION

Указатель на подпрограмму обратного вызова , которая освобождает структуру контекста для каждого файла.

Возвращаемое значение

VOID

Нет.

Этот макрос необходимо использовать перед вызовом FsRtlInsertPerFileContext.

Модули записи фильтров должны выбрать значение OwnerID , которое является понятным и удобным, например адрес объекта драйвера или объекта устройства.

Модули записи фильтров должны использовать понятное и удобное значение InstanceID , например адрес объекта контекста файла для файла. Используйте макрос FsRtlGetPerFileContextPointer , чтобы получить этот адрес из объекта файла.

Дополнительные сведения об использовании и создании объектов контекста см. в статье Отслеживание Per-File контекста в устаревшем драйвере фильтра файловой системы.

Требования

Требование	Значение
Минимальная версия клиента	Доступно начиная с Windows Vista.
Верхняя часть	ntifs.h (включая Fltkernel.h, Ntifs.h)