Définition de contextes

Après avoir créé un contexte, un pilote de minifiltre peut l’attacher à un objet en appelant l’une des routines définies suivantes :

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

La routine définie effectue les opérations suivantes, en fonction de la valeur du paramètre Operation :

• Si l’opération == FLT_SET_CONTEXT_KEEP_IF_EXISTS :

  • Si le minifiltre n’a pas encore défini un contexte du même type pour l’objet, la routine de définition :
    • Attache le contexte nouvellement alloué à l’objet.
    • Incrémente le nombre de références.
  • Sinon, si le minifiltre a déjà défini un contexte, la routine définie :
    • Retourne STATUS_FLT_CONTEXT_ALREADY_DEFINED (code d’erreur NTSTATUS).
    • Ne remplace pas le contexte existant.
    • N’incrémente pas le nombre de références.
    • Stocke un pointeur vers le contexte existant dans le paramètre OldContext s’il n’est pas NULL. Lorsque ce pointeur n’est plus nécessaire, le pilote de minifiltre doit le libérer en appelant FltReleaseContext.

• Si l’opération == FLT_SET_CONTEXT_REPLACE_IF_EXISTS :

  • La routine définie attache toujours le nouveau contexte à l’objet.
  • Si le pilote de minifiltre a déjà défini un contexte, la routine définie :
    • Supprime le contexte existant, définit le nouveau contexte et incrémente le nombre de références sur le nouveau contexte.
    • Si le paramètre OldContext n’a pas la valeur NULL, il reçoit un pointeur vers le contexte supprimé. Lorsque ce pointeur n’est plus nécessaire, le pilote de minifiltre doit le libérer en appelant FltReleaseContext.

Une fois qu’un type de contexte a été défini, un minifiltre peut obtenir un contexte lors des opérations d’E/S suivantes pour déterminer s’il doit effectuer une action.

Tous les ensembles de contextes réussis doivent être supprimés.

Dans l’exemple de code suivant, tiré de l’exemple de minifiltre CTX, la routine CtxInstanceSetup crée et définit un contexte instance :

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;

Notez qu’après l’appel à FltSetInstanceContext, il y a un appel à FltReleaseContext pour libérer le nombre de références qui a été défini par FltAllocateContext (et nonpar FltSetInstanceContext). Cela est expliqué dans Libération de contextes.