Compartilhar via


Função FltSetTransactionContext (fltkernel.h)

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.

[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 obter um contexto de transação, chame FltGetTransactionContext.

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.

Confira também

FltAllocateContext

FltCommitComplete

FltDeleteContext

FltDeleteTransactionContext

FltEnlistInTransaction

FltGetTransactionContext

FltPrepareComplete

FltPrepareComplete

FltReleaseContext

FltRollbackComplete

FltRollbackEnlistment