Função FltSetTransactionContext (fltkernel.h)

Artigo
08/07/2023

A rotina FltSetTransactionContext define um contexto em uma transação.

Sintaxe

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
);

Parâmetros

[in] Instance

Ponteiro de instância opaco para o chamador.

[in] Transaction

Ponteiro de transação opaco para a transação na qual o contexto está sendo definido.

[in] Operation

Sinalizador que especifica os detalhes da operação a ser executada. Esse parâmetro deve ser um dos seguintes:

Sinalizador	Significado
FLT_SET_CONTEXT_REPLACE_IF_EXISTS	Se um contexto já estiver definido para a transação apontada pelo parâmetro Transaction , FltSetTransactionContext o substituirá pelo contexto apontado pelo parâmetro NewContext . Caso contrário, ele definirá o contexto apontado pelo parâmetro NewContext como o contexto para a transação apontada pelo parâmetro Transaction .
FLT_SET_CONTEXT_KEEP_IF_EXISTS	Se um contexto já estiver definido para a transação apontada pelo parâmetro Transaction , FltSetTransactionContext retornará STATUS_FLT_CONTEXT_ALREADY_DEFINED e não substituirá o contexto existente ou incrementará a contagem de referência. Se um contexto ainda não tiver sido definido, essa rotina definirá o contexto apontado pelo parâmetro NewContext como o contexto para transação apontado pelo parâmetro Transaction e incrementará a contagem de referência.

Sinalizador

Significado

FLT_SET_CONTEXT_REPLACE_IF_EXISTS

Se um contexto já estiver definido para a transação apontada pelo parâmetro Transaction , FltSetTransactionContext o substituirá pelo contexto apontado pelo parâmetro NewContext . Caso contrário, ele definirá o contexto apontado pelo parâmetro NewContext como o contexto para a transação apontada pelo parâmetro Transaction .

FLT_SET_CONTEXT_KEEP_IF_EXISTS

Se um contexto já estiver definido para a transação apontada pelo parâmetro Transaction , FltSetTransactionContext retornará STATUS_FLT_CONTEXT_ALREADY_DEFINED e não substituirá o contexto existente ou incrementará a contagem de referência. Se um contexto ainda não tiver sido definido, essa rotina definirá o contexto apontado pelo parâmetro NewContext como o contexto para transação apontado pelo parâmetro Transaction e incrementará a contagem de referência.

[in] NewContext

Ponteiro para o novo contexto a ser definido para a transação. Esse parâmetro é necessário e não pode ser NULL.

[out, optional] OldContext

Ponteiro para uma variável alocada pelo chamador que recebe o endereço do contexto de transação existente, se já estiver definido. Esse parâmetro é opcional e pode ser NULL. Para obter mais informações sobre esse parâmetro, consulte a seção Comentários a seguir.

Retornar valor

FltSetTransactionContext retorna STATUS_SUCCESS ou um valor NTSTATUS apropriado, como um dos seguintes:

Código de retorno	Descrição
STATUS_FLT_CONTEXT_ALREADY_DEFINED	Se FLT_SET_CONTEXT_KEEP_IF_EXISTS foi especificado para o parâmetro Operation , esse código de erro indica que um contexto já está anexado à transação. Somente um contexto pode ser anexado a uma transação para um determinado driver de minifiltro.
STATUS_FLT_CONTEXT_ALREADY_LINKED	O contexto apontado pelo parâmetro NewContext já está vinculado a um objeto . Em outras palavras, esse código de erro indica que NewContext já está em uso devido a uma chamada anterior bem-sucedida de uma rotina de ContextoXxx do FltSet.
STATUS_FLT_DELETING_OBJECT
A instância especificada no parâmetro Instance está sendo interrompida. Este é um código de erro.
STATUS_INVALID_PARAMETER	Um parâmetro inválido foi passado. Por exemplo, o parâmetro NewContext não aponta para um contexto de transação válido ou um valor inválido foi especificado para o parâmetro Operation . Este é um código de erro.

Comentários

Para obter mais informações sobre contextos, consulte Sobre contextos de minifiltro.

Um driver de minifiltro chama FltSetTransactionContext para anexar um contexto a uma transação ou remover ou substituir um contexto de transação existente. Um driver de minifiltro pode anexar apenas um contexto a uma determinada transação.

Contagem de referências

Se FltSetTransactionContext for bem-sucedido:

A contagem de referência em NewContext é incrementada. Quando NewContext não for mais necessário, o minifiltro deverá chamar FltReleaseContext para diminuir sua contagem de referência.

Caso contrário, se FltSetTransactionContext falhar:

A contagem de referência em NewContext permanece inalterada.
Se OldContext não for NULL e não apontar para NULL_CONTEXT , OldContext será um ponteiro referenciado para o contexto atualmente associado à transação. O filtro que chama FltSetTransactionContext deve chamar FltReleaseContext para OldContext também quando o ponteiro de contexto não for mais necessário.

Independentemente do sucesso:

O filtro que chama FltSetTransactionContext deve chamar FltReleaseContext para diminuir a contagem de referência no objeto NewContext que foi incrementado por FltAllocateContext.

Para obter mais informações, consulte Referenciando contextos.

Outras operações de contexto

Para obter mais informações, consulte Configurando contextos e Liberando contextos:

Para alocar um novo contexto, chame FltAllocateContext.

Para obter um contexto de transação, chame FltGetTransactionContext.

Para excluir um contexto de transação, chame FltDeleteTransactionContext ou FltDeleteContext.

Requisitos

Requisito	Valor
Cliente mínimo com suporte	Disponível e com suporte no Windows Vista e em sistemas operacionais posteriores.
Plataforma de Destino	Universal
Cabeçalho	fltkernel.h (inclua Fltkernel.h)
Biblioteca	FltMgr.lib
DLL	FltMgr.sys
IRQL	<= APC_LEVEL.