Verarbeitung von Benachrichtigungs-Legenden

Das Filtermodul ruft die Calloutfunktion notifyFn einer Legende auf, um den Legendentreiber über Ereignisse zu benachrichtigen, die der Legende zugeordnet sind.

Filterzugabe

Wenn der Filter-Engine ein Filter hinzugefügt wird, der eine Beschriftung für die Aktion des Filters angibt, ruft die Filter-Engine die Calloutfunktion notifyFn der Legende auf und übergibt FWPS_CALLOUT_NOTIFY_ADD_FILTER im notifyType-Parameter .

Ein Legendentreiber kann eine Legende bei der Filter-Engine registrieren, nachdem Filter, die die Legende für die Aktion des Filters angeben, der Filter-Engine bereits hinzugefügt wurden. In dieser Situation ruft die Filter-Engine die Calloutfunktion notifyFn der Legende nicht auf, um die Legende über einen der vorhandenen Filter zu benachrichtigen.

Das Filtermodul ruft nur die Beschriftungsfunktion notifyFn der Legende auf, um die Legende zu benachrichtigen, wenn der Filter-Engine neue Filter hinzugefügt werden, die die Legende für die Aktion des Filters angeben. In dieser Situation wird die Beschriftungsfunktion notifyFn einer Legende möglicherweise nicht für jeden Filter in der Filter-Engine aufgerufen, der die Legende für die Aktion des Filters angibt.

Wenn ein Legendentreiber eine Legende registriert, nachdem die Filter-Engine gestartet wurde und die Legende Informationen zu jedem Filter in der Filter-Engine erhalten muss, der die Legende für die Aktion des Filters angibt, muss der Legendentreiber die entsprechenden Verwaltungsfunktionen aufrufen, um alle Filter in der Filter-Engine aufzulisten. Der Legendentreiber muss die resultierende Liste aller Filter sortieren, um die Filter zu finden, die die Beschriftung für die Aktion des Filters angeben. Weitere Informationen zum Aufrufen dieser Funktionen finden Sie unter Aufrufen anderer Windows-Filterplattformfunktionen .

Filterlöschung

Wenn ein Filter, der eine Legende für die Aktion des Filters angibt, aus der Filter-Engine gelöscht wird, ruft die Filter-Engine die Calloutfunktion notifyFn der Legende auf und übergibt FWPS_CALLOUT_NOTIFY_DELETE_FILTER im notifyType-Parameter und NULL im filterKey-Parameter . Die Filter-Engine ruft die Beschriftungsfunktion notifyFn der Legende für jeden gelöschten Filter in der Filter-Engine auf, die die Legende für die Aktion des Filters angibt. Dies schließt alle Filter ein, die der Filter-Engine hinzugefügt wurden, bevor der Legendentreiber die Legende bei der Filter-Engine registriert hat. Daher kann eine Legende Filterlöschbenachrichtigungen für Filter erhalten, für die sie keine Filter-Add-Benachrichtigungen empfangen hat.

Wenn die Calloutfunktion notifyFn der Legende die Art der Benachrichtigung nicht erkennt, die im notifyType-Parameter übergeben wird, sollte sie die Benachrichtigung ignorieren und STATUS_SUCCESS zurückgeben.

Ein Legendentreiber kann einen Kontext angeben, der einem Filter zugeordnet werden soll, wenn der Filter der Filter-Engine hinzugefügt wird. Ein solcher Kontext ist für die Filter-Engine undurchsichtig. Die Legendenfunktion klassifizierenFn kann diesen Kontext verwenden, um Zustandsinformationen für das nächste Mal zu speichern, wenn sie von der Filter-Engine aufgerufen wird. Wenn der Filter aus der Filter-Engine gelöscht wird, führt der Legendentreiber alle erforderlichen Bereinigungen des Kontexts durch.

Beispiel:

// 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;
}