Função NotifyRouteChange (iphlpapi.h)

Artigo
08/24/2023

A função NotifyRouteChange faz com que uma notificação seja enviada ao chamador sempre que ocorrer uma alteração na tabela de roteamento IPv4.

Sintaxe

IPHLPAPI_DLL_LINKAGE DWORD NotifyRouteChange(
  [out] PHANDLE      Handle,
  [in]  LPOVERLAPPED overlapped
);

Parâmetros

[out] Handle

Um ponteiro para uma variável HANDLE que recebe um identificador a ser usado na notificação assíncrona.

[in] overlapped

Um ponteiro para uma estrutura OVERLAPPED que notifica o chamador de quaisquer alterações na tabela de roteamento.

Valor retornado

Se a função for bem-sucedida, o valor retornado será NO_ERROR se o chamador especificar NULL para os parâmetros Handle e sobrepostos . Se o chamador especificar parâmetros não NULL , o valor retornado para êxito será ERROR_IO_PENDING. Se a função falhar, use FormatMessage para obter a cadeia de caracteres de mensagem para o erro retornado.

Código de retorno	Descrição
ERROR_CANCELLED	O contexto está sendo desregistrado, portanto, a chamada foi cancelada imediatamente.
ERROR_INVALID_PARAMETER	Um parâmetro inválido foi passado. Esse erro será retornado se os parâmetros Handle e overlapped não forem NULL, mas a memória especificada pelos parâmetros de entrada não puder ser gravada pelo processo de chamada. Esse erro também será retornado se o cliente já tiver feito uma solicitação de notificação de alteração, portanto, essa solicitação duplicada falhará.
ERROR_NOT_ENOUGH_MEMORY	Não havia memória suficiente disponível para concluir a operação.
ERROR_NOT_SUPPORTED	Esse erro é retornado em versões do Windows em que essa função não tem suporte, como Windows 98/95 e Windows NT 4.0.

Comentários

O
A função NotifyRouteChange pode ser chamada de duas maneiras:

Método síncrono
Método assíncrono

Se o chamador especificar NULL para os parâmetros Handle e sobrepostos , a chamada para NotifyRouteChange será síncrona e será bloqueada até que ocorra uma alteração de tabela de roteamento IPv4. Nesse caso, se ocorrer uma alteração, a função NotifyRouteChange será concluída para indicar que ocorreu uma alteração.

Se a função NotifyRouteChange for chamada de forma síncrona, uma notificação será enviada na próxima alteração de roteamento IPv4 até que o aplicativo seja encerrado.

Se o chamador especificar uma variável de identificador e uma estrutura OVERLAPPED , o chamador poderá usar o identificador retornado com a estrutura OVERLAPPED para receber uma notificação assíncrona de alterações de tabela de roteamento IPv4. Consulte os tópicos a seguir para obter informações sobre como usar o identificador e a estrutura OVERLAPPED para receber notificações:

Se o aplicativo receber uma notificação e exigir notificação para a próxima alteração, a função NotifyRouteChange deverá ser chamada novamente.

A função CancelIPChangeNotify cancela a notificação de endereço IP e roteia as alterações solicitadas anteriormente com chamadas bem-sucedidas para as funções NotifyAddrChange ou NotifyRouteChange .

Depois que um aplicativo tiver sido notificado sobre uma alteração, o aplicativo poderá chamar a função GetIpForwardTable ou GetIpForwardTable2 para recuperar a tabela de roteamento IPv4 para determinar o que mudou. Se o aplicativo for notificado e exigir notificação para a próxima alteração, a função NotifyRouteChange deverá ser chamada novamente.

Se a função NotifyRouteChange for chamada de forma assíncrona, uma notificação será enviada na próxima alteração de rota IPv4 até que o aplicativo cancele a notificação chamando a função CancelIPChangeNotify ou o aplicativo seja encerrado. Se o aplicativo for encerrado, o sistema cancelará automaticamente o registro da notificação. Ainda é recomendável que um aplicativo cancele explicitamente qualquer notificação antes de terminar.

Qualquer registro de uma notificação não persiste em um sistema desligado ou reinicializado.

No Windows Vista e posteriores, a função NotifyRouteChange2 pode ser usada para se registrar para ser notificada quanto a alterações na tabela de roteamento IPv6 no computador local.

Exemplos

O exemplo a seguir aguarda que uma alteração ocorra na tabela de roteamento de IP.

#include <winsock2.h>
#include <iphlpapi.h>
#include <stdio.h>
#include <windows.h>

#pragma comment(lib, "iphlpapi.lib")
#pragma comment(lib, "ws2_32.lib")

void main()
{
  OVERLAPPED overlap;
  DWORD ret;
    
  HANDLE hand = NULL;
  overlap.hEvent = WSACreateEvent();

  ret = NotifyRouteChange(&hand, &overlap);

  if (ret != NO_ERROR)
  {
    if (WSAGetLastError() != WSA_IO_PENDING)
    {
      printf("NotifyRouteChange error...%d\n", WSAGetLastError());            
      return;
    }
  }

  if ( WaitForSingleObject(overlap.hEvent, INFINITE) == WAIT_OBJECT_0 )
    printf("Routing table changed..\n");
}

Requisitos


Cliente mínimo com suporte	Windows 2000 Professional [somente aplicativos da área de trabalho]
Servidor mínimo com suporte	Windows 2000 Server [somente aplicativos da área de trabalho]
Plataforma de Destino	Windows
Cabeçalho	iphlpapi.h
Biblioteca	Iphlpapi.lib
DLL	Iphlpapi.dll