Funzione GetUnicastIpAddressEntry (netioapi.h)
La funzione GetUnicastIpAddressEntry recupera informazioni per una voce di indirizzo IP unicast esistente nel computer locale.
Sintassi
IPHLPAPI_DLL_LINKAGE _NETIOAPI_SUCCESS_ NETIOAPI_API GetUnicastIpAddressEntry(
[in, out] PMIB_UNICASTIPADDRESS_ROW Row
);
Parametri
[in, out] Row
Puntatore a una voce di struttura MIB_UNICASTIPADDRESS_ROW per una voce di indirizzo IP unicast. Al termine della restituzione, questa struttura verrà aggiornata con le proprietà per un indirizzo IP unicast esistente.
Valore restituito
Se la funzione ha esito positivo, il valore restituito viene NO_ERROR.
Se la funzione ha esito negativo, il valore restituito è uno dei codici di errore seguenti.
| Codice restituito | Descrizione |
|---|---|
|
Non è possibile trovare il file specificato. Questo errore viene restituito se l'interfaccia di rete LUID o l'indice di interfaccia specificato dal membro InterfaceLuid o InterfaceIndex del MIB_UNICASTIPADDRESS_ROW a cui punta il parametro Row non è un valore nel computer locale. |
|
Un parametro non è corretto. Questo errore viene restituito se un puntatore NULL viene passato nel parametro Row , il membro Address del MIB_UNICASTIPADDRESS_ROW a cui punta il parametro Row non è impostato su un indirizzo IPv4 o IPv6 valido oppure entrambi i membri InterfaceLuid e InterfaceIndex del MIB_UNICASTIPADDRESS_ROW a cui punta il parametro Row non sono specificati. |
|
Element not found. Questo errore viene restituito se l'interfaccia di rete specificata dal membro InterfaceLuid o InterfaceIndex della struttura MIB_UNICASTIPADDRESS_ROW a cui punta il parametro Row non corrisponde all'indirizzo IP specificato nel membro Address nella struttura MIB_UNICASTIPADDRESS_ROW . |
|
La richiesta non è supportata. Questo errore viene restituito se non si trova alcun stack IPv4 nel computer locale e viene specificato un indirizzo IPv4 nel membro Address della struttura MIB_UNICASTIPADDRESS_ROW a cui punta il parametro Row . Questo errore viene restituito anche se non si trova alcun stack IPv6 nel computer locale e nel membro Address viene specificato un indirizzo IPv6. |
|
Usare FormatMessage per ottenere la stringa del messaggio per l'errore restituito. |
Commenti
La funzione GetUnicastIpAddressEntry viene definita in Windows Vista e versioni successive.
La funzione GetUnicastIpAddressEntry viene in genere utilizzata per recuperare una voce di struttura MIB_UNICASTIPADDRESS_ROW esistente da modificare. Un'applicazione può quindi modificare i membri nella voce MIB_UNICASTIPADDRESS_ROW che desidera modificare e quindi chiamare la funzione SetUnicastIpAddressEntry .
In input, il membro Address nella struttura MIB_UNICASTIPADDRESS_ROW a cui punta il parametro Row deve essere inizializzato in un indirizzo IPv4 o IPv6 unicast valido. Il membro si_family della struttura SOCKADDR_INET nel membro Address deve essere inizializzato in AF_INET o AF_INET6 e il membro Ipv4 o Ipv6 correlato della struttura SOCKADDR_INET deve essere impostato su un indirizzo IP unicast valido. Inoltre, almeno uno dei membri seguenti nella struttura MIB_UNICASTIPADDRESS_ROW a cui punta il parametro Row deve essere inizializzato: InterfaceLuid o InterfaceIndex.
I campi vengono usati nell'ordine indicato in precedenza. Quindi, se si specifica InterfaceLuid , questo membro viene usato per determinare l'interfaccia. Se non viene impostato alcun valore per il membro InterfaceLuid (il valore di questo membro è impostato su zero), il membro InterfaceIndex viene usato successivamente per determinare l'interfaccia.
Quando la chiamata ha esito positivo, GetUnicastIpAddressEntry recupera le altre proprietà per l'indirizzo IP unicast e compila la struttura MIB_UNICASTIPADDRESS_ROW a cui punta il parametro Row .
È possibile chiamare la funzione GetUnicastIpAddressTable per enumerare le voci di indirizzo IP unicast in un computer locale.
Esempio
Nell'esempio seguente viene recuperata una voce di indirizzo IP unicast specificata nella riga di comando e vengono stampati alcuni valori dalla struttura MIB_UNICASTIPADDRESS_ROW recuperata.
#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");
}
Requisiti
| Requisito | Valore |
|---|---|
| Client minimo supportato | Windows Vista [solo app desktop] |
| Server minimo supportato | Windows Server 2008 [solo app desktop] |
| Piattaforma di destinazione | Windows |
| Intestazione | netioapi.h (include Iphlpapi.h) |
| Libreria | Iphlpapi.lib |
| DLL | Iphlpapi.dll |
Vedi anche
Informazioni di riferimento sulle funzioni helper IP