Função NotifyStableUnicastIpAddressTable (netioapi.h)

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.

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

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.

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 .

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:

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

Confira também

CancelMibChangeNotify2

CreateUnicastIpAddressEntry

DeleteUnicastIpAddressEntry

FreeMibTable

GetTeredoPort

GetUnicastIpAddressEntry

GetUnicastIpAddressTable

Referência de função auxiliar de IP

InitializeUnicastIpAddressEntry

MIB_NOTIFICATION_TYPE

MIB_UNICASTIPADDRESS_ROW

MIB_UNICASTIPADDRESS_TABLE

NotifyTeredoPortChange

NotifyUnicastIpAddressChange

SetUnicastIpAddressEntry