Fazendo referência a contextos

O Gerenciador de filtros usa a contagem de referência para gerenciar o tempo de vida de um contexto do minifiltro. Uma contagem de referência é um número que indica o estado de um contexto.

Sempre que um contexto é criado com êxito, o FltMgr Inicializa a contagem de referência do contexto para um. Isso é chamado de referência inicial ao contexto.

Sempre que um contexto é referenciado, por exemplo, por um contexto bem-sucedido definido ou Get, fltmgr incrementa a contagem de referência do contexto em um.

Quando um contexto não é mais necessário, sua contagem de referência deve ser decrementada. Uma contagem de referência positiva significa que o contexto é utilizável. Quando a contagem de referência se torna zero, o contexto é inutilizável e FltMgr eventualmente a libera.

FltMgr libera a referência inicial para o contexto (diminui a contagem de referência para zero) quando o objeto está sendo interrompido e, em seguida, chama o retorno de chamada de limpeza de contextoopcional do filtro. Embora isso raramente ocorra, se um minifiltro precisar remover um contexto de um objeto antes da subdivisão, o minifiltro deverá liberar com segurança essa referência inicial ao contexto chamando FltDeleteContext.

Um minifiltro pode adicionar sua própria referência a um contexto chamando FltReferenceContext para incrementar a contagem de referência do contexto. O minifiltro deve eventualmente remover essa referência adicionada chamando FltReleaseContext.

Veja a seguir um breve exemplo de histórico de contagem de referência para um objeto típico. Suponha que todas as chamadas à API FLT tenham sucesso.

Retorno de chamada de filtro API FLT chamada Contagem de referência de contexto Descrição
Precriar FltAllocateContext 1 O filtro está processando uma pré-criação e decide que pode ser útil controlar o arquivo. Ele aloca um contexto de fluxo, o que faz com que FltMgr inicialize a contagem de referência como 1. O filtro passa o contexto para seu retorno de chamada de createcreate por meio do parâmetro CompletionContext .
Criar FltSetStreamContext 2 O filtro passou o contexto que ele alocou durante a precriar para seu retorno de chamada de createcreate . A criação foi bem-sucedida e, portanto, o filtro anexa o contexto, o que faz com que FltMgr aumente a contagem de referência.
Criar FltReleaseContext 1 Como FltSetStreamContext incrementou a contagem de referência, o filtro precisa remover a contagem extra. A contagem de referência é 1 após o filtro liberar o contexto, portanto, o contexto permanece ativo. Se o filtro tiver decidido que não se preocupava com esse arquivo, ele poderia ter ignorado a chamada de FltSetStreamContext e simplesmente chamado de FltReleaseContext. Nesse caso, a contagem teria passado para 0 e o contexto teria sido desalocado.
Li FltGetStreamContext 2 O filtro vê uma e/s de leitura e deseja saber se está rastreando esse arquivo. Ele solicita seu contexto de fluxo e o Obtém, portanto, ele sabe que deseja controlar esse arquivo. FltMgr incrementa a contagem de referência.
Li FltReleaseContext 1 O filtro é feito usando seu contexto e, portanto, o libera, fazendo com que a contagem de referência seja decrementada. Cada contexto FltGet * precisa ser balanceado com um FltReleaseContext.
Prelimpeza FltGetStreamContext 2 O filtro solicita e obtém seu contexto, que incrementa a contagem de referência.
Prelimpeza FltReleaseContext 1 O filtro é feito usando o contexto, portanto, libera-o, o que decrementa a contagem de referência.
Retorno de chamada de limpeza de contexto 0 O sistema de arquivos está subdividindo o objeto de fluxo subjacente. (No caso específico de um objeto de fluxo, a subdivisão é disparada por IRP_MJ_CLOSE). FltMgr decrementa a contagem de referência para 0 e, em seguida, chama o retorno de chamada de limpeza de contexto do filtro. Agora, o filtro tem a oportunidade de limpar seu contexto.