Fungsi IpRenewAddress (iphlpapi.h)

Artikel
08/24/2023

Fungsi IpRenewAddress memperbarui sewa pada alamat IPv4 yang sebelumnya diperoleh melalui Dynamic Host Configuration Protocol (DHCP).

Sintaks

IPHLPAPI_DLL_LINKAGE DWORD IpRenewAddress(
  [in] PIP_ADAPTER_INDEX_MAP AdapterInfo
);

Parameter

[in] AdapterInfo

Penunjuk ke struktur IP_ADAPTER_INDEX_MAP yang menentukan adaptor yang terkait dengan alamat IP untuk diperpanjang.

Menampilkan nilai

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 perpanjangan alamat IPv4.
Lainnya	Gunakan FormatMessage untuk mendapatkan string pesan untuk kesalahan yang dikembalikan.

Keterangan

Fungsi IpRenewAddress khusus untuk IPv4 dan hanya memperbarui 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 diperpanjang.

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 struktur IP_ADAPTER_INDEX_MAP yang ditujukkan oleh parameter AdapterInfo adalah NULL, fungsi IpRenewAddress 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.

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

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

/* Note: could also use malloc() and free() */
#define MALLOC(x) HeapAlloc(GetProcessHeap(), 0, (x))
#define FREE(x) HeapFree(GetProcessHeap(), 0, (x))

void main()
{

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

    PIP_INTERFACE_INFO pInfo;
    pInfo = (IP_INTERFACE_INFO *) MALLOC( sizeof(IP_INTERFACE_INFO) );
    ULONG ulOutBufLen = 0;
    DWORD dwRetVal = 0;

    // 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");
      FREE(pInfo);
      pInfo = NULL;
      return;
    }
    else {
      printf("GetInterfaceInfo failed.\n");
      LPVOID lpMsgBuf;
                
      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.\n");
    }

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

    /* Free allocated memory no longer needed */
    if (pInfo) {
        FREE(pInfo);
        pInfo = NULL;
    }
}

Persyaratan


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