Elaborazione delle segnalazioni di notifica.

Il motore di filtro chiama la funzione callout notifyFn di un callout per notificare il driver del callout sugli eventi associati.

Aggiunta filtro

Quando un filtro che specifica un callout per l'azione viene aggiunto al motore di filtro, quest'ultimo chiama la funzione notifyFn del callout, passando FWPS_CALLOUT_NOTIFY_ADD_FILTER nel parametro notifyType.

Un driver callout può registrare un callout con il motore di filtro dopo che i filtri che richiedono il callout per la loro azione sono già stati aggiunti al motore di filtro. In questo caso, il motore di filtro non chiama la funzione callout notifyFn del callout per notificare riguardo a uno dei filtri esistenti.

Il motore di filtro chiama la funzione di notifica notifyFn del callout solo quando vengono aggiunti nuovi filtri al motore di filtro che specificano il callout per l'azione del filtro. In questa situazione, la funzione callout notifyFn del callout potrebbe non essere chiamata per ogni filtro nel motore di filtro che specifica il callout per l'azione del filtro.

Se un driver callout registra un callout dopo l'avvio del motore di filtro e il callout deve ricevere informazioni su ogni filtro nel motore di filtro che specifica il callout per l'azione del filtro, il driver del callout deve chiamare le funzioni di gestione appropriate per enumerare tutti i filtri nel motore di filtro. Il driver di callout deve ordinare nell'elenco risultante di tutti i filtri per trovare quelli che specificano il callout per l'azione del filtro. Per altre informazioni sulla chiamata di queste funzioni, vedere Chiamata di altre funzioni della piattaforma di filtro di Windows.

Eliminazione filtro

Quando un filtro che specifica un callout per l'azione del filtro viene eliminato dal motore di filtro, il motore di filtro chiama la funzione notifyFn del callout e passa FWPS_CALLOUT_NOTIFY_DELETE_FILTER come parametro notifyType e NULL come parametro filterKey. Il motore di filtro chiama la funzione di callout notifyFn per ogni filtro eliminato nel motore di filtro che specifica il callout per l'azione del filtro. Sono inclusi tutti i filtri aggiunti al motore di filtro prima che il driver del callout abbia registrato il callout con il motore di filtro. Pertanto, un callout potrebbe ricevere notifiche di eliminazione del filtro per i filtri per cui non ha ricevuto notifiche di aggiunta di filtri.

Se la funzione di callout notifyFn non riconosce il tipo di notifica passato nel parametro notifyType, deve ignorare la notifica e restituire STATUS_SUCCESS.

Un driver callout può specificare un contesto da associare a un filtro quando il filtro viene aggiunto al motore di filtro. Tale contesto è opaco per il motore di filtro. La funzione callout classifyFn del callout può usare questo contesto per salvare le informazioni sullo stato per la successiva chiamata dal motore di filtro. Quando il filtro viene eliminato dal motore di filtro, il callout driver esegue qualsiasi operazione di pulizia necessaria del contesto.

Per esempio:

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