Elaborazione dei callout notifica

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

Addizione filtro

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

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

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

Se un driver di 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 del callout deve eseguire l'ordinamento nell'elenco risultante di tutti i filtri per trovare i filtri 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 callout notifyFn del callout del callout e passa FWPS_CALLOUT_NOTIFY_DELETE_FILTER nel parametro notifyType e NULL nel parametro filterKey . Il motore di filtro chiama la funzione callout notifyFn del callout del callout 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 registrasse il callout con il motore di filtro. Pertanto, un callout potrebbe ricevere notifiche di eliminazione filtro per i filtri per cui non ha ricevuto notifiche di aggiunta filtro.

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

Un driver di callout può specificare un contesto da associare a un filtro quando il filtro viene aggiunto al motore di filtro. Un contesto di questo tipo è opaco al motore di filtro. La funzione callout classifyFn del callout del callout 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 driver del callout esegue qualsiasi pulizia necessaria del contesto.

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