Função FwpsCalloutRegister1 (fwpsk.h)

Artigo
03/08/2023

A função FwpsCalloutRegister1 registra um texto explicativo com o mecanismo de filtro.

ObservaçãoFwpsCalloutRegister1 é a versão específica de FwpsCalloutRegister usada no Windows 7 e posterior. Consulte Nomes de Version-Independent WFP e Direcionamento de versões específicas do Windows para obter mais informações. Para Windows 8, FwpsCalloutRegister2 está disponível. Para o Windows Vista, FwpsCalloutRegister0 está disponível.

Sintaxe

NTSTATUS FwpsCalloutRegister1(
  [in, out]       void                *deviceObject,
  [in]            const FWPS_CALLOUT1 *callout,
  [out, optional] UINT32              *calloutId
);

Parâmetros

[in, out] deviceObject

Um ponteiro para um objeto de dispositivo que foi criado anteriormente pelo driver de texto explicativo. Para obter mais informações sobre como um driver de texto explicativo cria um objeto de dispositivo, consulte Criando um objeto de dispositivo.

[in] callout

Um ponteiro para uma estrutura de FWPS_CALLOUT1 constante que contém os dados necessários para registrar o texto explicativo com o mecanismo de filtro.

[out, optional] calloutId

Um ponteiro para uma variável do tipo UINT32 que recebe um identificador de tempo de execução que identifica o texto explicativo no mecanismo de filtro. O driver de texto explicativo passa esse identificador para a função FwpsCalloutUnregisterById0 ao cancelar o registro do texto explicativo do mecanismo de filtro. Se um driver de texto explicativo estiver filtrando um fluxo de dados, ele também passará esse identificador para as funções FwpsFlowAssociateContext0 e FwpsFlowRemoveContext0 . Se um driver de texto explicativo injetar dados em fluxos de dados, ele também passará esse identificador para a função FwpsStreamInjectAsync0 . O mecanismo de filtro também passa esse identificador para a função de texto explicativo flowDeleteFn do driver de texto explicativo. Esse parâmetro é opcional e pode ser NULL.

Retornar valor

A função FwpsCalloutRegister1 retorna um dos seguintes códigos NTSTATUS.

Código de retorno	Descrição
STATUS_SUCCESS	O texto explicativo foi registrado com êxito com o mecanismo de filtro.
STATUS_FWP_ALREADY_EXISTS	Não foi possível registrar o texto explicativo com o mecanismo de filtro. Um texto explicativo já está registrado no mecanismo de filtro com um identificador idêntico ao GUID especificado no membro calloutKey da estrutura FWPS_CALLOUT1 apontada pelo parâmetro callout .
Outros códigos de status	Ocorreu um erro.

Comentários

Um driver de texto explicativo chama a função FwpsCalloutRegister1 para registrar um texto explicativo com o mecanismo de filtro. Um driver de texto explicativo pode registrar um texto explicativo com o mecanismo de filtro a qualquer momento, mesmo que o mecanismo de filtro não esteja em execução no momento.

Um texto explicativo e filtros que especificam o texto explicativo para a ação do filtro podem ser adicionados ao mecanismo de filtro antes que um driver de texto explicativo registre o texto explicativo com o mecanismo de filtro. Nessa situação, os filtros com um tipo de ação de FWP_ACTION_CALLOUT_TERMINATING ou FWP_ACTION_CALLOUT_UNKNOWN são tratados como FWP_ACTION_BLOCK e os filtros com um tipo de ação de FWP_ACTION_CALLOUT_INSPECTION são ignorados até que o texto explicativo seja registrado no mecanismo de filtro.

Um driver de texto explicativo cancela o registro de um texto explicativo do mecanismo de filtro chamando o Função FwpsCalloutUnregisterById0 ou a Função FwpsCalloutUnregisterByKey0 . Um driver de texto explicativo não pode ser descarregado até que todos os textos explicativos registrados anteriormente com o mecanismo de filtro tenham sido cancelados com êxito.

Requisitos

Requisito	Valor
Cliente mínimo com suporte	Disponível a partir do Windows 7.
Plataforma de Destino	Universal
Cabeçalho	fwpsk.h (inclua Fwpsk.h)
Biblioteca	Fwpkclnt.lib
IRQL	PASSIVE_LEVEL