Função NotifyUnicastIpAddressChange

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

Sintaxe

NETIOAPI_API NotifyUnicastIpAddressChange(
  _In_    ADDRESS_FAMILY                     Family,
  _In_    PUNICAST_IPADDRESS_CHANGE_CALLBACK Callback,
  _In_    PVOID                              CallerContext,
  _In_    BOOLEAN                            InitialNotification,
  _Inout_ HANDLE                             *NotificationHandle
);

Parâmetros

Família [in]
A família de endereços para registrar o driver para notificações de alteração.

Os valores possíveis para a família de endereços estã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 PF_ protocolo são idênticos (por exemplo, AF_INET e PF_INET), portanto, você pode usar qualquer constante.

No Windows Vista e versões posteriores dos sistemas operacionais Windows, os valores possíveis para o parâmetro da família são definidos no arquivo de cabeçalho Ws2def.h. Observe que o arquivo de cabeçalho Ws2def.h é incluído automaticamente no Netioapi.h e você nunca deve usar Ws2def.h diretamente.

Os seguintes valores são atualmente suportados para a família de endereços:
- AF_INET
  A família de endereços IPv4. Quando esse valor é especificado, a função registra o driver somente para notificações de alteração de endereço IPv4 unicast.
- AF_INET6
  A família de endereços IPv6. Quando esse valor é especificado, a função registra o driver somente para notificações de alteração de endereço IPv6 unicast.
- AF_UNSPEC
  A família de endereços não é especificada. Quando esse valor é especificado, a função registra o driver para notificações de alteração de endereço IPv4 e IPv6 unicast.
Callback [in]
Um ponteiro para a função a ser chamada quando ocorre uma alteração. Esta função é chamada quando uma notificação de endereço IP unicast é recebida.
CallerContext [em]
Um contexto de usuário que é passado para a função de retorno de chamada especificada no parâmetro Callback quando uma notificação de interface é recebida.
InitialNotification [in]
Um valor que indica se o retorno de chamada deve ser chamado imediatamente após a conclusão do registro para notificação de alteração. Esta notificação inicial não indica que ocorreu uma alteração a um endereço IP unicast. Este parâmetro fornece a confirmação de que o retorno de chamada está registrado.
NotificationHandle [entrada, saída]
Um ponteiro que é usado para retornar uma alça que o driver pode usar posteriormente para cancelar o registro da notificação de alteração de driver. Quando for bem-sucedido, um identificador de notificação é retornado nesse parâmetro. Se ocorrer um erro, NULL será retornado.

Valor de retorno

NotifyUnicastIpAddressChange retorna STATUS_SUCCESS se a função for bem-sucedida.

Se a função falhar, NotifyUnicastIpAddressChange retornará um dos seguintes códigos de erro:

Código de retorno	Descrição
ERROR_INVALID_HANDLE	Ocorreu um erro interno onde foi encontrado um identificador inválido.
STATUS_INVALID_PARAMETER	Um parâmetro inválido foi passado para a função. Este erro será retornado se o parâmetro Family não tiver sido AF_INET, AF_INET6 ou AF_UNSPEC.
STATUS_NOT_ENOUGH_MEMORY	Não havia memória suficiente.
Outros	Use a função FormatMessage para obter a cadeia de caracteres de mensagem para o erro retornado.

Comentários

O driver deve definir o parâmetro Family 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 que são passados para a função de retorno de chamada incluem o seguinte.

Parâmetro	Descrição
EM PVOID CallerContext	O parâmetro CallerContext que é passado para a função NotifyUnicastIpAddressChange quando está registrando o driver para notificações de alteração.
EM PMIB_UNICASTIPADDRESS_ROW Linha OPCIONAL	Um ponteiro para a entrada MIB_UNICASTIPADDRESS_ROW para o endereço IP unicast que foi alterado. Este parâmetro é um ponteiro de NULL quando o valor MIB_NOTIFICATION_TYPE que é passado no parâmetro NotificationType para a função de retorno de chamada é definido como MibInitialNotification. Essa situação pode ocorrer somente se o parâmetro InitialNotification que é passado para NotifyUnicastIpAddressChange foi definido como TRUE ao registrar o driver para notificações de alteração.
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.

Para cancelar o registro do driver para notificações de alteração, chame a funçãoCancelMibChangeNotify2, passando o parâmetro NotificationHandle que NotifyUnicastIpAddress Change retorna.

Requerimentos

Plataforma de destino	Universal
Versão	Disponível no Windows Vista e versões posteriores dos sistemas operacionais Windows.
Cabeçalho	Netioapi.h (inclui Netioapi.h)
Biblioteca	Netio.lib
IRQL	< DISPATCH_LEVEL