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.

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

Weitere Informationen

CreateUnicastIpAddressEntry

DeleteUnicastIpAddressEntry

GetUnicastIpAddressTable

Ip-Hilfsfunktionsreferenz

InitializeUnicastIpAddressEntry

MIB_UNICASTIPADDRESS_ROW

MIB_UNICASTIPADDRESS_TABLE

NotifyUnicastIpAddressChange

SetUnicastIpAddressEntry