GetUnicastIpAddressEntry-Funktion (netioapi.h)
Die GetUnicastIpAddressEntry-Funktion ruft Informationen für einen vorhandenen Unicast-IP-Adresseintrag auf dem lokalen Computer ab.
Syntax
IPHLPAPI_DLL_LINKAGE _NETIOAPI_SUCCESS_ NETIOAPI_API GetUnicastIpAddressEntry(
[in, out] PMIB_UNICASTIPADDRESS_ROW Row
);
Parameter
[in, out] Row
Ein Zeiger auf einen MIB_UNICASTIPADDRESS_ROW-Struktureintrag für einen Unicast-IP-Adresseintrag. Bei erfolgreicher Rückgabe wird diese Struktur mit den Eigenschaften für eine vorhandene Unicast-IP-Adresse aktualisiert.
Rückgabewert
Wenn die Funktion erfolgreich ist, wird der Rückgabewert NO_ERROR.
Wenn die Funktion fehlschlägt, ist der Rückgabewert einer der folgenden Fehlercodes.
| Rückgabecode | Beschreibung |
|---|---|
|
Die angegebene Datei wurde nicht gefunden. Dieser Fehler wird zurückgegeben, wenn die netzwerkschnittstellen-LUID oder der Schnittstellenindex, der vom InterfaceLuid - oder InterfaceIndex-Member des MIB_UNICASTIPADDRESS_ROW angegeben wird, auf den der Row-Parameter verweist, kein Wert auf dem lokalen Computer ist. |
|
Ein Parameter ist falsch. Dieser Fehler wird zurückgegeben, wenn im Row-Parameter ein NULL-Zeiger übergeben wird, der Address-Member des MIB_UNICASTIPADDRESS_ROW, auf den der Row-Parameter verweist, nicht auf eine gültige Unicast-IPv4- oder IPv6-Adresse festgelegt ist, oder die Member InterfaceLuid und InterfaceIndex der MIB_UNICASTIPADDRESS_ROW, auf die der Row-Parameter verweist, nicht angegeben sind. |
|
Element wurde nicht gefunden. Dieser Fehler wird zurückgegeben, wenn die netzwerkschnittstelle, die vom InterfaceLuid - oder InterfaceIndex-Member der MIB_UNICASTIPADDRESS_ROW-Struktur angegeben wird, auf die der Row-Parameter verweist, nicht mit der IP-Adresse übereinstimmt, die im Address-Member in der MIB_UNICASTIPADDRESS_ROW-Struktur angegeben ist. |
|
Die Anforderung wird nicht unterstützt. Dieser Fehler wird zurückgegeben, wenn sich kein IPv4-Stapel auf dem lokalen Computer befindet und eine IPv4-Adresse im Address-Member der MIB_UNICASTIPADDRESS_ROW Struktur angegeben ist, auf die der Row-Parameter verweist. Dieser Fehler wird auch zurückgegeben, wenn sich kein IPv6-Stapel auf dem lokalen Computer befindet und eine IPv6-Adresse im Adresselement angegeben ist. |
|
Verwenden Sie FormatMessage , um die Meldungszeichenfolge für den zurückgegebenen Fehler abzurufen. |
Hinweise
Die GetUnicastIpAddressEntry-Funktion ist unter Windows Vista und höher definiert.
Die GetUnicastIpAddressEntry-Funktion wird normalerweise verwendet, um einen vorhandenen MIB_UNICASTIPADDRESS_ROW Struktureintrag abzurufen, der geändert werden soll. Eine Anwendung kann dann die Member im MIB_UNICASTIPADDRESS_ROW Eintrag ändern, den sie ändern möchte, und dann die SetUnicastIpAddressEntry-Funktion aufrufen.
Bei der Eingabe muss das Address-Element in der MIB_UNICASTIPADDRESS_ROW Struktur, auf die der Row-Parameter verweist, mit einer gültigen IPv4- oder IPv6-Unicastadresse initialisiert werden. Der si_family Member der SOCKADDR_INET-Struktur im Address-Member muss entweder als AF_INET oder AF_INET6 initialisiert werden, und der zugehörige Ipv4 - oder Ipv6-Member der SOCKADDR_INET-Struktur muss auf eine gültige Unicast-IP-Adresse festgelegt werden. Darüber hinaus muss mindestens eines der folgenden Member in der MIB_UNICASTIPADDRESS_ROW Struktur, die auf den Row-Parameter verweist, initialisiert werden: InterfaceLuid oder InterfaceIndex.
Die Felder werden in der oben aufgeführten Reihenfolge verwendet. Wenn also InterfaceLuid angegeben wird, wird dieser Member verwendet, um die Schnittstelle zu bestimmen. Wenn kein Wert für das InterfaceLuid-Element festgelegt ist (der Wert dieses Members ist auf 0 festgelegt), wird als Nächstes das InterfaceIndex-Element verwendet, um die Schnittstelle zu bestimmen.
Bei der Ausgabe, wenn der Aufruf erfolgreich ist, ruft GetUnicastIpAddressEntry die anderen Eigenschaften für die Unicast-IP-Adresse ab und füllt die MIB_UNICASTIPADDRESS_ROW Struktur aus, auf die der Row-Parameter verweist.
Die GetUnicastIpAddressTable-Funktion kann aufgerufen werden, um die Unicast-IP-Adresseinträge auf einem lokalen Computer aufzulisten.
Beispiele
Im folgenden Beispiel wird ein Unicast-IP-Adresseintrag abgerufen, der in der Befehlszeile angegeben ist, und einige Werte aus der abgerufenen MIB_UNICASTIPADDRESS_ROW-Struktur ausgegeben.
#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");
}
Anforderungen
| Anforderung | Wert |
|---|---|
| Unterstützte Mindestversion (Client) | Windows Vista [nur Desktop-Apps] |
| Unterstützte Mindestversion (Server) | Windows Server 2008 [nur Desktop-Apps] |
| Zielplattform | Windows |
| Kopfzeile | netioapi.h (include Iphlpapi.h) |
| Bibliothek | Iphlpapi.lib |
| DLL | Iphlpapi.dll |