Função FltSetInstanceContext (fltkernel.h)

  • Artigo

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:

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

Confira também

FltAllocateContext

FltDeleteContext

FltDeleteInstanceContext

FltGetInstanceContext

FltReleaseContext