IpReleaseAddress-Funktion (iphlpapi.h)

Artikel
03/01/2024

Die IpReleaseAddress-Funktion gibt eine IPv4-Adresse frei, die zuvor über das Dynamic Host Configuration Protocol (DHCP) abgerufen wurde.

Syntax

IPHLPAPI_DLL_LINKAGE DWORD IpReleaseAddress(
  [in] PIP_ADAPTER_INDEX_MAP AdapterInfo
);

Parameter

[in] AdapterInfo

Ein Zeiger auf eine IP_ADAPTER_INDEX_MAP-Struktur , die den Adapter angibt, der der zu veröffentlichenden IPv4-Adresse zugeordnet ist.

Rückgabewert

Wenn die Funktion erfolgreich ist, wird der Rückgabewert NO_ERROR.

Wenn die Funktion fehlschlägt, verwenden Sie FormatMessage , um die Nachrichtenzeichenfolge für den zurückgegebenen Fehler abzurufen.

Rückgabecode	Beschreibung
ERROR_INVALID_PARAMETER	Einer der Parameter ist ungültig. Dieser Fehler wird zurückgegeben, wenn der AdapterInfo-ParameterNULL ist oder wenn der Name-Member der PIP_ADAPTER_INDEX_MAP Struktur, auf die vom AdapterInfo-Parameter verwiesen wird, ungültig ist.
ERROR_PROC_NOT_FOUND	Während der Anforderung an DHCP für die Freigabe der IPv4-Adresse ist eine Ausnahme aufgetreten.
Andere	Verwenden Sie FormatMessage , um die Nachrichtenzeichenfolge für den zurückgegebenen Fehler abzurufen.

Hinweise

Die IpReleaseAddress-Funktion ist IPv4-spezifisch und gibt nur eine IPv4-Adresse frei, die zuvor über das Dynamic Host Configuration Protocol (DHCP) abgerufen wurde. Das Name-Element der IP_ADAPTER_INDEX_MAP Struktur, auf die vom AdapterInfo-Parameter verwiesen wird, ist das einzige Element, das verwendet wird, um die zu freigebende DHCP-Adresse zu bestimmen.

Ein Array von IP_ADAPTER_INDEX_MAP Strukturen wird in der IP_INTERFACE_INFO-Struktur von der GetInterfaceInfo-Funktion zurückgegeben. Die vonGetInterfaceInfo zurückgegebene IP_INTERFACE_INFO-Struktur enthält mindestens eine IP_ADAPTER_INDEX_MAP-Struktur , auch wenn das NumAdapters-Element der IP_INTERFACE_INFO-Struktur angibt, dass keine Netzwerkadapter mit IPv4 aktiviert sind. Wenn das NumAdapters-Element der vonGetInterfaceInfo zurückgegebenen IP_INTERFACE_INFO-Struktur 0 ist, ist der Wert der Elemente der einzelnen IP_ADAPTER_INDEX_MAP Struktur, die in der IP_INTERFACE_INFO-Struktur zurückgegeben werden, undefiniert.

Wenn das Name-Element der IP_ADAPTER_INDEX_MAP-Struktur , auf die vom AdapterInfo-Parameter verwiesen wird , NULL ist, gibt die IpReleaseAddress-FunktionERROR_INVALID_PARAMETER zurück.

Es sind keine Funktionen zum Freigeben oder Verlängern einer IPv6-Adresse verfügbar. Dies kann nur durch Ausführen des Befehls Ipconfig erfolgen:

ipconfig /release6

ipconfig /renew6

Beispiele

Im folgenden Beispiel wird die Liste der Netzwerkadapter abgerufen, für die IPv4 auf dem lokalen System aktiviert ist. Anschließend wird die IPv4-Adresse für den ersten Adapter in der Liste freigegeben und erneuert.

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

Anforderungen

Anforderung	Wert
Unterstützte Mindestversion (Client)	Windows 2000 Professional [nur Desktop-Apps]
Unterstützte Mindestversion (Server)	Windows 2000 Server [nur Desktop-Apps]
Zielplattform	Windows
Kopfzeile	iphlpapi.h
Bibliothek	Iphlpapi.lib
DLL	Iphlpapi.dll