Partager via

GetUnicastIpAddressEntry, fonction (netioapi.h)

  • Article

La fonction GetUnicastIpAddressEntry récupère les informations d’une entrée d’adresse IP unicast existante sur l’ordinateur local.

Syntaxe

IPHLPAPI_DLL_LINKAGE _NETIOAPI_SUCCESS_ NETIOAPI_API GetUnicastIpAddressEntry(
  [in, out] PMIB_UNICASTIPADDRESS_ROW Row
);

Paramètres

[in, out] Row

Pointeur vers une entrée de structure MIB_UNICASTIPADDRESS_ROW pour une entrée d’adresse IP unicast. En cas de retour réussi, cette structure est mise à jour avec les propriétés d’une adresse IP de unidiffusion existante.

Valeur retournée

Si la fonction réussit, la valeur de retour est NO_ERROR.

Si la fonction échoue, la valeur de retour est l’un des codes d’erreur suivants.

Code de retour Description
ERROR_FILE_NOT_FOUND
 Le système ne peut pas trouver le fichier spécifié. Cette erreur est retournée si l’interface réseau LUID ou l’index d’interface spécifié par le membre InterfaceLuid ou InterfaceIndex du MIB_UNICASTIPADDRESS_ROW pointé par le paramètre Row n’est pas une valeur sur l’ordinateur local.
ERROR_INVALID_PARAMETER
 Un paramètre est incorrect. Cette erreur est retournée si un pointeur NULL est transmis dans le paramètre Row , si le membre Address du MIB_UNICASTIPADDRESS_ROW pointé par le paramètre Row n’est pas défini sur une adresse IPv4 ou IPv6 de monodiffusion valide, ou si les membres InterfaceLuid et InterfaceIndex du MIB_UNICASTIPADDRESS_ROW pointés par le paramètre Row ne sont pas spécifiés.
ERROR_NOT_FOUND
 Element not found. Cette erreur est retournée si l’interface réseau spécifiée par le membre InterfaceLuid ou InterfaceIndex de la structure MIB_UNICASTIPADDRESS_ROW pointée par le paramètre Row ne correspond pas à l’adresse IP spécifiée dans le membre Address dans la structure MIB_UNICASTIPADDRESS_ROW .
ERROR_NOT_SUPPORTED
 La demande n'est pas prise en charge. Cette erreur est retournée si aucune pile IPv4 ne se trouve sur l’ordinateur local et qu’une adresse IPv4 est spécifiée dans le membre Address de la structure MIB_UNICASTIPADDRESS_ROW pointée vers le paramètre Row . Cette erreur est également retournée si aucune pile IPv6 ne se trouve sur l’ordinateur local et qu’une adresse IPv6 est spécifiée dans le membre Address .
Autres
 Utilisez FormatMessage pour obtenir la chaîne de message pour l’erreur retournée.

Remarques

La fonction GetUnicastIpAddressEntry est définie sur Windows Vista et versions ultérieures.

La fonction GetUnicastIpAddressEntry est normalement utilisée pour récupérer une entrée de structure MIB_UNICASTIPADDRESS_ROW existante à modifier. Une application peut ensuite modifier les membres de l’entrée MIB_UNICASTIPADDRESS_ROW qu’elle souhaite modifier, puis appeler la fonction SetUnicastIpAddressEntry .

Lors de l’entrée, le membre Address dans la structure MIB_UNICASTIPADDRESS_ROW pointée vers le paramètre Row doit être initialisé vers une adresse IPv4 ou IPv6 unicast valide. Le membre si_family de la structure SOCKADDR_INET dans le membre Address doit être initialisé sur AF_INET ou AF_INET6 et le membre Ipv4 ou Ipv6 associé de la structure SOCKADDR_INET doit être défini sur une adresse IP de unidiffusion valide. En outre, au moins l’un des membres suivants de la structure MIB_UNICASTIPADDRESS_ROW pointée vers le paramètre Row doit être initialisé : InterfaceLuid ou InterfaceIndex.

Les champs sont utilisés dans l’ordre indiqué ci-dessus. Par conséquent, si l’interfaceLuid est spécifiée, ce membre est utilisé pour déterminer l’interface. Si aucune valeur n’est définie pour le membre InterfaceLuid (la valeur de ce membre est définie sur zéro), le membre InterfaceIndex est ensuite utilisé pour déterminer l’interface.

Lors de la sortie lorsque l’appel réussit, GetUnicastIpAddressEntry récupère les autres propriétés de l’adresse IP unicast et remplit la structure MIB_UNICASTIPADDRESS_ROW pointée vers le paramètre Row .

La fonction GetUnicastIpAddressTable peut être appelée pour énumérer les entrées d’adresse IP unicast sur un ordinateur local.

Exemples

L’exemple suivant récupère une entrée d’adresse IP unicast spécifiée sur la ligne de commande et imprime certaines valeurs de la structure MIB_UNICASTIPADDRESS_ROW récupérée.


#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");
}

Configuration requise

Condition requise Valeur
Client minimal pris en charge Windows Vista [applications de bureau uniquement]
Serveur minimal pris en charge Windows Server 2008 [applications de bureau uniquement]
Plateforme cible Windows
En-tête netioapi.h (inclure Iphlpapi.h)
Bibliothèque Iphlpapi.lib
DLL Iphlpapi.dll

Voir aussi

CreateUnicastIpAddressEntry

DeleteUnicastIpAddressEntry

GetUnicastIpAddressTable

Informations de référence sur la fonction d’assistance IP

InitializeUnicastIpAddressEntry

MIB_UNICASTIPADDRESS_ROW

MIB_UNICASTIPADDRESS_TABLE

NotifyUnicastIpAddressChange

SetUnicastIpAddressEntry