Função NotifyStableUnicastIpAddressTable
A função NotifyStableUnicastIpAddressTable recupera a tabela de endereços IP unicast estável em um computador local.
Sintaxe
NETIOAPI_API NotifyStableUnicastIpAddressTable(
_In_ ADDRESS_FAMILY Family,
_Out_ PMIB_UNICASTIPADDRESS_TABLE *Table,
_In_ PSTABLE_UNICAST_IPADDRESS_TABLE_CALLBACK CallerCallback,
_In_ PVOID CallerContext,
_Inout_ HANDLE *NotificationHandle
);
Parâmetros
Família [in]
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 PF_ constantes da família de protocolos são idênticos (por exemplo, AF_INET e PF_INET), para que você possa usar qualquer constante.
No Windows Vista e versões posteriores dos sistemas operacionais Windows, os valores possíveis para o parâmetro Family são definidos no arquivo de cabeçalho Ws2def.h. Observe que o arquivo de cabeçalho Ws2def.h é incluído automaticamente em Netioapi.h e você nunca deve usar Ws2def.h diretamente.
Atualmente, há suporte para os seguintes valores para a família de endereços:
AF_INET
A família de endereços IPv4. Quando esse valor é especificado, a função recupera a tabela de endereços IP unicast estável que contém apenas entradas IPv4.AF_INET6
A família de endereços IPv6. Quando esse valor é especificado, a função recupera a tabela de endereços IP unicast estável que contém apenas entradas IPv6.AF_UNSPEC
A família de endereços não é especificada. Quando esse valor é especificado, a função recupera a tabela de endereços IP unicast estável que contém entradas IPv4 e IPv6.
Tabela [out]
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ável no computador local.Quando NotifyStableUnicastIpAddressTable retorna ERROR_IO_PENDING, o que indica que a solicitação de E/S está pendente, a tabela de endereços IP unicast estáveis é retornada para a função no parâmetro CallerCallback .
CallerCallback [in]
Um ponteiro para a função a ser chamada com a tabela de endereços IP unicast estável. Essa função será chamada se NotifyStableUnicastIpAddressTable retornar ERROR_IO_PENDING, o que indica que a solicitação de E/S está pendente.CallerContext [in]
Um contexto de usuário que é 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.NotificationHandle [in, out]
Um ponteiro usado para retornar um identificador que o driver pode usar 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, o que indica que a solicitação de E/S está pendente.
Retornar valor
NotifyStableUnicastIpAddressTable retornará STATUS_SUCCESS e a tabela IP unicast estável será retornada no parâmetro Table se a função for bem-sucedida imediatamente.
Se a solicitação de E/S estiver pendente, a função retornará ERROR_IO_PENDING e a função para a qual o parâmetro CallerCallback aponta 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, NotifyStableUnicastIpAddressTable retornará 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. |
| STATUS_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 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
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, esse estado corresponderia a um membro DadState do MIB_UNICASTIPADDRESS_ROW para o endereço IP definido como IpDadStatePreferred. Cada endereço de discagem sob demanda define sua própria métrica de estabilidade. Atualmente, o único endereço discado sob demanda que a função NotifyStableUnicastIpAddressTable considera é o endereço IP unicast que o cliente Teredo usa no computador local.
O driver deve definir o parâmetro Family como AF_INET, AF_INET6 ou AF_UNSPEC.
Quando NotifyStableUnicastIpAddressTable é bem-sucedido e retorna STATUS_SUCCESS, o parâmetro Table retorna a tabela de endereços IP unicast estáveis no computador local.
Quando NotifyStableUnicastIpAddressTable retorna ERROR_IO_PENDING, o que indica que a solicitação de E/S está pendente, a tabela de endereços IP unicast estáveis é retornada para a função no parâmetro CallerCallback .
Se o endereço IP unicast que o Teredo usa 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 será eventualmente 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á chamada.
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 que são passados para a função de retorno de chamada incluem o seguinte.
| Parâmetro | Descrição |
|---|---|
IN PVOID CallerContext |
O parâmetro CallerContext que é passado para a função NotifyStableUnicastIpAddressTable quando está registrando o driver para notificações. |
IN PMIB_UNICASTIPADDRESS_TABLE AddressTable |
Um ponteiro para uma estrutura MIB_UNICASTIPADDRESS_TABLE que contém a tabela de endereços IP unicast estável no computador local. |
A função NotifyStableUnicastIpAddressTable é usada principalmente por drivers que usam o cliente Teredo.
Para cancelar a notificação após a conclusão do retorno de chamada, chame a função CancelMibChangeNotify2 , passando o parâmetro NotificationHandle que NotifyStableUnicastIpAddressTable retorna.
Requisitos
Plataforma de destino |
Universal |
Versão |
Disponível no Windows Vista e versões posteriores dos sistemas operacionais Windows. |
Cabeçalho |
Netioapi.h (inclua Netioapi.h) |
Biblioteca |
Netio.lib |
IRQL |
< DISPATCH_LEVEL |