Функция FltSetStreamHandleContext (fltkernel.h)

Статья
02/06/2025

Подпрограмма FltSetStreamHandleContext задает контекст для дескриптора потока.

Синтаксис

NTSTATUS FLTAPI FltSetStreamHandleContext(
  [in]            PFLT_INSTANCE             Instance,
  [in]            PFILE_OBJECT              FileObject,
  [in]            FLT_SET_CONTEXT_OPERATION Operation,
  [in]            PFLT_CONTEXT              NewContext,
  [out, optional] PFLT_CONTEXT              *OldContext
);

Параметры

[in] Instance

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

[in] FileObject

Указатель на объект файла для потока файлов. Этот параметр является обязательным и не может быть null.

[in] Operation

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

Ценность	Значение
FLT_SET_CONTEXT_REPLACE_IF_EXISTS	Если для этого экземплярауже задан контекст, FltSetStreamHandleContext заменит его контекстом, указанным в NewContext. В противном случае он вставляет NewContext в список контекстов для дескриптора потока.
FLT_SET_CONTEXT_KEEP_IF_EXISTS	Если контекст уже задан для этого экземпляра , FltSetStreamHandleContext вернет STATUS_FLT_CONTEXT_ALREADY_DEFINED и не заменит существующий контекст или добавит число ссылок. Если контекст еще не задан, подпрограмма вставляет NewContext в список контекстов для дескриптора потока и увеличивает число ссылок.

Ценность

Значение

FLT_SET_CONTEXT_REPLACE_IF_EXISTS

Если для этого экземплярауже задан контекст, FltSetStreamHandleContext заменит его контекстом, указанным в NewContext. В противном случае он вставляет NewContext в список контекстов для дескриптора потока.

FLT_SET_CONTEXT_KEEP_IF_EXISTS

Если контекст уже задан для этого экземпляра , FltSetStreamHandleContext вернет STATUS_FLT_CONTEXT_ALREADY_DEFINED и не заменит существующий контекст или добавит число ссылок. Если контекст еще не задан, подпрограмма вставляет NewContext в список контекстов для дескриптора потока и увеличивает число ссылок.

[in] NewContext

Указатель на новый контекст, заданный для дескриптора потока. Этот параметр является обязательным и не может быть null.

[out, optional] OldContext

Указатель на выделенную вызывающим переменную, которая получает адрес существующего контекста дескриптора потока для параметра экземпляра, если он уже задан. Этот параметр является необязательным и может быть null. Дополнительные сведения об этом параметре см. в следующем разделе "Примечания".

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

Подпрограмма fltSetStreamHandleContext возвращает STATUS_SUCCESS или соответствующее значение NTSTATUS, например один из следующих кодов ошибок:

Возвращаемый код	Описание
STATUS_FLT_CONTEXT_ALREADY_DEFINED	Если FLT_SET_CONTEXT_KEEP_IF_EXISTS был указан для операции, этот код ошибки указывает, что контекст уже подключен к дескриптору потока.
STATUS_FLT_CONTEXT_ALREADY_LINKED	Контекст, на который NewContext указывает, уже связан с объектом. Другими словами, этот код ошибки указывает, что NewContext уже используется из-за успешного вызова подпрограммы FltSetXxxContext.
STATUS_FLT_DELETING_OBJECT	Указанный экземпляр выполняется отключается. Это код ошибки.
STATUS_INVALID_PARAMETER	Недопустимый параметр был передан. Например, параметр NewContext не указывает на допустимый контекст дескриптора потока или недопустимое значение было указано для операции.
STATUS_NOT_SUPPORTED	Произошла неподдерживаемая ситуация, например файловая система не поддерживает контексты для каждого потока для этого потока, или вызывающий объект предоставил значение NULL FileObject.

Замечания

Дополнительные сведения о контекстах см. в разделе О контекстах минифильтра.

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

FltSetStreamHandleContext нельзя вызывать на нераскрытый FileObject. Поэтому fltSetStreamHandleContext нельзя вызывать из предварительно созданного обратного вызова для потока, так как поток не был открыт в этом моменте. Однако мини-фильтр может выделить и настроить контекст дескриптора потока в предварительно созданном обратном вызове, передать его в обратный вызов после создания с помощью параметра контекста завершения и задать контекст дескриптора потока в потоке после создания обратного вызова.

Подсчет ссылок

Если FltSetStreamHandleContext успешно:

Число ссылок на NewContext увеличивается. Если NewContext больше не требуется, мини-фильтр должен вызвать FltReleaseContext, чтобы свести к минимуму количество ссылок.

Если FltSetStreamHandleContext завершается ошибкой:

Количество ссылок на NewContext остается неизменным.
Если OldContext не NULL и не указывает на NULL_CONTEXT, то OldContext — это указатель на контекст, связанный с дескриптором потока. Вызов фильтра FltSetStreamHandleContext должен вызывать FltReleaseContext для OldContext, а также когда указатель контекста больше не нужен.

Независимо от успеха:

Вызов фильтра FltSetStreamHandleContext должен вызывать FltReleaseContext для уменьшения количества ссылок для объекта NewContext, который был добавлен FltAllocateContext.

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

Другие операции контекста

Дополнительные сведения см. в разделе Настройка контекстови выпуск контекстов:

Чтобы определить, поддерживаются ли контексты дескриптора потока для данного файла, вызовите FltSupportsStreamHandleContexts
Чтобы выделить новый контекст, вызовите FltAllocateContext.
Чтобы получить контекст дескриптора потока, вызовите FltGetStreamHandleContext.
Чтобы удалить контекст дескриптора потока, вызовите FltDeleteStreamHandleContext или FltDeleteContext.

Требования

Требование	Ценность
минимальные поддерживаемые клиентские	Доступно и поддерживается в пакете обновления 1 для Microsoft Windows 2000 с пакетом обновления 1 (SP4), Windows XP с пакетом обновления 2 (SP2), Windows Server 2003 с пакетом обновления 1 (SP1) и более поздних операционных систем.
целевая платформа	Всеобщий
заголовка	fltkernel.h (include Fltkernel.h)
библиотеки	Fltmgr.lib
DLL	Fltmgr.sys
IRQL	<= APC_LEVEL