Compartilhar via


Função FltSetFileContext (fltkernel.h)

A rotina FltSetFileContext define um contexto para um arquivo.

Sintaxe

NTSTATUS FLTAPI FltSetFileContext(
  [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 opaco para uma instância de driver de minifiltro para o chamador. Esse parâmetro é necessário e não pode ser NULL.

[in] FileObject

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

[in] Operation

Um sinalizador que especifica o tipo de operação a ser executada por FltSetFileContext . Esse parâmetro deve ser um dos seguintes sinalizadores:

Sinalizador Significado
FLT_SET_CONTEXT_REPLACE_IF_EXISTS Se um contexto já estiver definido para o arquivo para o qual o parâmetro FileObject aponta, FltSetFileContext substituirá esse contexto pelo contexto especificado em NewContext. Caso contrário, ele inserirá NewContext na lista de contextos do arquivo.
FLT_SET_CONTEXT_KEEP_IF_EXISTS Se um contexto já estiver definido para o arquivo para o qual FileObject aponta, FltSetFileContext 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 tiver sido definido, a rotina inserirá o contexto especificado em NewContext na lista de contextos para o arquivo e incrementará a contagem de referência.

[in] NewContext

Um ponteiro para o novo contexto a ser definido para o arquivo. 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 arquivo existente para a instância apontada pelo parâmetro Instance , 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

A rotina FltSetFileContext 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 ao arquivo.
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.
STATUS_NOT_SUPPORTED Não há suporte para contextos de arquivo para este arquivo. 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 FltSetFileContext para definir ou substituir seu próprio contexto de arquivo em um arquivo. Um driver de minifiltro pode anexar apenas um contexto por instância de driver de minifiltro ao arquivo.

FltSetFileContext não pode ser chamado em um FileObject não aberto. Portanto, FltSetFileContext não pode ser chamado de um retorno de chamada de pré-criação para um arquivo porque o arquivo não foi aberto nesse momento. No entanto, um driver de minifiltro pode alocar e configurar o contexto do arquivo 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 arquivo no arquivo correspondente a esse fluxo no retorno de chamada pós-criação.

Contagem de referências

Se FltSetFileContext for bem-sucedido:

  • A contagem de referência em 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 FltSetFileContext 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 arquivo. O filtro que chama FltSetFileContext 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 FltSetFileContext deve chamar FltReleaseContext para decrementar 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 a partir do Windows Vista.
Plataforma de Destino Universal
Cabeçalho fltkernel.h (inclua Fltkernel.h)
Biblioteca Fltmgr.lib
DLL Fltmgr.sys
IRQL <= APC_LEVEL

Confira também

FLT_CONTEXT_REGISTRATION

FltAllocateContext

FltDeleteContext

FltDeleteFileContext

FltGetFileContext

FltReleaseContext

FltSupportsFileContexts

FltSupportsFileContextsEx