Funzione AddIPAddress (iphlpapi.h)

Articolo
08/24/2023

La funzione AddIPAddress aggiunge l'indirizzo IPv4 specificato all'adattatore specificato.

Sintassi

IPHLPAPI_DLL_LINKAGE DWORD AddIPAddress(
  [in]  IPAddr Address,
  [in]  IPMask IpMask,
  [in]  DWORD  IfIndex,
  [out] PULONG NTEContext,
  [out] PULONG NTEInstance
);

Parametri

[in] Address

Indirizzo IPv4 da aggiungere all'adattatore, sotto forma di struttura IPAddr .

[in] IpMask

Subnet mask per l'indirizzo IPv4 specificato nel parametro Address . Il parametro IPMask usa lo stesso formato di una struttura IPAddr .

[in] IfIndex

Indice dell'adattatore in cui aggiungere l'indirizzo IPv4.

[out] NTEContext

Puntatore a una variabile ULONG . In caso di esito positivo, questo parametro punta al contesto Net Table Entry (NTE) per l'indirizzo IPv4 aggiunto. Il chiamante può in seguito usare questo contesto in una chiamata alla funzione DeleteIPAddress .

[out] NTEInstance

Puntatore a una variabile ULONG . In caso di esito positivo, questo parametro punta all'istanza NTE per l'indirizzo IPv4 aggiunto.

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
ERROR_DEV_NOT_EXIST	L'adattatore specificato dal parametro IfIndex non esiste.
ERROR_DUP_DOMAINNAME	L'indirizzo IPv4 da aggiungere specificato nel parametro Address esiste già.
ERROR_GEN_FAILURE	Errore generale. Questo errore viene restituito per alcuni valori specificati nel parametro Address , ad esempio un indirizzo IPv4 normalmente considerato come indirizzi broadcast.
ERROR_INVALID_HANDLE	L'utente che tenta di effettuare la chiamata di funzione non è un amministratore.
ERROR_INVALID_PARAMETER	Uno o più parametri non sono validi. Questo errore viene restituito se i parametri NTEContext o NTEInstance sono NULL. Questo errore viene restituito anche quando l'indirizzo IP specificato nel parametro Address non è coerente con l'indice di interfaccia specificato nel parametro IfIndex (ad esempio, un indirizzo di loopback in un'interfaccia non loopback).
ERROR_NOT_SUPPORTED	La chiamata di funzione non è supportata nella versione di Windows in cui è stata eseguita.
Altri	Usare FormatMessage per ottenere la stringa del messaggio per l'errore restituito.

Commenti

La funzione AddIPAddress viene usata per aggiungere una nuova voce di indirizzo IPv4 in un computer locale. L'indirizzo IPv4 aggiunto dalla funzione AddIPAddress non è persistente. L'indirizzo IPv4 esiste solo se l'oggetto adapter esiste. Il riavvio del computer elimina definitivamente l'indirizzo IPv4, così come la reimpostazione manuale della scheda di interfaccia di rete (NIC). Inoltre, alcuni eventi PnP possono distruggere l'indirizzo.

Per creare un indirizzo IPv4 permanente, è possibile usare il metodo EnableStatic della classe Win32_NetworkAdapterConfiguration nei controlli Strumentazione gestione Windows (WMI). I comandi netsh possono essere usati anche per creare un indirizzo IPv4 persistente.

Per altre informazioni, vedere la documentazione su Netsh.exe nella documentazione di Windows Sockets.

In Windows Server 2003, Windows XP e Windows 2000, se l'indirizzo IPv4 nel parametro Address esiste già nella rete, la funzione AddIPAddress restituisce NO_ERROR e l'indirizzo IPv4 aggiunto è 0.0.0.0.

In Windows Vista e versioni successive, se l'indirizzo IPv4 passato nel parametro Address esiste già nella rete, la funzione AddIPAddress restituisce NO_ERROR e l'indirizzo IPv4 duplicato viene aggiunto con il membro IP_DAD_STATE nella struttura IP_ADAPTER_UNICAST_ADDRESS impostata su IpDadStateDuplicate.

Un indirizzo IPv4 aggiunto tramite la funzione AddIPAddress può essere eliminato in un secondo momento chiamando la funzione DeleteIPAddress passando il parametro NTEContext restituito dalla funzione AddIPAddress .

Per informazioni sui tipi di dati IPAddr e IPMask , vedere Tipi di dati Windows. Per convertire un indirizzo IPv4 tra notazione decimale punteggiata e formato IPAddr , usare le funzioni inet_addr e inet_ntoa .

In Windows Vista e versioni successive è possibile usare la funzione CreateUnicastIpAddressEntry per aggiungere una nuova voce di indirizzo IPv4 o IPv6 unicast in un computer locale.

Esempio

Nell'esempio seguente viene recuperata la tabella degli indirizzi IP per determinare l'indice di interfaccia per la prima scheda, quindi viene aggiunto l'indirizzo IP specificato nella riga di comando alla prima scheda. L'indirizzo IP aggiunto viene quindi eliminato.

#pragma comment(lib, "iphlpapi.lib")
#pragma comment(lib, "ws2_32.lib")

#include <winsock2.h>
#include <ws2tcpip.h>
#include <iphlpapi.h>
#include <stdio.h>

#define MALLOC(x) HeapAlloc(GetProcessHeap(), 0, (x))
#define FREE(x) HeapFree(GetProcessHeap(), 0, (x))

/* Note: could also use malloc() and free() */

int __cdecl main(int argc, char **argv)
{

    /* Variables used by GetIpAddrTable */
    PMIB_IPADDRTABLE pIPAddrTable;
    DWORD dwSize = 0;
    DWORD dwRetVal = 0;
    IN_ADDR IPAddr;
    DWORD ifIndex;

    /* IPv4 address and subnet mask we will be adding */
    UINT iaIPAddress;
    UINT iaIPMask;

    /* Variables where handles to the added IP are returned */
    ULONG NTEContext = 0;
    ULONG NTEInstance = 0;

    /* Variables used to return error message */
    LPVOID lpMsgBuf;

    // Validate the parameters
    if (argc != 3) {
        printf("usage: %s IPAddress SubnetMask\n", argv[0]);
        exit(1);
    }

    iaIPAddress = inet_addr(argv[1]);
    if (iaIPAddress == INADDR_NONE) {
        printf("usage: %s IPAddress SubnetMask\n", argv[0]);
        exit(1);
    }

    iaIPMask = inet_addr(argv[2]);
    if (iaIPMask == INADDR_NONE) {
        printf("usage: %s IPAddress SubnetMask\n", argv[0]);
        exit(1);
    }

    // Before calling AddIPAddress we use GetIpAddrTable to get
    // an adapter to which we can add the IP.
    pIPAddrTable = (MIB_IPADDRTABLE *) MALLOC(sizeof (MIB_IPADDRTABLE));
    if (pIPAddrTable == NULL) {
        printf("Error allocating memory needed to call GetIpAddrTable\n");
        exit (1);
    }
    else {
        dwSize = 0;
        // Make an initial call to GetIpAddrTable to get the
        // necessary size into the dwSize variable
        if (GetIpAddrTable(pIPAddrTable, &dwSize, 0) ==
            ERROR_INSUFFICIENT_BUFFER) {
            FREE(pIPAddrTable);
            pIPAddrTable = (MIB_IPADDRTABLE *) MALLOC(dwSize);

        }
        if (pIPAddrTable == NULL) {
            printf("Memory allocation failed for GetIpAddrTable\n");
            exit(1);
        }
    }
    // Make a second call to GetIpAddrTable to get the
    // actual data we want
    if ((dwRetVal = GetIpAddrTable(pIPAddrTable, &dwSize, 0)) == NO_ERROR) {
        // Save the interface index to use for adding an IP address
        ifIndex = pIPAddrTable->table[0].dwIndex;
        printf("\n\tInterface Index:\t%ld\n", ifIndex);
        IPAddr.S_un.S_addr = (u_long) pIPAddrTable->table[0].dwAddr;
        printf("\tIP Address:       \t%s (%lu%)\n", inet_ntoa(IPAddr),
               pIPAddrTable->table[0].dwAddr);
        IPAddr.S_un.S_addr = (u_long) pIPAddrTable->table[0].dwMask;
        printf("\tSubnet Mask:      \t%s (%lu%)\n", inet_ntoa(IPAddr),
               pIPAddrTable->table[0].dwMask);
        IPAddr.S_un.S_addr = (u_long) pIPAddrTable->table[0].dwBCastAddr;
        printf("\tBroadCast Address:\t%s (%lu%)\n", inet_ntoa(IPAddr),
               pIPAddrTable->table[0].dwBCastAddr);
        printf("\tReassembly size:  \t%lu\n\n",
               pIPAddrTable->table[0].dwReasmSize);
    } else {
        printf("Call to GetIpAddrTable failed with error %d.\n", dwRetVal);
        if (pIPAddrTable)
            FREE(pIPAddrTable);
        exit(1);
    }

    if (pIPAddrTable) {
        FREE(pIPAddrTable);
        pIPAddrTable = NULL;
    }

    if ((dwRetVal = AddIPAddress(iaIPAddress,
                                 iaIPMask,
                                 ifIndex,
                                 &NTEContext, &NTEInstance)) == NO_ERROR) {
        printf("\tIPv4 address %s was successfully added.\n", argv[1]);
    } else {
        printf("AddIPAddress failed with error: %d\n", dwRetVal);

        if (FormatMessage(FORMAT_MESSAGE_ALLOCATE_BUFFER | FORMAT_MESSAGE_FROM_SYSTEM | FORMAT_MESSAGE_IGNORE_INSERTS, NULL, dwRetVal, MAKELANGID(LANG_NEUTRAL, SUBLANG_DEFAULT),       // Default language
                          (LPTSTR) & lpMsgBuf, 0, NULL)) {
            printf("\tError: %s", lpMsgBuf);
            LocalFree(lpMsgBuf);
            exit(1);
        }
    }

// Delete the IP we just added using the NTEContext
// variable where the handle was returned       
    if ((dwRetVal = DeleteIPAddress(NTEContext)) == NO_ERROR) {
        printf("\tIPv4 address %s was successfully deleted.\n", argv[1]);
    } else {
        printf("\tDeleteIPAddress failed with error: %d\n", dwRetVal);
        exit(1);
    }

    exit(0);
}

Requisiti


Client minimo supportato	Windows 2000 Professional [solo app desktop]
Server minimo supportato	Windows 2000 Server [solo app desktop]
Piattaforma di destinazione	Windows
Intestazione	iphlpapi.h
Libreria	Iphlpapi.lib
DLL	Iphlpapi.dll