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

Статья
08/07/2023

FltSetInstanceContext задает контекст для экземпляра драйвера мини-фильтра.

Синтаксис

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

Параметры

[in] Instance

Указатель непрозрачного экземпляра для экземпляра.

[in] Operation

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

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

Flag

Значение

FLT_SET_CONTEXT_REPLACE_IF_EXISTS

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

FLT_SET_CONTEXT_KEEP_IF_EXISTS

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

[in] NewContext

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

[out] OldContext

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

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

FltSetInstanceContext возвращает 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 указано недопустимое значение. Это код ошибки.

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

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

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

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

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

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

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

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

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

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

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

Чтобы выделить новый контекст, вызовите FltAllocateContext.
Чтобы получить контекст экземпляра, вызовите Метод FltGetInstanceContext.
Чтобы удалить контекст экземпляра, вызовите Метод FltDeleteInstanceContext или FltDeleteContext.

Требования

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