Traitement des légendes de notification

Le moteur de filtre appelle la fonction de légende notifyFn d’une légende pour informer le pilote de légende des événements associés à la légende.

Ajout de filtre

Lorsqu’un filtre qui spécifie une légende pour l’action du filtre est ajouté au moteur de filtre, le moteur de filtre appelle la fonction de légende notifyFn de la légende, en passant FWPS_CALLOUT_NOTIFY_ADD_FILTER dans le paramètre notifyType .

Un pilote de légende peut inscrire une légende auprès du moteur de filtre une fois que les filtres qui spécifient la légende pour l’action du filtre ont déjà été ajoutés au moteur de filtre. Dans ce cas, le moteur de filtre n’appelle pas la fonction de légende notifyFn de la légende pour informer la légende de l’un des filtres existants.

Le moteur de filtre appelle uniquement la fonction de légende notifyFn de la légende pour notifier la légende lorsque de nouveaux filtres qui spécifient la légende pour l’action du filtre sont ajoutés au moteur de filtre. Dans ce cas, la fonction de légende notifyFn d’une légende peut ne pas être appelée pour chaque filtre dans le moteur de filtre qui spécifie la légende pour l’action du filtre.

Si un pilote de légende inscrit une légende après le démarrage du moteur de filtre et que la légende doit recevoir des informations sur chaque filtre dans le moteur de filtre qui spécifie la légende pour l’action du filtre, le pilote de légende doit appeler les fonctions de gestion appropriées pour énumérer tous les filtres dans le moteur de filtre. Le pilote de légende doit trier la liste résultante de tous les filtres pour rechercher les filtres qui spécifient la légende pour l’action du filtre. Pour plus d’informations sur l’appel de ces fonctions, consultez Appel d’autres fonctions de plateforme de filtrage Windows .

Suppression de filtres

Lorsqu’un filtre qui spécifie une légende pour l’action du filtre est supprimé du moteur de filtre, le moteur de filtre appelle la fonction de légende notifyFn de la légende et transmet FWPS_CALLOUT_NOTIFY_DELETE_FILTER dans le paramètre notifyType et NULL dans le paramètre filterKey . Le moteur de filtre appelle la fonction de légende notifyFn de la légende pour chaque filtre supprimé dans le moteur de filtre qui spécifie la légende pour l’action du filtre. Cela inclut tous les filtres qui ont été ajoutés au moteur de filtre avant que le pilote de légende ait inscrit la légende auprès du moteur de filtre. Par conséquent, une légende peut recevoir des notifications de suppression de filtre pour les filtres pour lesquels elle n’a pas reçu de notifications d’ajout de filtre.

Si la fonction de légende notifyFn de la légende ne reconnaît pas le type de notification passée dans le paramètre notifyType , elle doit ignorer la notification et retourner STATUS_SUCCESS.

Un pilote de légende peut spécifier un contexte à associer à un filtre lorsque le filtre est ajouté au moteur de filtre. Un tel contexte est opaque pour le moteur de filtre. La fonction de légende classifyFn de la légende peut utiliser ce contexte pour enregistrer les informations d’état pour la prochaine fois qu’elle est appelée par le moteur de filtre. Lorsque le filtre est supprimé du moteur de filtre, le pilote de légende effectue tout nettoyage nécessaire du contexte.

Par exemple :

// Context structure to be associated with the filters
typedef struct FILTER_CONTEXT_ {
  .
  .  // Driver-specific content
  .
} FILTER_CONTEXT, *PFILTER_CONTEXT;

// Memory pool tag for filter context structures
#define FILTER_CONTEXT_POOL_TAG 'fcpt'

// notifyFn callout function
NTSTATUS NTAPI
 NotifyFn(
    IN FWPS_CALLOUT_NOTIFY_TYPE  notifyType,
    IN const GUID  *filterKey,
    IN const FWPS_FILTER0  *filter
    )
{
  PFILTER_CONTEXT context;

 ASSERT(filter != NULL);

  // Switch on the type of notification
 switch(notifyType) {

    // A filter is being added to the filter engine
 case FWPS_CALLOUT_NOTIFY_ADD_FILTER:

      // Allocate the filter context structure
 context =
        (PFILTER_CONTEXT)ExAllocatePoolWithTag(
 NonPagedPool,
 sizeof(FILTER_CONTEXT),
          FILTER_CONTEXT_POOL_TAG
          );

      // Check the result of the memory allocation
 if (context == NULL) {

        // Return error
 return STATUS_INSUFFICIENT_RESOURCES;
      }

      // Initialize the filter context structure
      ...

      // Associate the filter context structure with the filter
 filter->context = (UINT64)context;

 break;

    // A filter is being removed from the filter engine
 case FWPS_CALLOUT_NOTIFY_DELETE_FILTER:

      // Get the filter context structure from the filter
 context = (PFILTER_CONTEXT)filter->context;

 // Check whether the filter has a context
 if (context) {

        // Cleanup the filter context structure
        ...

        // Free the memory for the filter context structure
 ExFreePoolWithTag(
 context,
          FILTER_CONTEXT_POOL_TAG
          );

      }
 break;

    // Unknown notification
 default:

      // Do nothing
 break;
  }

 return STATUS_SUCCESS;
}