Função NotifyAddrChange (iphlpapi.h)

Artigo
08/24/2023

A função NotifyAddrChange faz com que uma notificação seja enviada ao chamador sempre que ocorrer uma alteração na tabela que mapeia endereços IPv4 para interfaces.

Sintaxe

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

Parâmetros

[out] Handle

Um ponteiro para uma variável HANDLE que recebe um identificador de arquivo para uso em uma chamada subsequente para a função GetOverlappedResult .

Aviso Não feche esse identificador e não o associe a uma porta de conclusão.

[in] overlapped

Um ponteiro para uma estrutura OVERLAPPED que notifica o chamador de qualquer alteração na tabela que mapeia endereços IP para interfaces.

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 NotifyAddrChange 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 NotifyAddrChange será síncrona e será bloqueada até que ocorra uma alteração de endereço IP. Nesse caso, se ocorrer uma alteração, a função NotifyAddrChange será concluída para indicar que ocorreu uma alteração.

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

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

A função CancelIPChangeNotify cancela a notificação do endereço IPv4 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 de uma alteração, o aplicativo poderá chamar a função GetIpAddrTable ou GetAdaptersAddresses para recuperar a tabela de endereços IPv4 para determinar o que mudou. Se o aplicativo for notificado e exigir notificação para a próxima alteração, a função NotifyAddrChange deverá ser chamada novamente.

Se a função NotifyAddrChange for chamada de forma assíncrona, uma notificação será enviada na próxima alteração de endereço 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 NotifyIpInterfaceChange pode ser usada para registrar para ser notificada quanto a alterações nas interfaces IPv4 e IPv6 no computador local.

Exemplos

O exemplo a seguir aguarda que uma alteração ocorra na tabela que mapeia endereços IP para interfaces.

#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 = NotifyAddrChange(&hand, &overlap);

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

  if ( WaitForSingleObject(overlap.hEvent, INFINITE) == WAIT_OBJECT_0 )
    printf("IP Address 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