Função FwpsCalloutRegister1 (fwpsk.h)

Artigo
02/07/2025

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

ObservaçãoFwpsCalloutRegister1 é a versão específica do FwpsCalloutRegister usado no Windows 7 e posterior. Consulte nomes de Version-Independent WFP e versões específicas de destino do Windows para obter mais informações. Para o 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 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 em 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 explicativo estiver filtrando um fluxo de dados, ele também passará esse identificador para as funções FwpsFlowAssociateContext0 e FwpsFlowRemoveContext0. Se um driver explicativo injetar dados em fluxos de dados, ele também passará esse identificador para a função de 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.

Valor de retorno

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 no 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 de FWPS_CALLOUT1 apontado pelo parâmetro de texto explicativo.
Outros códigos de status	Ocorreu um erro.

Observações

Um driver 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, filtros com um tipo de ação de FWP_ACTION_CALLOUT_TERMINATING ou FWP_ACTION_CALLOUT_UNKNOWN são tratados como FWP_ACTION_BLOCKe filtros com um tipo de ação de FWP_ACTION_CALLOUT_INSPECTION são ignorados até que o texto explicativo seja registrado com o 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 função de FwpsCalloutUnregisterByKey0. Um driver de texto explicativo não pode ser descarregado até que todos os textos explicativos registrados anteriormente com o mecanismo de filtro não tenham sido registrados com êxito.

Requisitos

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