Função FltSetStreamContext (fltkernel.h)

  • Artigo

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

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 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ência. 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ência.

[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 pelo chamador que recebe o endereço do contexto 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 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 tiver sido especificado para Operação, esse código de erro indicará 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 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 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 ponto. 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ências

Se FltSetStreamContext 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 FltSetStreamContext 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 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 Referenciando contextos.

Outras operações de contexto

Para obter mais informações, consulte Configurando contextos e Liberando contextos:

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

Confira também

FltAllocateContext

FltDeleteContext

FltDeleteStreamContext

FltGetStreamContext

FltReleaseContext