Fonction IpReleaseAddress (iphlpapi.h)

Article
02/28/2024

La fonction IpReleaseAddress libère une adresse IPv4 précédemment obtenue via le protocole DHCP (Dynamic Host Configuration Protocol).

Syntaxe

IPHLPAPI_DLL_LINKAGE DWORD IpReleaseAddress(
  [in] PIP_ADAPTER_INDEX_MAP AdapterInfo
);

Paramètres

[in] AdapterInfo

Pointeur vers une structure de IP_ADAPTER_INDEX_MAP qui spécifie l’adaptateur associé à l’adresse IPv4 à libérer.

Valeur retournée

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

Si la fonction échoue, utilisez FormatMessage pour obtenir la chaîne de message correspondant à l’erreur retournée.

Code de retour	Description
ERROR_INVALID_PARAMETER	L’un des paramètres n’est pas valide. Cette erreur est retournée si le paramètre AdapterInfo a la valeur NULL ou si le membre Name de la structure PIP_ADAPTER_INDEX_MAP pointée par le paramètre AdapterInfo n’est pas valide.
ERROR_PROC_NOT_FOUND	Une exception s’est produite lors de la demande à DHCP pour la publication de l’adresse IPv4.
Autres	Utilisez FormatMessage pour obtenir la chaîne de message pour l’erreur retournée.

Remarques

La fonction IpReleaseAddress est spécifique à IPv4 et publie uniquement une adresse IPv4 précédemment obtenue via le protocole DHCP (Dynamic Host Configuration Protocol). Le membre Name de la structure IP_ADAPTER_INDEX_MAP pointée vers le paramètre AdapterInfo est le seul membre utilisé pour déterminer l’adresse DHCP à libérer.

Un tableau de structures IP_ADAPTER_INDEX_MAP est retourné dans la structure IP_INTERFACE_INFO par la fonction GetInterfaceInfo . La structure IP_INTERFACE_INFO retournée par GetInterfaceInfo contient au moins une structure IP_ADAPTER_INDEX_MAP même si le membre NumAdapters de la structure IP_INTERFACE_INFO indique qu’aucune carte réseau avec IPv4 n’est activée. Lorsque le membre NumAdapters de la structure IP_INTERFACE_INFO retournée par GetInterfaceInfo est égal à zéro, la valeur des membres de la structure IP_ADAPTER_INDEX_MAP unique retournée dans la structure IP_INTERFACE_INFO n’est pas définie.

Si le membre Name de la structure IP_ADAPTER_INDEX_MAP pointée par le paramètre AdapterInfo a la valeur NULL, la fonction IpReleaseAddress retourne ERROR_INVALID_PARAMETER.

Aucune fonction n’est disponible pour libérer ou renouveler une adresse IPv6. Pour ce faire, exécutez la commande Ipconfig :

ipconfig /release6

ipconfig /renew6

Exemples

L’exemple suivant récupère la liste des cartes réseau avec IPv4 activé sur le système local, puis libère et renouvelle l’adresse IPv4 pour la première carte de la liste.

#ifndef WIN32_LEAN_AND_MEAN
#define WIN32_LEAN_AND_MEAN
#endif

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

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

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

// Before calling IpReleaseAddress and IpRenewAddress we use
// GetInterfaceInfo to retrieve a handle to the adapter

void __cdecl main()
{
    ULONG ulOutBufLen = 0;
    DWORD dwRetVal = 0;
    PIP_INTERFACE_INFO pInfo;

    pInfo = (IP_INTERFACE_INFO *) MALLOC(sizeof(IP_INTERFACE_INFO));

    // Make an initial call to GetInterfaceInfo to get
    // the necessary size into the ulOutBufLen variable
    if (GetInterfaceInfo(pInfo, &ulOutBufLen) == ERROR_INSUFFICIENT_BUFFER) {
        FREE(pInfo);
        pInfo = (IP_INTERFACE_INFO *) MALLOC (ulOutBufLen);
    }

    // Make a second call to GetInterfaceInfo to get the
    // actual data we want
    if ((dwRetVal = GetInterfaceInfo(pInfo, &ulOutBufLen)) == NO_ERROR ) {
        printf("\tAdapter Name: %ws\n", pInfo->Adapter[0].Name);
        printf("\tAdapter Index: %ld\n", pInfo->Adapter[0].Index);
        printf("\tNum Adapters: %ld\n", pInfo->NumAdapters);
    }
    else if (dwRetVal == ERROR_NO_DATA) {
        printf("There are no network adapters with IPv4 enabled on the local system\n");
        return;
    }
    else {
        LPVOID lpMsgBuf;
        printf("GetInterfaceInfo failed.\n");
            
        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 );
        return;
    }

// Call IpReleaseAddress and IpRenewAddress to release and renew
// the IP address on the first network adapter returned 
// by the call to GetInterfaceInfo.
    if ((dwRetVal = IpReleaseAddress(&pInfo->Adapter[0])) == NO_ERROR) {
        printf("IP release succeeded.\n");
    }
    else {
        printf("IP release failed: %ld\n", dwRetVal);
    }

    if ((dwRetVal = IpRenewAddress(&pInfo->Adapter[0])) == NO_ERROR) {
        printf("IP renew succeeded.\n");
    }
    else {
        printf("IP renew failed: %ld\n", dwRetVal);
    }

    // Free memory for IP_INTERFACE_INFO 
    if (pInfo != NULL) {
        FREE(pInfo);
    }
    return;
}

Configuration requise

Condition requise	Valeur
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