Definindo contextos

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

• FltSetFileContext
• FltSetInstanceContext
• FltSetStreamContext
• FltSetStreamHandleContext
• FltSetTransactionContext
• Contexto de Volume FltSetVolumeContext

A rotina definida 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 de 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 definida:
    • 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 definida sempre anexa o novo contexto ao objeto.
  • Se o driver de minifiltro já tiver definido um contexto, a rotina definida:
    • Exclui o contexto existente, define o novo contexto e incrementa a contagem de referência 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 é definido, um minifiltro pode obter um contexto durante as operações de E/S subsequentes para determinar se ele precisa executar alguma ação.

Todo conjunto de contexto bem-sucedido deve 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ão FltSetInstanceContext). Isso é explicado em Liberando contextos.