Função FltSetStreamHandleContext (fltkernel.h)

Artigo
08/07/2023

A rotina FltSetStreamHandleContext define um contexto para um identificador de fluxo.

Sintaxe

NTSTATUS FLTAPI FltSetStreamHandleContext(
  [in]            PFLT_INSTANCE             Instance,
  [in]            PFILE_OBJECT              FileObject,
  [in]            FLT_SET_CONTEXT_OPERATION Operation,
  [in]            PFLT_CONTEXT              NewContext,
  [out, optional] PFLT_CONTEXT              *OldContext
);

Parâmetros

[in] Instance

Um ponteiro de instância opaco para a instância do driver de minifiltro cujo contexto deve ser inserido, removido ou substituído na lista de contextos anexados ao identificador de fluxo.

[in] FileObject

Um ponteiro para um objeto de arquivo para o fluxo de arquivos. Esse parâmetro é necessário e não pode ser NULL.

[in] Operation

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

Valor	Significado
FLT_SET_CONTEXT_REPLACE_IF_EXISTS	Se um contexto já estiver definido para esta Instância, FltSetStreamHandleContext o substituirá pelo contexto especificado em NewContext. Caso contrário, ele inserirá NewContext na lista de contextos do identificador de fluxo.
FLT_SET_CONTEXT_KEEP_IF_EXISTS	Se um contexto já estiver definido para esta Instância, FltSetStreamHandleContext 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, a rotina inserirá NewContext na lista de contextos para o identificador de fluxo e incrementará a contagem de referência.

[in] NewContext

Um ponteiro para o novo contexto a ser definido para o identificador de fluxo. Esse parâmetro é necessário e não pode ser NULL.

[out, optional] OldContext

Um ponteiro para uma variável alocada pelo chamador que recebe o endereço do contexto de identificador de fluxo existente para o parâmetro Instance , 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

A rotina FltSetStreamHandleContext retorna STATUS_SUCCESS ou um valor NTSTATUS apropriado, como um dos seguintes códigos de erro:

Código de retorno	Descrição
STATUS_FLT_CONTEXT_ALREADY_DEFINED	Se FLT_SET_CONTEXT_KEEP_IF_EXISTS foi especificado para Operação, esse código de erro indica que um contexto já está anexado ao identificador de fluxo.
STATUS_FLT_CONTEXT_ALREADY_LINKED	O contexto para o qual NewContext aponta 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 ContextoXxxfltSet .
STATUS_FLT_DELETING_OBJECT	A Instância especificada 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 válido do identificador de fluxo ou um valor inválido foi especificado para Operação.
STATUS_NOT_SUPPORTED	Ocorreu uma situação sem suporte, como o sistema de arquivos não dá suporte a contextos por fluxo para esse fluxo de arquivos ou o chamador forneceu um FileObject NULL.

Comentários

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

A rotina FltSetStreamHandleContext adiciona, remove ou substitui um contexto para uma instância de driver de minifiltro em um identificador de fluxo. Um driver de minifiltro pode anexar um contexto por instância do driver de minifiltro ao identificador de fluxo.

FltSetStreamHandleContext não pode ser chamado em um FileObject não aberto. Portanto, FltSetStreamHandleContext não pode ser chamado de um retorno de chamada de pré-criação para um fluxo porque o fluxo não foi aberto nesse momento. No entanto, um minifiltro pode alocar e configurar o contexto do identificador de fluxo no retorno de chamada de pré-criação, passá-lo para o retorno de chamada pós-criação usando o parâmetro de contexto de conclusão e definir o contexto do identificador de fluxo no fluxo no retorno de chamada pós-criação.

Contagem de referências

Se FltSetStreamHandleContext 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 FltSetStreamHandleContext 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 ao identificador de fluxo. O filtro que chama FltSetStreamHandleContext 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 FltSetStreamHandleContext 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 determinar se há suporte para contextos de identificador de fluxo para um determinado arquivo, chame FltSupportsStreamHandleContexts
Para alocar um novo contexto, chame FltAllocateContext.
Para obter um contexto de identificador de fluxo, chame FltGetStreamHandleContext.
Para excluir um contexto de identificador de fluxo, chame FltDeleteStreamHandleContext ou FltDeleteContext.

Requisitos

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