Função NotifyRouteChange2 (netioapi.h)

Artigo
03/15/2023

A função NotifyRouteChange2 registra para ser notificada quanto a alterações nas entradas de rota IP em um computador local.

Sintaxe

IPHLPAPI_DLL_LINKAGE _NETIOAPI_SUCCESS_ NETIOAPI_API NotifyRouteChange2(
  [in]      ADDRESS_FAMILY             AddressFamily,
  [in]      PIPFORWARD_CHANGE_CALLBACK Callback,
  [in]      PVOID                      CallerContext,
  [in]      BOOLEAN                    InitialNotification,
  [in, out] HANDLE                     *NotificationHandle
);

Parâmetros

[in] AddressFamily

A família de endereços na qual se registrar para notificações de alteração.

Os valores possíveis para a família de endereços são listados no arquivo de cabeçalho Winsock2.h . Observe que os valores para a família de endereços AF_ e PF_ constantes da família de protocolos são idênticos (por exemplo, AF_INET e PF_INET), portanto, qualquer constante pode ser usada.

No SDK do Windows lançado para Windows Vista e posterior, a organização dos arquivos de cabeçalho foi alterada e os valores possíveis para esse membro são definidos no arquivo de cabeçalho Ws2def.h . Observe que o arquivo de cabeçalho Ws2def.h é incluído automaticamente no Winsock2.h e nunca deve ser usado diretamente.

Os valores com suporte no momento são AF_INET, AF_INET6 e AF_UNSPEC.

Valor	Significado
AF_INET	Registre-se apenas para notificações de alteração de rota IPv4.
AF_INET6	Registre-se apenas para notificações de alteração de rota IPv6.
AF_UNSPEC	Registre-se para notificações de alteração de rota IPv4 e IPv6.

[in] Callback

Um ponteiro para a função a ser chamada quando ocorre uma alteração. Essa função será invocada quando uma notificação de rota IP for recebida.

[in] CallerContext

Um contexto de usuário passado para a função de retorno de chamada especificada no parâmetro Callback quando uma notificação de rota IP é recebida.

[in] InitialNotification

Um valor que indica se o retorno de chamada deve ser invocado imediatamente após a conclusão do registro da notificação de alteração. Essa notificação inicial não indica que ocorreu uma alteração em uma entrada de rota IP. A finalidade desse parâmetro para fornecer a confirmação de que o retorno de chamada está registrado.

[in, out] NotificationHandle

Um ponteiro usado para retornar um identificador que pode ser usado posteriormente para cancelar o registro da notificação de alteração. Em caso de êxito, um identificador de notificação é retornado nesse parâmetro. Se ocorrer um erro, NULL será retornado.

Valor retornado

Se a função for bem-sucedida, o valor retornado será NO_ERROR.

Se a função falhar, o valor retornado será um dos códigos de erro a seguir.

Código de retorno	Descrição
ERROR_INVALID_HANDLE	Ocorreu um erro interno em que um identificador inválido foi encontrado.
ERROR_INVALID_PARAMETER	Um parâmetro inválido foi passado para a função. Esse erro será retornado se o parâmetro Family não tiver sido AF_INET, AF_INET6 ou AF_UNSPEC.
ERROR_NOT_ENOUGH_MEMORY	Não havia memória suficiente.
Outros	Use FormatMessage para obter a cadeia de caracteres de mensagem para o erro retornado.

Comentários

A função NotifyRouteChange2 é definida no Windows Vista e posterior.

O parâmetro Family deve ser definido como AF_INET, AF_INET6 ou AF_UNSPEC.

A invocação da função de retorno de chamada especificada no parâmetro Callback é serializada. A função de retorno de chamada deve ser definida como uma função do tipo VOID. Os parâmetros passados para a função de retorno de chamada incluem o seguinte:

