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

Статья
02/06/2025

Подпрограмма 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

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

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

Флаг

Значение

FLT_SET_CONTEXT_REPLACE_IF_EXISTS

Если контекст уже задан для транзакции, на которую указывает параметр Transaction, FltSetTransactionContext заменит его контекстом, на который указывает параметр NewContext. В противном случае контекст будет задан параметром 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	Если FLT_SET_CONTEXT_KEEP_IF_EXISTS был указан для параметра операции, этот код ошибки указывает, что контекст уже подключен к транзакции. Только один контекст можно подключить к транзакции для заданного драйвера минифильтра.
STATUS_FLT_CONTEXT_ALREADY_LINKED	Контекст, на который указывает параметр NewContext, уже связан с объектом. Другими словами, этот код ошибки указывает, что NewContext уже используется из-за успешного вызова подпрограммы FltSetXxxContext.
STATUS_FLT_DELETING_OBJECT
Экземпляр, указанный в параметре экземпляра, отключается. Это код ошибки.
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 (include Fltkernel.h)
библиотеки	FltMgr.lib
DLL	FltMgr.sys
IRQL	<= APC_LEVEL.