Função FltSetVolumeContext (fltkernel.h)

Artigo
08/07/2023

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:

Para alocar um novo contexto, chame FltAllocateContext.
Para obter um contexto de volume, chame FltGetVolumeContext.
Para excluir um contexto de volume, chame FltDeleteVolumeContext ou FltDeleteContext.

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