Impostazione dei contesti

Dopo aver creato un nuovo contesto, un driver minifiltro può collegarlo a un oggetto chiamando una delle routine set seguenti:

• FltSetFileContext
• FltSetInstanceContext
• FltSetStreamContext
• FltSetStreamHandleContext
• FltSetTransactionContext
• FltSetVolumeContext

La routine set esegue le operazioni seguenti, a seconda del valore del parametro Operation :

• If Operation == FLT_SET_CONTEXT_KEEP_IF_EXISTS:

  • Se il minifiltro non ha già impostato un contesto dello stesso tipo per l'oggetto, la routine set:
    • Associa il contesto appena allocato all'oggetto .
    • Incrementa il conteggio dei riferimenti.
  • In caso contrario, se il minifiltro ha già impostato un contesto, la routine set:
    • Restituisce STATUS_FLT_CONTEXT_ALREADY_DEFINED (codice di errore NTSTATUS).
    • Non sostituisce il contesto esistente.
    • Non incrementa il conteggio dei riferimenti.
    • Archivia un puntatore al contesto esistente nel parametro OldContext se non è NULL. Quando questo puntatore non è più necessario, il driver minifiltro deve rilasciarlo chiamando FltReleaseContext.

• If Operation == FLT_SET_CONTEXT_REPLACE_IF_EXISTS:

  • La routine set collega sempre il nuovo contesto all'oggetto .
  • Se il driver minifilter ha già impostato un contesto, la routine set:
    • Elimina il contesto esistente, imposta il nuovo contesto e incrementa il conteggio dei riferimenti nel nuovo contesto.
    • Se il parametro OldContext non è NULL, riceve un puntatore al contesto eliminato. Quando questo puntatore non è più necessario, il driver minifiltro deve rilasciarlo chiamando FltReleaseContext.

Dopo aver impostato un tipo di contesto, un minifiltro può ottenere un contesto durante le operazioni di I/O successive per determinare se deve eseguire qualsiasi azione.

Ogni set di contesto riuscito deve essere eliminato.

Nell'esempio di codice seguente, tratto dal minifiltro di esempio CTX, la routine CtxInstanceSetup crea e imposta un contesto di istanza:

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;

Si noti che dopo la chiamata a FltSetInstanceContext, viene eseguita una chiamata a FltReleaseContext per rilasciare il conteggio dei riferimenti impostato da FltAllocateContext (non FltSetInstanceContext). Questo è illustrato in Rilascio dei contesti.