AddIPAddress, fonction (iphlpapi.h)

Article
08/24/2023

La fonction AddIPAddress ajoute l’adresse IPv4 spécifiée à l’adaptateur spécifié.

Syntaxe

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

Paramètres

[in] Address

Adresse IPv4 à ajouter à l’adaptateur, sous la forme d’une structure IPAddr .

[in] IpMask

Masque de sous-réseau pour l’adresse IPv4 spécifiée dans le paramètre Address . Le paramètre IPMask utilise le même format qu’une structure IPAddr .

[in] IfIndex

Index de l’adaptateur sur lequel ajouter l’adresse IPv4.

[out] NTEContext

Pointeur vers une variable ULONG . En cas de retour réussi, ce paramètre pointe vers le contexte NTE (Net Table Entry) pour l’adresse IPv4 qui a été ajoutée. L’appelant peut ensuite utiliser ce contexte dans un appel à la fonction DeleteIPAddress .

[out] NTEInstance

Pointeur vers une variable ULONG . En cas de retour réussi, ce paramètre pointe vers le instance NTE pour l’adresse IPv4 qui a été ajoutée.

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_DEV_NOT_EXIST	L’adaptateur spécifié par le paramètre IfIndex n’existe pas.
ERROR_DUP_DOMAINNAME	L’adresse IPv4 à ajouter spécifiée dans le paramètre Address existe déjà.
ERROR_GEN_FAILURE	Défaillance générale. Cette erreur est retournée pour certaines valeurs spécifiées dans le paramètre Address , telles qu’une adresse IPv4 normalement considérée comme une adresse de diffusion.
ERROR_INVALID_HANDLE	L’utilisateur qui tente d’effectuer l’appel de fonction n’est pas un administrateur.
ERROR_INVALID_PARAMETER	Un ou plusieurs des paramètres n’est pas valide. Cette erreur est retournée si les paramètres NTEContext ou NTEInstance ont la valeur NULL. Cette erreur est également retournée lorsque l’adresse IP spécifiée dans le paramètre Address est incohérente avec l’index d’interface spécifié dans le paramètre IfIndex (par exemple, une adresse de bouclage sur une interface non-bouclage).
ERROR_NOT_SUPPORTED	L’appel de fonction n’est pas pris en charge sur la version de Windows sur laquelle il a été exécuté.
Autres	Utilisez FormatMessage pour obtenir la chaîne de message pour l’erreur retournée.

Notes

La fonction AddIPAddress est utilisée pour ajouter une nouvelle entrée d’adresse IPv4 sur un ordinateur local. L’adresse IPv4 ajoutée par la fonction AddIPAddress n’est pas persistante. L’adresse IPv4 existe uniquement tant que l’objet adaptateur existe. Le redémarrage de l’ordinateur détruit l’adresse IPv4, tout comme la réinitialisation manuelle de l’interface réseau carte (NIC). En outre, certains événements PnP peuvent détruire l’adresse.

Pour créer une adresse IPv4 qui persiste, la méthode EnableStatic de la classe Win32_NetworkAdapterConfiguration dans les contrôles WMI (Windows Management Instrumentation) peut être utilisée. Les commandes netsh peuvent également être utilisées pour créer une adresse IPv4 persistante.

Pour plus d’informations, consultez la documentation sur Netsh.exe dans la documentation des sockets Windows.

Sur Windows Server 2003, Windows XP et Windows 2000, si l’adresse IPv4 dans le paramètre Address existe déjà sur le réseau, la fonction AddIPAddress retourne NO_ERROR et l’adresse IPv4 ajoutée est 0.0.0.0.

Sur Windows Vista et versions ultérieures, si l’adresse IPv4 passée dans le paramètre Address existe déjà sur le réseau, la fonction AddIPAddress retourne NO_ERROR et l’adresse IPv4 en double est ajoutée avec le membre IP_DAD_STATE dans la structure IP_ADAPTER_UNICAST_ADDRESS définie sur IpDadStateDuplicate.

Une adresse IPv4 ajoutée à l’aide de la fonction AddIPAddress peut être supprimée ultérieurement en appelant la fonction DeleteIPAddress en passant le paramètre NTEContext retourné par la fonction AddIPAddress .

Pour plus d’informations sur les types de données IPAddr et IPMask , consultez Types de données Windows. Pour convertir une adresse IPv4 entre la notation décimale en pointillés et le format IPAddr , utilisez les fonctions inet_addr et inet_ntoa .

Sur Windows Vista et versions ultérieures, la fonction CreateUnicastIpAddressEntry peut être utilisée pour ajouter une nouvelle entrée d’adresse IPv4 ou IPv6 unicast sur un ordinateur local.

Exemples

L’exemple suivant récupère la table d’adresses IP pour déterminer l’index d’interface de la première carte, puis ajoute l’adresse IP spécifiée sur la ligne de commande à la première carte. L’adresse IP ajoutée est ensuite supprimée.

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

Spécifications


Client minimal pris en charge	Windows 2000 Professionnel [applications de bureau uniquement]
Serveur minimal pris en charge	Windows 2000 Server [applications de bureau uniquement]
Plateforme cible	Windows
En-tête	iphlpapi.h
Bibliothèque	Iphlpapi.lib
DLL	Iphlpapi.dll