Função NotifyStableUnicastIpAddressTable (netioapi.h)

Artigo
08/25/2023

A função NotifyStableUnicastIpAddressTable recupera a tabela de endereços IP unicast estáveis em um computador local.

Sintaxe

IPHLPAPI_DLL_LINKAGE _NETIOAPI_SUCCESS_ NETIOAPI_API NotifyStableUnicastIpAddressTable(
  [in]      ADDRESS_FAMILY                           Family,
  [in, out] PMIB_UNICASTIPADDRESS_TABLE              *Table,
  [in]      PSTABLE_UNICAST_IPADDRESS_TABLE_CALLBACK CallerCallback,
  [in]      PVOID                                    CallerContext,
  [in, out] HANDLE                                   *NotificationHandle
);

Parâmetros

[in] Family

A família de endereços a ser recuperada.

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_UNSPEC 0	A família de endereços não é especificada. Quando esse parâmetro é especificado, a função recupera a tabela de endereços IP unicast estáveis que contém entradas IPv4 e IPv6.
AF_INET 2	A família de endereços IPv4 (Protocolo de Internet versão 4). Quando esse parâmetro é especificado, a função recupera a tabela de endereços IP unicast estáveis que contém apenas entradas IPv4.
AF_INET6 23	A família de endereços IPv6 (Internet Protocol versão 6). Quando esse parâmetro é especificado, a função recupera a tabela de endereços IP unicast estáveis que contém apenas entradas IPv6.

[in, out] Table

Um ponteiro para uma estrutura MIB_UNICASTIPADDRESS_TABLE . Quando NotifyStableUnicastIpAddressTable for bem-sucedido, esse parâmetro retornará a tabela de endereços IP unicast estáveis no computador local.

Quando NotifyStableUnicastIpAddressTable retorna ERROR_IO_PENDING indicando que a solicitação de E/S está pendente, a tabela de endereços IP unicast estáveis é retornada à função no parâmetro CallerCallback .

[in] CallerCallback

Um ponteiro para a função a ser chamada com a tabela de endereços IP unicast estáveis. Essa função será invocada se NotifyStableUnicastIpAddressTable retornar ERROR_IO_PENDING, indicando que a solicitação de E/S está pendente.

[in] CallerContext

Um contexto de usuário passado para a função de retorno de chamada especificada no parâmetro CallerCallback quando a tabela de endereços IP unicast estáveis está disponível.

[in, out] NotificationHandle

Um ponteiro usado para retornar um identificador que pode ser usado para cancelar a solicitação para recuperar a tabela de endereços IP unicast estáveis. Esse parâmetro será retornado se o valor retornado de NotifyStableUnicastIpAddressTable for ERROR_IO_PENDING indicando que a solicitação de E/S está pendente.

Retornar valor

Se a função for bem-sucedida imediatamente, o valor retornado será NO_ERROR e a tabela IP unicast estável será retornada no parâmetro Table .

Se a solicitação de E/S estiver pendente, a função retornará ERROR_IO_PENDING e a função apontada pelo parâmetro CallerCallback será chamada quando a solicitação de E/S for concluída com a tabela de endereços IP unicast estáveis.

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 Table for um ponteiro NULL , o parâmetro NotificationHandle for um ponteiro NULL ou o parâmetro Family não for 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 NotifyStableUnicastIpAddressTable é definida no Windows Vista e posterior.

Se a função NotifyStableUnicastIpAddressTable for bem-sucedida imediatamente, o valor retornado será NO_ERROR e a tabela IP unicast estável será retornada no parâmetro Table . O aplicativo de chamada deve liberar a memória apontada pelo parâmetro Table usando a função FreeMibTable quando as informações de MIB_UNICASTIPADDRESS_TABLE não forem mais necessárias.

Todos os endereços IP unicast, exceto endereços discados sob demanda, serão considerados estáveis somente se estiverem no estado preferencial. Para uma entrada de endereço IP unicast normal, isso corresponderia a um membro DadState do MIB_UNICASTIPADDRESS_ROW para o endereço IP definido como IpDadStatePreferred. Cada endereço discado sob demanda define sua própria métrica de estabilidade. Atualmente, o único endereço discado sob demanda considerado por essa função é o endereço IP unicast usado pelo cliente Teredo no computador local.

O parâmetro Family deve ser definido como AF_INET, AF_INET6 ou AF_UNSPEC.

Quando NotifyStableUnicastIpAddressTable for bem-sucedido e retornar NO_ERROR, o parâmetro Table retornará a tabela de endereços IP unicast estáveis no computador local.

A função NotifyStableUnicastIpAddressTable é usada principalmente por aplicativos que usam o cliente Teredo.

Se o endereço IP unicast usado pelo Teredo estiver disponível no computador local, mas não no estado estável (qualificado), NotifyStableUnicastIpAddressTable retornará ERROR_IO_PENDING e a tabela de endereços IP unicast estáveis eventualmente será retornada chamando a função no parâmetro CallerCallback . Se o endereço Teredo não estiver disponível ou estiver no estado estável e os outros endereços IP unicast estiverem em um estado estável, a função no parâmetro CallerCallback nunca será invocada.

A função de retorno de chamada especificada no parâmetro CallerCallback 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 NotifyStableUnicastIpAddressTable ao se registrar para notificações.
IN PMIB_UNICASTIPADDRESS_TABLE AddressTable	Um ponteiro para um MIB_UNICASTIPADDRESS_TABLE que contém a tabela de endereços IP unicast estáveis no computador local.

A função de retorno de chamada especificada no parâmetro CallerCallback deve ser implementada no mesmo processo que o aplicativo que chama a função NotifyStableUnicastIpAddressTable . Se a função de retorno de chamada estiver em uma DLL separada, a DLL deverá ser carregada antes de chamar a função NotifyStableUnicastIpAddressTable para se registrar para notificações de alteração.

A memória apontada pelo parâmetro AddressTable usado em uma indicação de retorno de chamada é alocada pelo sistema operacional. Um aplicativo que recebe uma notificação deve liberar a memória apontada pelo parâmetro AddressTable usando a função FreeMibTable quando as informações de MIB_UNICASTIPADDRESS_TABLE não forem mais necessárias.

Depois que a função NotifyStableUnicastIpAddressTable for chamada para registrar-se para notificações de alteração, essas notificações continuarão a ser enviadas até que os desregistros do aplicativo 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 as notificações de alteração antes de terminar.

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

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