Processando textos explicativos de notificação

O mecanismo de filtro chama a função de texto explicativo notifyFn de um texto explicativo para notificar o driver de texto explicativo sobre eventos associados ao texto explicativo.

Adição de filtro

Quando um filtro que especifica um texto explicativo para a ação do filtro é adicionado ao mecanismo de filtro, o mecanismo de filtro chama a função de texto explicativo notifyFn do texto explicativo, passando FWPS_CALLOUT_NOTIFY_ADD_FILTER no parâmetro notifyType .

Um driver de texto explicativo pode registrar um texto explicativo com o mecanismo de filtro depois que filtros que especificam o texto explicativo para a ação do filtro já foram adicionados ao mecanismo de filtro. Nessa situação, o mecanismo de filtro não chama a função de texto explicativo notifyFn do texto explicativo para notificar o texto explicativo sobre qualquer um dos filtros existentes.

O mecanismo de filtro chama apenas a função de texto explicativo notifyFn do texto explicativo para notificar o texto explicativo quando novos filtros que especificam o texto explicativo para a ação do filtro são adicionados ao mecanismo de filtro. Nessa situação, a função de texto explicativo notifyFn de um texto explicativo pode não ser chamada para cada filtro no mecanismo de filtro que especifica o texto explicativo para a ação do filtro.

Se um driver de texto explicativo registrar um texto explicativo depois que o mecanismo de filtro for iniciado e o texto explicativo precisar receber informações sobre cada filtro no mecanismo de filtro que especifica o texto explicativo para a ação do filtro, o driver de texto explicativo deverá chamar as funções de gerenciamento apropriadas para enumerar todos os filtros no mecanismo de filtro. O driver de texto explicativo deve classificar a lista resultante de todos os filtros para localizar os filtros que especificam o texto explicativo para a ação do filtro. Consulte Chamando outras funções da plataforma de filtragem do Windows para obter mais informações sobre como chamar essas funções.

Exclusão de filtro

Quando um filtro que especifica um texto explicativo para a ação do filtro é excluído do mecanismo de filtro, o mecanismo de filtro chama a função de texto explicativo notifyFn do texto explicativo e passa FWPS_CALLOUT_NOTIFY_DELETE_FILTER no parâmetro notifyType e NULL no parâmetro filterKey . O mecanismo de filtro chama a função de texto explicativo notifyFn do texto explicativo para cada filtro excluído no mecanismo de filtro que especifica o texto explicativo para a ação do filtro. Isso inclui todos os filtros que foram adicionados ao mecanismo de filtro antes que o driver de texto explicativo registrasse o texto explicativo com o mecanismo de filtro. Portanto, um texto explicativo pode receber notificações de exclusão de filtro para filtros para os quais não recebeu notificações de adição de filtro.

Se a função de texto explicativo notifyFn do texto explicativo não reconhecer o tipo de notificação passada no parâmetro notifyType , ela deverá ignorar a notificação e retornar STATUS_SUCCESS.

Um driver de texto explicativo pode especificar um contexto a ser associado a um filtro quando o filtro é adicionado ao mecanismo de filtro. Esse contexto é opaco para o mecanismo de filtro. A função de texto explicativo classifyFn do texto explicativo pode usar esse contexto para salvar informações de estado na próxima vez que for chamada pelo mecanismo de filtro. Quando o filtro é excluído do mecanismo de filtro, o driver de texto explicativo executa qualquer limpeza necessária do contexto.

Por exemplo:

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