Définition de contextes

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

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

La routine set 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 minifilter n’a pas encore défini de contexte du même type pour l’objet, la routine définie :
    • Attache le contexte nouvellement alloué à l’objet.
    • Incrémente le nombre de références.
  • Sinon, si le minifilter 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 minifilter doit le libérer en appelant FltReleaseContext.

• Si l’opération == FLT_SET_CONTEXT_REPLACE_IF_EXISTS :

  • La routine set attache toujours le nouveau contexte à l’objet.
  • Si le pilote minifilter 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’est pas NULL, il reçoit un pointeur vers le contexte supprimé. Lorsque ce pointeur n’est plus nécessaire, le pilote minifilter doit le libérer en appelant FltReleaseContext.

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

Chaque jeu de contextes réussi doit éventuellement être supprimé.

Dans l’exemple de code suivant, extrait de l’exemple CTX minifilter, la routine CtxInstanceSetup crée et définit un contexte d’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 existe un appel à FltReleaseContext pour libérer le nombre de références défini par FltAllocateContext (et non FltSetInstanceContext). Cela est expliqué dans La publication de contextes.