Função NotifyIpInterfaceChange (netioapi.h)
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.
[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 |
---|---|
|
Ocorreu um erro interno em que um identificador inválido foi encontrado. |
|
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. |
|
Não havia memória suficiente. |
|
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 |