Função NotifyUnicastIpAddressChange (netioapi.h)

Artigo
08/25/2023

A função NotifyUnicastIpAddressChange registra para ser notificada quanto a alterações em todas as interfaces IP unicast, endereços IPv4 unicast ou endereços IPv6 unicast em um computador local.

Sintaxe

IPHLPAPI_DLL_LINKAGE _NETIOAPI_SUCCESS_ NETIOAPI_API NotifyUnicastIpAddressChange(
  [in]      ADDRESS_FAMILY                     Family,
  [in]      PUNICAST_IPADDRESS_CHANGE_CALLBACK Callback,
  [in]      PVOID                              CallerContext,
  [in]      BOOLEAN                            InitialNotification,
  [in, out] HANDLE                             *NotificationHandle
);

Parâmetros

[in] Family

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 as constantes da família de protocolos PF_ são idênticos (por exemplo, AF_INET e PF_INET), para que qualquer constante possa ser usada.

Na SDK do Windows lançada para o Windows Vista e posteriores, 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 em Winsock2.h e nunca deve ser usado diretamente.

Atualmente, os valores com suporte são AF_INET, AF_INET6 e AF_UNSPEC.

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

[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 endereço IP unicast 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 interface é 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 um endereço IP unicast. 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 desregistrar a 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.

Retornar valor

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

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

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 NotifyUnicastIpAddressChange é 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 NotifyUnicastIpAddressChange ao se registrar para notificações.
IN PMIB_UNICASTIPADDRESS_ROW Row OPTIONAL	Um ponteiro para a entrada MIB_UNICASTIPADDRESS_ROW para o endereço IP unicast que foi alterado. Esse parâmetro é um ponteiro NULL quando o valor de 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 NotifyUnicastIpAddressChange 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 NotifyUnicastIpAddressChange . Se a função de retorno de chamada estiver em uma DLL separada, a DLL deverá ser carregada antes de chamar a função NotifyUnicastIpAddressChange 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_UNICASTIPADDRESS_ROW passada no parâmetro Row contém dados incompletos. As informações retornadas na estrutura MIB_UNICASTIPADDRESS_ROW são apenas informações suficientes que um aplicativo pode chamar a função GetUnicastIpAddressEntry para consultar informações completas sobre o endereço IP que foi alterado. Quando a função de retorno de chamada é recebida, um aplicativo deve alocar uma estrutura MIB_UNICASTIPADDRESS_ROW e inicializá-la com os membros Address, InterfaceLuid e InterfaceIndex na estrutura MIB_UNICASTIPADDRESS_ROW apontada pelo parâmetro Row recebido. Um ponteiro para essa estrutura de MIB_UNICASTIPADDRESS_ROW recém-inicializada deve ser passado para a função GetUnicastIpAddressEntry para recuperar informações completas sobre o endereço IP unicast que foi alterado.

A memória apontada pelo parâmetro Row usado 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 NotifyUnicastIpAddressChange for chamada para se registrar para notificações de alteração, essas notificações continuarão a ser enviadas até que o aplicativo desregistros para 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 desregistre explicitamente para notificações de alteração antes de ser encerrado.

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 NotifyUnicastIpAddressChange.

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 ter 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

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