Parâmetro	Descrição
IN PVOID CallerContext	O parâmetro CallerContext passado para a função NotifyRouteChange2 ao se registrar para notificações.
IN PMIB_IPFORWARD_ROW2 Row OPTIONAL	Um ponteiro para a entrada MIB_IPFORWARD_ROW2 para a entrada de rota IP que foi alterada. Esse parâmetro é um ponteiro NULL quando o valor MIB_NOTIFICATION_TYPE passado no parâmetro NotificationType para a função de retorno de chamada é definido como MibInitialNotification. Isso só poderá ocorrer se o parâmetro InitialNotification passado para NotifyRouteChange2 tiver sido definido como TRUE ao se registrar para notificações.
IN MIB_NOTIFICATION_TYPE NotificationType	O tipo de notificação. Esse membro pode ser um dos valores do tipo de enumeração MIB_NOTIFICATION_TYPE definido no arquivo de cabeçalho Netioapi.h .

A função de retorno de chamada especificada no parâmetro Callback deve ser implementada no mesmo processo que o aplicativo que chama a função NotifyRouteChange2 . Se a função de retorno de chamada estiver em uma DLL separada, a DLL deverá ser carregada antes de chamar a função NotifyRouteChange2 para se registrar para notificações de alteração.

Quando a função de retorno de chamada é recebida quando ocorre uma alteração e o parâmetro Row não é NULL, o ponteiro para a estrutura MIB_IPFORWARD_ROW2 passada no parâmetro Row contém dados incompletos. As informações retornadas na estrutura MIB_IPFORWARD_ROW2 são apenas informações suficientes que um aplicativo pode chamar a função GetIpForwardEntry2 para consultar informações completas sobre a rota IP que foi alterada. Quando a função de retorno de chamada é recebida, um aplicativo deve alocar uma estrutura MIB_IPFORWARD_ROW2 e inicializá-la com os membros DestinationPrefix, NextHop, InterfaceLuid e InterfaceIndex na estrutura MIB_IPFORWARD_ROW2 apontada pelo parâmetro Row recebido. Um ponteiro para essa estrutura de MIB_IPFORWARD_ROW2 recém-inicializada deve ser passado para a função GetIpForwardEntry2 para recuperar informações completas sobre a rota IP que foi alterada.

A memória apontada pelo parâmetro Row usada nas indicações de retorno de chamada é gerenciada pelo sistema operacional. Um aplicativo que recebe uma notificação nunca deve tentar liberar a memória apontada pelo parâmetro Row .

Depois que a função NotifyRouteChange2 for chamada para se registrar para notificações de alteração, essas notificações continuarão a ser enviadas até que o aplicativo desregistre as notificações de alteração ou o aplicativo seja encerrado. Se o aplicativo for encerrado, o sistema cancelará automaticamente qualquer registro para notificações de alteração. Ainda é recomendável que um aplicativo registre explicitamente as notificações de alteração antes de terminar.

Qualquer registro para notificações de alteração não persistirá se o sistema for desligado ou reinicializado.

Para cancelar o registro de notificações de alteração, chame a função CancelMibChangeNotify2 passando o parâmetro NotificationHandle retornado por NotifyRouteChange2.

Um aplicativo não pode fazer uma chamada para a função CancelMibChangeNotify2 do contexto do thread que está executando atualmente a função de retorno de chamada de notificação para o mesmo parâmetro NotificationHandle . Caso contrário, o thread que executa esse retorno de chamada resultará em deadlock. Portanto, a função CancelMibChangeNotify2 não deve ser chamada diretamente como parte da rotina de retorno de chamada de notificação. Em uma situação mais geral, um thread que executa a função CancelMibChangeNotify2 não pode possuir um recurso no qual o thread que executa uma operação de retorno de chamada de notificação aguardaria porque resultaria em um deadlock semelhante. A função CancelMibChangeNotify2 deve ser chamada de um thread diferente, no qual o thread que recebe o retorno de chamada de notificação não tem dependências.

Requisitos


Cliente mínimo com suporte	Windows Vista [somente aplicativos da área de trabalho]
Servidor mínimo com suporte	Windows Server 2008 [somente aplicativos da área de trabalho]
Plataforma de Destino	Windows
Cabeçalho	netioapi.h (inclua Iphlpapi.h)
Biblioteca	Iphlpapi.lib
DLL	Iphlpapi.dll