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

Статья
08/07/2023

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

Синтаксис

NTSTATUS FLTAPI FltSetTransactionContext(
  [in]            PFLT_INSTANCE             Instance,
  [in]            PKTRANSACTION             Transaction,
  [in]            FLT_SET_CONTEXT_OPERATION Operation,
  [in]            PFLT_CONTEXT              NewContext,
  [out, optional] PFLT_CONTEXT              *OldContext
);

Параметры

[in] Instance

Указатель непрозрачного экземпляра для вызывающего объекта.

[in] Transaction

Непрозрачный указатель транзакции для транзакции, для которой задается контекст.

[in] Operation

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

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

Flag

Значение

FLT_SET_CONTEXT_REPLACE_IF_EXISTS

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

FLT_SET_CONTEXT_KEEP_IF_EXISTS

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

[in] NewContext

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

[out, optional] OldContext

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

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

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

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

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

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

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

В противном случае, если сбой FltSetTransactionContext :

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

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

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

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

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

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

Чтобы выделить новый контекст, вызовите FltAllocateContext.

Чтобы получить контекст транзакции, вызовите Метод FltGetTransactionContext.

Чтобы удалить контекст транзакции, вызовите Метод FltDeleteTransactionContext или FltDeleteContext.

Требования

Требование	Значение
Минимальная версия клиента	Доступно и поддерживается в Операционных системах Windows Vista и более поздних версий.
Целевая платформа	Универсальное
Верхняя часть	fltkernel.h (включая Fltkernel.h)
Библиотека	FltMgr.lib
DLL	FltMgr.sys
IRQL	<= APC_LEVEL.