Fungsi IpReleaseAddress (iphlpapi.h)

Artikel
02/28/2024

Fungsi IpReleaseAddress merilis alamat IPv4 yang sebelumnya diperoleh melalui Dynamic Host Configuration Protocol (DHCP).

Sintaks

IPHLPAPI_DLL_LINKAGE DWORD IpReleaseAddress(
  [in] PIP_ADAPTER_INDEX_MAP AdapterInfo
);

Parameter

[in] AdapterInfo

Penunjuk ke struktur IP_ADAPTER_INDEX_MAP yang menentukan adaptor yang terkait dengan alamat IPv4 untuk dilepaskan.

Nilai kembali

Jika fungsi berhasil, nilai yang dikembalikan NO_ERROR.

Jika fungsi gagal, gunakan FormatMessage untuk mendapatkan string pesan untuk kesalahan yang dikembalikan.

Menampilkan kode	Deskripsi
ERROR_INVALID_PARAMETER	Salah satu parameter tidak valid. Kesalahan ini dikembalikan jika parameter AdapterInfo adalah NULL atau jika anggota Nama dari struktur PIP_ADAPTER_INDEX_MAP yang ditujukkan oleh parameter AdapterInfo tidak valid.
ERROR_PROC_NOT_FOUND	Pengecualian terjadi selama permintaan ke DHCP untuk rilis alamat IPv4.
Lainnya	Gunakan FormatMessage untuk mendapatkan string pesan untuk kesalahan yang dikembalikan.

Keterangan

Fungsi IpReleaseAddress khusus untuk IPv4 dan hanya merilis alamat IPv4 yang sebelumnya diperoleh melalui Dynamic Host Configuration Protocol (DHCP). Anggota Nama dari struktur IP_ADAPTER_INDEX_MAP yang ditunjukkan oleh parameter AdapterInfo adalah satu-satunya anggota yang digunakan untuk menentukan alamat DHCP yang akan dirilis.

Array struktur IP_ADAPTER_INDEX_MAP dikembalikan dalam struktur IP_INTERFACE_INFO oleh fungsi GetInterfaceInfo . Struktur IP_INTERFACE_INFO yang dikembalikan oleh GetInterfaceInfo berisi setidaknya satu struktur IP_ADAPTER_INDEX_MAP meskipun anggota NumAdapters dari struktur IP_INTERFACE_INFO menunjukkan bahwa tidak ada adaptor jaringan dengan IPv4 yang diaktifkan. Ketika anggota NumAdapters dari struktur IP_INTERFACE_INFO yang dikembalikan oleh GetInterfaceInfo adalah nol, nilai anggota struktur IP_ADAPTER_INDEX_MAP tunggal yang dikembalikan dalam struktur IP_INTERFACE_INFO tidak terdefinisi.

Jika anggota Nama dari struktur IP_ADAPTER_INDEX_MAP yang ditujukkan oleh parameter AdapterInfo adalah NULL, fungsi IpReleaseAddress mengembalikan ERROR_INVALID_PARAMETER.

Tidak ada fungsi yang tersedia untuk merilis atau memperbarui alamat IPv6. Ini hanya dapat dilakukan dengan menjalankan perintah Ipconfig:

ipconfig /release6

ipconfig /renew6

Contoh

Contoh berikut mengambil daftar adaptor jaringan dengan IPv4 diaktifkan pada sistem lokal, lalu merilis dan memperbarui alamat IPv4 untuk adaptor pertama dalam daftar.

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

Persyaratan

Persyaratan	Nilai
Klien minimum yang didukung	Windows 2000 Professional [hanya aplikasi desktop]
Server minimum yang didukung	Windows 2000 Server [hanya aplikasi desktop]
Target Platform	Windows
Header	iphlpapi.h
Pustaka	Iphlpapi.lib
DLL	Iphlpapi.dll