Função FltSetVolumeContext (fltkernel.h)

  • Artigo

FltSetVolumeContext define um contexto para um volume.

Sintaxe

NTSTATUS FLTAPI FltSetVolumeContext(
  [in]            PFLT_VOLUME               Volume,
  [in]            FLT_SET_CONTEXT_OPERATION Operation,
  [in]            PFLT_CONTEXT              NewContext,
  [out, optional] PFLT_CONTEXT              *OldContext
);

Parâmetros

[in] Volume

Ponteiro de volume opaco para o volume.

[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 Volume, FltSetVolumeContext o substituirá por NewContext>. Caso contrário, ele inserirá NewContext na lista de contextos para o volume.
FLT_SET_CONTEXT_KEEP_IF_EXISTS Se um contexto já estiver definido para esse volume, FltSetVolumeContext 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á NewContext na lista de contextos para o volume e incrementará a contagem de referência.

[in] NewContext

Ponteiro para o novo contexto a ser definido para o volume. Esse parâmetro é necessário e não pode ser NULL.

[out, optional] OldContext

Ponteiro para uma variável alocada pelo chamador que recebe o endereço do contexto de volume existente para Volume. 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

FltSetVolumeContext 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 já está anexado ao volume.
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 O Volume especificado está sendo derrubado. 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 volume válido ou um valor inválido foi especificado para 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 FltSetVolumeContext para anexar um contexto a um volume ou para remover ou substituir um contexto de volume existente. Um driver de minifiltro pode anexar apenas um contexto a um volume.

Contagem de referências

Se FltSetVolumeContext 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 FltSetVolumeContext 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 volume. O filtro que chama FltSetVolumeContext 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 FltSetVolumeContext 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 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

FltDeleteVolumeContext

FltGetVolumeContext

FltReleaseContext