Função NotifyIpInterfaceChange (netioapi.h)

Artigo
03/15/2023

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

Sintaxe

IPHLPAPI_DLL_LINKAGE _NETIOAPI_SUCCESS_ NETIOAPI_API NotifyIpInterfaceChange(
  [in]      ADDRESS_FAMILY               Family,
  [in]      PIPINTERFACE_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 PF_ constantes da família de protocolos são idênticos (por exemplo, AF_INET e PF_INET), portanto, qualquer constante pode ser usada.

Na SDK do Windows lançada 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_UNSPEC 0	A família de endereços não é especificada. Quando esse parâmetro é especificado, essa função registra para notificações de alteração IPv4 e IPv6.
AF_INET 2	A família de endereços IPv4 (Protocolo de Internet versão 4). Quando esse parâmetro é especificado, essa função registra apenas notificações de alteração IPv4.
AF_INET6 23	A família de endereços IPv6 (Internet Protocol versão 6). Quando esse parâmetro é especificado, essa função registra apenas notificações de alteração 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 interface 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 uma interface de 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.

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 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 NotifyIpInterfaceChange é 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 NotifyIpInterfaceChange ao se registrar para notificações.
IN PMIB_IPINTERFACE_ROW Row OPTIONAL	Um ponteiro para a entrada MIB_IPINTERFACE_ROW para a interface 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 NotifyIpInterfaceChange 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 NotifyIpInterfaceChange . Se a função de retorno de chamada estiver em uma DLL separada, a DLL deverá ser carregada antes de chamar a função NotifyIpInterfaceChange 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_IPINTERFACE_ROW passada no parâmetro Row contém dados incompletos. As informações retornadas na estrutura MIB_IPINTERFACE_ROW são apenas informações suficientes que um aplicativo pode chamar a função GetIpInterfaceEntry para consultar informações completas sobre a interface ip que foi alterada. Quando a função de retorno de chamada é recebida, um aplicativo deve alocar uma estrutura MIB_IPINTERFACE_ROW e inicializá-la com os membros Family, InterfaceLuid e InterfaceIndex na estrutura MIB_IPINTERFACE_ROW apontada pelo parâmetro Row recebido. Um ponteiro para essa estrutura de MIB_IPINTERFACE_ROW recém-inicializada deve ser passado para a função GetIpInterfaceEntry para recuperar informações completas sobre a interface de 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 .

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

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.

Depois que a função NotifyIpInterfaceChange 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 persiste em um sistema desligado ou reinicializado.

Requisitos

Requisito	Valor
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