Função FltSetInstanceContext (fltkernel.h)

Artigo
08/07/2023

FltSetInstanceContext define um contexto para uma instância de driver de minifiltro.

Sintaxe

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

Parâmetros

[in] Instance

Ponteiro de instância opaco para a instância.

[in] Operation

Sinalizador especificando 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 instância para a qual o parâmetro Instance aponta, FltSetInstanceContext substituirá esse contexto pelo contexto especificado em NewContext. Caso contrário, ele definirá NewContext como o contexto de Instance.
FLT_SET_CONTEXT_KEEP_IF_EXISTS	Se um contexto já estiver definido para essa Instância, FltSetInstanceContext retornará STATUS_FLT_CONTEXT_ALREADY_DEFINED e não substituirá o contexto existente nem incrementará a contagem de referência. Se um contexto ainda não estiver definido, a rotina definirá NewContext como o contexto de Instance e incrementará a contagem de referência.

[in] NewContext

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

[out] OldContext

Ponteiro para uma variável alocada pelo chamador que recebe o endereço do contexto de instância existente, se já estiver definida. 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

FltSetInstanceContext 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 à instância. Somente um contexto pode ser anexado a uma instância.
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 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 arquivo 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 FltSetInstanceContext para anexar um contexto de instância a uma instância de driver de minifiltro de propriedade do chamador ou para remover ou substituir um contexto de instância existente. Um driver de minifiltro pode anexar apenas um contexto a uma instância.

Contagem de referências

Se FltSetInstanceContext for bem-sucedido:

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

Caso contrário, se FltSetInstanceContext 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 à instância. O filtro que chama FltSetInstanceContext deve eventualmente chamar FltReleaseContext para OldContext também quando o ponteiro de contexto não for mais necessário.

Independentemente do sucesso:

O filtro que chama FltSetInstanceContext 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 Definindo contextos e Liberando contextos:

Para alocar um novo contexto, chame FltAllocateContext.
Para obter um contexto de instância, chame FltGetInstanceContext.
Para excluir um contexto de instância, chame FltDeleteInstanceContext ou FltDeleteContext.

Requisitos

Requisito	Valor
Cliente mínimo com suporte	Disponível e com suporte no Pacote Cumulativo de Atualizações 1 do Microsoft Windows 2000 para SP4, Windows XP SP2, Windows Server 2003 SP1 e versões posteriores do sistema operacional.
Plataforma de Destino	Universal
Cabeçalho	fltkernel.h (inclua Fltkernel.h)
Biblioteca	FltMgr.lib
DLL	Fltmgr.sys
IRQL	<= APC_LEVEL