Função GetUnicastIpAddressEntry (netioapi.h)
A função GetUnicastIpAddressEntry recupera informações para uma entrada de endereço IP unicast existente no computador local.
Sintaxe
IPHLPAPI_DLL_LINKAGE _NETIOAPI_SUCCESS_ NETIOAPI_API GetUnicastIpAddressEntry(
[in, out] PMIB_UNICASTIPADDRESS_ROW Row
);
Parâmetros
[in, out] Row
Um ponteiro para uma entrada de estrutura MIB_UNICASTIPADDRESS_ROW para uma entrada de endereço IP unicast. No retorno bem-sucedido, essa estrutura será atualizada com as propriedades de um endereço IP unicast existente.
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 |
|---|---|
|
O sistema não pode encontrar o arquivo especificado. Esse erro será retornado se o LUID da interface de rede ou o índice de interface especificado pelo membro InterfaceLuid ou InterfaceIndex do MIB_UNICASTIPADDRESS_ROW apontado pelo parâmetro Row não for um valor no computador local. |
|
Um parâmetro está incorreto. Esse erro será retornado se um ponteiro NULL for passado no parâmetro Row , o membro Address do MIB_UNICASTIPADDRESS_ROW apontado pelo parâmetro Row não for definido como um endereço IPv4 ou IPv6 unicast válido ou os membros InterfaceLuid e InterfaceIndex do MIB_UNICASTIPADDRESS_ROW apontados pelo parâmetro Row não forem especificados. |
|
Elemento não encontrado. Esse erro será retornado se o adaptador de rede especificado pelo membro InterfaceLuid ou InterfaceIndex da estrutura MIB_UNICASTIPADDRESS_ROW apontada pelo parâmetro Row não corresponder ao endereço IP especificado no membro Address na estrutura MIB_UNICASTIPADDRESS_ROW . |
|
A solicitação não terá suporte. Esse erro será retornado se nenhuma pilha IPv4 estiver no computador local e um endereço IPv4 for especificado no membro Address da estrutura MIB_UNICASTIPADDRESS_ROW apontada pelo parâmetro Row . Esse erro também será retornado se nenhuma pilha IPv6 estiver no computador local e um endereço IPv6 for especificado no membro Address . |
|
Use FormatMessage para obter a cadeia de caracteres de mensagem para o erro retornado. |
Comentários
A função GetUnicastIpAddressEntry é definida no Windows Vista e posterior.
A função GetUnicastIpAddressEntry normalmente é usada para recuperar uma entrada de estrutura MIB_UNICASTIPADDRESS_ROW existente a ser modificada. Em seguida, um aplicativo pode alterar os membros na entrada MIB_UNICASTIPADDRESS_ROW que deseja modificar e, em seguida, chamar a função SetUnicastIpAddressEntry .
Na entrada, o membro Address na estrutura MIB_UNICASTIPADDRESS_ROW apontada pelo parâmetro Row deve ser inicializado para um endereço IPv4 ou IPv6 unicast válido. O membro si_family da estrutura SOCKADDR_INET no membro Address deve ser inicializado para AF_INET ou AF_INET6 e o membro Ipv4 ou Ipv6 relacionado da estrutura SOCKADDR_INET deve ser definido como um endereço IP unicast válido. Além disso, pelo menos um dos seguintes membros na estrutura MIB_UNICASTIPADDRESS_ROW apontado para o parâmetro Row deve ser inicializado: InterfaceLuid ou InterfaceIndex.
Os campos são usados na ordem listada acima. Portanto, se InterfaceLuid for especificado, esse membro será usado para determinar a interface. Se nenhum valor for definido para o membro InterfaceLuid (o valor desse membro é definido como zero), o membro InterfaceIndex será usado em seguida para determinar a interface.
Na saída quando a chamada for bem-sucedida, GetUnicastIpAddressEntry recuperará as outras propriedades para o endereço IP unicast e preencherá a estrutura de MIB_UNICASTIPADDRESS_ROW apontada pelo parâmetro Row .
A função GetUnicastIpAddressTable pode ser chamada para enumerar as entradas de endereço IP unicast em um computador local.
Exemplos
O exemplo a seguir recupera uma entrada de endereço IP unicast especificada na linha de comando e imprime alguns valores da estrutura de MIB_UNICASTIPADDRESS_ROW recuperada.
#ifndef UNICODE
#define UNICODE
#endif
#ifndef WIN32_LEAN_AND_MEAN
#define WIN32_LEAN_AND_MEAN
#endif
#include <Windows.h.>
#include <winsock2.h>
#include <ws2tcpip.h>
#include <ws2ipdef.h>
#include <iphlpapi.h>
#include <stdio.h>
#include <stdlib.h>
// Need to link with Iphlpapi.lib and Ws2_32.lib
#pragma comment (lib, "iphlpapi.lib")
#pragma comment (lib, "Ws2_32.lib")
void PrintUnicastIpAddress(PMIB_UNICASTIPADDRESS_ROW pIpRow);
int __cdecl wmain(int argc, WCHAR **argv)
{
// Declare and initialize variables
ULONG Result = 0;
ULONG ifIndex;
// default to unspecified address family
ULONG addressFamily = AF_UNSPEC;
IN_ADDR Ipv4Addr;
IN6_ADDR Ipv6Addr;
MIB_UNICASTIPADDRESS_ROW ipRow = {0};
// Validate the parameters
if (argc < 4) {
wprintf(L"usage: %s <AddressFamily> <IPAddress> <InterfaceIndex>\n", argv[0]);
wprintf(L" Gets the UnicastIpAddressEntry for an AddressFamily,\n");
wprintf(L" Interface Index, and IP address\n");
wprintf(L" Examples\n");
wprintf(L" Get the IPv4 loopback at interface index=1\n");
wprintf(L" %s 4 127.0.0.1 1\n", argv[0]);
wprintf(L" Get the IPv6 loopback at interface index=1\n");
wprintf(L" %s 6 ::1 1\n", argv[0]);
exit(1);
}
if (_wtoi(argv[1]) == 4) {
addressFamily = AF_INET;
if (InetPtonW(addressFamily, argv[2], &Ipv4Addr) != 1) {
wprintf(L"Unable to parse IPv4 address string: %s\n", argv[3]);
exit(1);
}
} else if (_wtoi(argv[1]) == 6) {
addressFamily = AF_INET6;
if (InetPton(addressFamily, argv[2], &Ipv6Addr) != 1) {
wprintf(L"Unable to parse IPv6 address string: %s\n", argv[3]);
exit(1);
}
}
ifIndex = _wtoi(argv[3]);
ipRow.Address.si_family = (ADDRESS_FAMILY) addressFamily;
ipRow.InterfaceIndex = ifIndex;
if (addressFamily == AF_INET) {
ipRow.Address.si_family = AF_INET;
memcpy(&ipRow.Address.Ipv4.sin_addr, &Ipv4Addr, sizeof (IN_ADDR));
}
if (addressFamily == AF_INET6) {
ipRow.Address.si_family = AF_INET6;
memcpy(&ipRow.Address.Ipv6.sin6_addr, &Ipv6Addr, sizeof (IN6_ADDR));
}
Result = GetUnicastIpAddressEntry(&ipRow);
if (Result != NO_ERROR) {
wprintf(L"GetUnicastIpAddressEntry returned error: %lu\n", Result);
exit(1);
}
PrintUnicastIpAddress(&ipRow);
exit(0);
}
void PrintUnicastIpAddress(PMIB_UNICASTIPADDRESS_ROW pipRow)
{
WCHAR Ipv4String[16] = { 0 };
WCHAR Ipv6String[46] = { 0 };
// Print some variables from the rows in the table
wprintf(L"AddressFamily:\t\t\t ");
switch (pipRow->Address.si_family) {
case AF_INET:
wprintf(L"IPv4\n");
if (InetNtop(AF_INET, &pipRow->Address.Ipv4.sin_addr, Ipv4String, 16) !=
NULL)
wprintf(L"IPv4 Address:\t\t\t %ws\n", Ipv4String);
break;
case AF_INET6:
wprintf(L"IPv6\n");
if (InetNtop(AF_INET6, &pipRow->Address.Ipv6.sin6_addr, Ipv6String, 46)
!= NULL)
wprintf(L"IPv6 Address:\t\t\t %s\n", Ipv6String);
break;
default:
wprintf(L"Other: %d\n", pipRow->Address.si_family);
break;
}
wprintf(L"Interface LUID NetLuidIndex:\t %lu\n",
pipRow->InterfaceLuid.Info.NetLuidIndex);
wprintf(L"Interface LUID IfType:\t\t ");
switch (pipRow->InterfaceLuid.Info.IfType) {
case IF_TYPE_OTHER:
wprintf(L"Other\n");
break;
case IF_TYPE_ETHERNET_CSMACD:
wprintf(L"Ethernet\n");
break;
case IF_TYPE_ISO88025_TOKENRING:
wprintf(L"Token ring\n");
break;
case IF_TYPE_PPP:
wprintf(L"PPP\n");
break;
case IF_TYPE_SOFTWARE_LOOPBACK:
wprintf(L"Software loopback\n");
break;
case IF_TYPE_ATM:
wprintf(L"ATM\n");
break;
case IF_TYPE_IEEE80211:
wprintf(L"802.11 wireless\n");
break;
case IF_TYPE_TUNNEL:
wprintf(L"Tunnel encapsulation\n");
break;
case IF_TYPE_IEEE1394:
wprintf(L"IEEE 1394 (Firewire)\n");
break;
default:
wprintf(L"Unknown: %d\n", pipRow->InterfaceLuid.Info.IfType);
break;
}
wprintf(L"Interface Index:\t\t %lu\n", pipRow->InterfaceIndex);
wprintf(L"Prefix Origin:\t\t\t ");
switch (pipRow->PrefixOrigin) {
case IpPrefixOriginOther:
wprintf(L"IpPrefixOriginOther\n");
break;
case IpPrefixOriginManual:
wprintf(L"IpPrefixOriginManual\n");
break;
case IpPrefixOriginWellKnown:
wprintf(L"IpPrefixOriginWellKnown\n");
break;
case IpPrefixOriginDhcp:
wprintf(L"IpPrefixOriginDhcp\n");
break;
case IpPrefixOriginRouterAdvertisement:
wprintf(L"IpPrefixOriginRouterAdvertisement\n");
break;
case IpPrefixOriginUnchanged:
wprintf(L"IpPrefixOriginUnchanged\n");
break;
default:
wprintf(L"Unknown: %d\n", pipRow->PrefixOrigin);
break;
}
wprintf(L"Suffix Origin:\t\t\t ");
switch (pipRow->SuffixOrigin) {
case IpSuffixOriginOther:
wprintf(L"IpSuffixOriginOther\n");
break;
case IpSuffixOriginManual:
wprintf(L"IpSuffixOriginManual\n");
break;
case IpSuffixOriginWellKnown:
wprintf(L"IpSuffixOriginWellKnown\n");
break;
case IpSuffixOriginDhcp:
wprintf(L"IpSuffixOriginDhcp\n");
break;
case IpSuffixOriginLinkLayerAddress:
wprintf(L"IpSuffixOriginLinkLayerAddress\n");
break;
case IpSuffixOriginRandom:
wprintf(L"IpSuffixOriginRandom\n");
break;
case IpSuffixOriginUnchanged:
wprintf(L"IpSuffixOriginUnchanged\n");
break;
default:
wprintf(L"Unknown: %d\n", pipRow->SuffixOrigin);
break;
}
wprintf(L"Valid Lifetime:\t\t\t 0x%x (%u)\n",
pipRow->ValidLifetime, pipRow->ValidLifetime);
wprintf(L"Preferred Lifetime:\t\t 0x%x (%u)\n",
pipRow->PreferredLifetime, pipRow->PreferredLifetime);
wprintf(L"OnLink PrefixLength:\t\t %lu\n", pipRow->OnLinkPrefixLength);
wprintf(L"Skip As Source:\t\t\t ");
if (pipRow->SkipAsSource)
wprintf(L"Yes\n");
else
wprintf(L"No\n");
wprintf(L"Dad State:\t\t\t ");
switch (pipRow->DadState) {
case IpDadStateInvalid:
wprintf(L"IpDadStateInvalid\n");
break;
case IpDadStateTentative:
wprintf(L"IpDadStateTentative\n");
break;
case IpDadStateDuplicate:
wprintf(L"IpDadStateDuplicate\n");
break;
case IpDadStateDeprecated:
wprintf(L"IpDadStateDeprecated\n");
break;
case IpDadStatePreferred:
wprintf(L"IpDadStatePreferred\n");
break;
default:
wprintf(L"Unknown: %d\n", pipRow->DadState);
break;
}
wprintf(L"\n");
}
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 |
Confira também
Referência de função auxiliar de IP
Comentários
Em breve: Ao longo de 2024, eliminaremos os problemas do GitHub como o mecanismo de comentários para conteúdo e o substituiremos por um novo sistema de comentários. Para obter mais informações, consulte https://aka.ms/ContentUserFeedback.
Enviar e exibir comentários de