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

Статья
08/07/2023

Подпрограмма FltSetStreamContext задает контекст для потока файлов.

Синтаксис

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

Параметры

[in] Instance

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

[in] FileObject

Указатель на объект файла для файлового потока.

[in] Operation

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

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

Flag

Значение

FLT_SET_CONTEXT_REPLACE_IF_EXISTS

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

FLT_SET_CONTEXT_KEEP_IF_EXISTS

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

[in] NewContext

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

[out] OldContext

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

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

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

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

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

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

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

Если fltSetStreamContext успешно выполняется:

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

В противном случае, если FltSetStreamContext завершается сбоем :

Количество ссылок в NewContext остается неизменным.
Если значение OldContext не равно NULL и не указывает на NULL_CONTEXT то OldContext является указателем на контекст, связанный в данный момент с потоком. Фильтр, вызывающий FltSetStreamContext , должен вызывать FltReleaseContext для OldContext , если указатель контекста больше не нужен.

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

Фильтр, вызывающий FltSetStreamContext , должен вызывать FltReleaseContext для уменьшения количества ссылок на объект NewContext , который был увеличен с помощью FltAllocateContext.

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

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

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

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

Требования

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