Função NotifyRouteChange (iphlpapi.h)
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 |
|---|---|
|
O contexto está sendo desregistrado, portanto, a chamada foi cancelada imediatamente. |
|
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á. |
|
Não havia memória suficiente disponível para concluir a operação. |
|
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 |