Referenciando contextos

O Gerenciador de Filtros usa a contagem de referências para gerenciar o tempo de vida de um contexto de 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 conjunto de contexto ou get bem-sucedido, o FltMgr incrementa a contagem de referência do contexto por 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 o FltMgr eventualmente a libera.

O FltMgr libera a referência inicial ao contexto (diminui a contagem de referência para zero) quando o objeto está sendo dividido e, em seguida, chama o retorno de chamada de limpeza de contexto opcional do filtro. Embora isso raramente ocorra, se um minifiltro precisar remover um contexto de um objeto antes do teardown, 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 pequeno exemplo de histórico de contagem de referência para um objeto típico. Suponha que todas as chamadas à API flt tenham êxito.

Filtrar retorno de chamada	API flt chamada	Contagem de referência de contexto	Descrição
Pré-Criar	FltAllocateContext	1	O filtro está processando uma pré-criação e decide que talvez queira acompanhar o arquivo. Ele aloca um contexto de fluxo, o que faz com que o FltMgr inicialize a contagem de referência como 1. O filtro passa o contexto para o retorno de chamada PostCreate por meio do parâmetro CompletionContext .
PostCreate	FltSetStreamContext	2	O filtro passou o contexto alocado durante PreCreate para seu retorno de chamada PostCreate . A criação foi bem-sucedida, de modo que o filtro anexa o contexto, o que faz com que o FltMgr incremente a contagem de referência.
PostCreate	FltReleaseContext	1	Como FltSetStreamContext incrementou a contagem de referência, o filtro precisa remover a contagem extra. A contagem de referência é 1 depois que o filtro libera o contexto, portanto, o contexto permanece ativo. Se o filtro decidisse que não se importava com esse arquivo, ele poderia ter ignorado a chamada de FltSetStreamContext e simplesmente chamado FltReleaseContext. Nesse caso, a contagem teria ido para 0 e o contexto teria sido desalocado.
PreRead	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, para que ele saiba que deseja rastrear esse arquivo. FltMgr incrementa a contagem de referência.
PreRead	FltReleaseContext	1	O filtro é feito usando seu contexto, portanto, ele o libera, fazendo com que a contagem de referência seja decrementada. Cada Contexto FltGet* precisa ser equilibrado com um FltReleaseContext.
Pré-limpeza	FltGetStreamContext	2	O filtro solicita e obtém seu contexto, o que incrementa a contagem de referência.
Pré-limpeza	FltReleaseContext	1	O filtro é feito usando o contexto para liberá-lo, o que diminui a contagem de referências.
Retorno de chamada de limpeza de contexto		0	O sistema de arquivos está derrubando o objeto de fluxo subjacente. (No caso específico de um objeto de fluxo, o teardown é disparado por IRP_MJ_CLOSE). O FltMgr diminui a contagem de referência para 0 e, em seguida, chama o retorno de chamada de limpeza de contexto do filtro. O filtro agora tem a oportunidade de limpo seu contexto.