Função FltSetStreamContext (fltkernel.h)

A rotina FltSetStreamContext define um contexto para um fluxo de arquivos.

Sintaxe

NTSTATUS FLTAPI FltSetStreamContext(
  [in]  PFLT_INSTANCE             Instance,
  [in]  PFILE_OBJECT              FileObject,
  [in]  FLT_SET_CONTEXT_OPERATION Operation,
  [in]  PFLT_CONTEXT              NewContext,
  [out] 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 fluxo de arquivos.

[in] FileObject

Um ponteiro para um objeto de arquivo para o fluxo de arquivos.

[in] Operation

Sinalizar 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 Instância, FltSetStreamContext o substituirá pelo contexto especificado em NewContext. Caso contrário, ele inserirá NewContext na lista de contextos para o fluxo de arquivos.
FLT_SET_CONTEXT_KEEP_IF_EXISTS Se um contexto já estiver definido para esta Instância, FltSetStreamContext retornará STATUS_FLT_CONTEXT_ALREADY_DEFINED e não substituirá o contexto existente ou incrementará a contagem de referências. Se um contexto ainda não tiver sido definido, a rotina inserirá NewContext na lista de contextos para o fluxo de arquivos e incrementará a contagem de referências.

[in] NewContext

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

[out] OldContext

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

Valor retornado

A rotina fltSetStreamContext 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 Operação, esse código de erro indica que um contexto de fluxo já está anexado ao fluxo de arquivos.
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 o 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 demolida. 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 fluxo válido ou um valor inválido foi especificado para o parâmetro Operation . Este é um código de erro.
STATUS_NOT_SUPPORTED O sistema de arquivos não dá suporte a contextos por fluxo para esse fluxo de arquivos. 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 FltSetStreamContext para anexar um contexto de fluxo a um fluxo de arquivos ou para remover ou substituir um contexto de fluxo existente. Um driver de minifiltro pode anexar um contexto por instância de driver de minifiltro ao fluxo de arquivos.

FltSetStreamContext não pode ser chamado em um FileObject não aberto. Portanto, ele 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 driver de minifiltro pode alocar e configurar o contexto 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 de fluxo no fluxo no retorno de chamada pós-criação.

Contagem de referência

Se FltSetStreamContext for bem-sucedido:

  • A contagem de referências no NewContext é incrementada. Quando NewContext não é mais necessário, o minifiltro deve chamar FltReleaseContext para diminuir sua contagem de referência.

Caso contrário, se FltSetStreamContext falhar:

  • A contagem de referências no NewContext permanece inalterada.
  • Se OldContext não for NULL e não apontar para NULL_CONTEXT , o OldContext será um ponteiro referenciado para o contexto atualmente associado ao fluxo. O filtro que chama FltSetStreamContext 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 FltSetStreamContext deve chamar FltReleaseContext para diminuir a contagem de referência no objeto NewContext que foi incrementado por FltAllocateContext.

Para obter mais informações, consulte Contextos de Referência.

Outras operações de contexto

Para obter mais informações, consulte Contextos de Configuração e Liberação de Contextos:

Requisitos

   
Cliente mínimo com suporte Disponível e com suporte no Microsoft Windows 2000 Update Rollup 1 para SP4, Windows XP SP2, Windows Server 2003 SP1 e sistemas operacionais posteriores.
Plataforma de Destino Universal
Cabeçalho fltkernel.h (include Fltkernel.h)
Biblioteca FltMgr.lib
DLL Fltmgr.sys
IRQL <= APC_LEVEL

Confira também

FltAllocateContext

FltDeleteContext

FltDeleteStreamContext

FltGetStreamContext

FltReleaseContext