Definindo contextos

  • Artigo

Depois de criar um novo contexto, um driver de minifiltro pode anexá-lo a um objeto chamando uma das seguintes rotinas de conjunto:

A rotina set faz o seguinte, dependendo do valor do parâmetro Operation :

  • Se a Operação == FLT_SET_CONTEXT_KEEP_IF_EXISTS:

    • Se o minifiltro ainda não tiver definido um contexto do mesmo tipo para o objeto , a rotina set:
      • Anexa o contexto recém-alocado ao objeto .
      • Incrementa a contagem de referência.
    • Caso contrário, se o minifiltro já tiver definido um contexto, a rotina de conjunto:
      • Retorna STATUS_FLT_CONTEXT_ALREADY_DEFINED (um código de erro NTSTATUS).
      • Não substitui o contexto existente.
      • Não incrementa a contagem de referência.
      • Armazena um ponteiro para o contexto existente no parâmetro OldContext se ele não for NULL. Quando esse ponteiro não for mais necessário, o driver de minifiltro deverá liberá-lo chamando FltReleaseContext.

  • Se a Operação == FLT_SET_CONTEXT_REPLACE_IF_EXISTS:

    • A rotina set sempre anexa o novo contexto ao objeto .
    • Se o driver de minifiltro já tiver definido um contexto, a rotina de definição:
      • Exclui o contexto existente, define o novo contexto e incrementa a contagem de referências no novo contexto.
      • Se o parâmetro OldContext não for NULL, ele receberá um ponteiro para o contexto excluído. Quando esse ponteiro não for mais necessário, o driver de minifiltro deverá liberá-lo chamando FltReleaseContext.

Depois que um tipo de contexto tiver sido definido, um minifiltro poderá obter um contexto durante as operações de E/S subsequentes para determinar se ele precisa executar alguma ação.

Cada conjunto de contexto bem-sucedido deve eventualmente ser excluído.

No exemplo de código a seguir, obtido do minifiltro de exemplo CTX, a rotina CtxInstanceSetup cria e define um contexto de instância:

status = FltAllocateContext(
           FltObjects->Filter,              //in: Filter
           FLT_INSTANCE_CONTEXT,            //in: ContextType
           CTX_INSTANCE_CONTEXT_SIZE,       //in: ContextSize
           NonPagedPool,                    //in: PoolType
           &instanceContext);               //out: ReturnedContext
...
status = FltSetInstanceContext(
           FltObjects->Instance,            //in: Instance
           FLT_SET_CONTEXT_KEEP_IF_EXISTS,  //in: Operation
           instanceContext,                 //in: NewContext
           NULL);                           //out: OldContext

if (instanceContext != NULL) {
  FltReleaseContext(instanceContext);
}
return status;

Observe que, após a chamada para FltSetInstanceContext, há uma chamada para FltReleaseContext para liberar a contagem de referência que foi definida por FltAllocateContext (nãoFltSetInstanceContext). Isso é explicado em Liberando Contextos.