IpReleaseAddress 函式 (iphlpapi.h)

發行項
02/28/2024

IpReleaseAddress 函式會釋放先前透過動態主機設定通訊協定取得的 IPv4 位址， (DHCP) 。

語法

IPHLPAPI_DLL_LINKAGE DWORD IpReleaseAddress(
  [in] PIP_ADAPTER_INDEX_MAP AdapterInfo
);

參數

[in] AdapterInfo

IP_ADAPTER_INDEX_MAP 結構的指標，指定要釋放之 IPv4 位址相關聯的配接器。

傳回值

如果函式成功，傳回值會NO_ERROR。

如果函式失敗，請使用 FormatMessage 取得傳回錯誤的訊息字串。

傳回碼	Description
ERROR_INVALID_PARAMETER	其中一個參數無效。如果 AdapterInfo 參數為 NULL，或 AdapterInfo 參數所指向之PIP_ADAPTER_INDEX_MAP結構的 Name 成員無效，就會傳回此錯誤。
ERROR_PROC_NOT_FOUND	針對 IPv4 位址的發行要求期間發生例外狀況。
其他	使用 FormatMessage 取得傳回錯誤的訊息字串。

備註

IpReleaseAddress 函式專屬於 IPv4，而且只會發行先前透過動態主機設定通訊協定取得的 IPv4 位址， (DHCP) 。 AdapterInfo 參數所指向之IP_ADAPTER_INDEX_MAP結構的 Name 成員是唯一用來判斷要釋放之 DHCP 位址的成員。

GetInterfaceInfo 函式會在IP_INTERFACE_INFO結構中傳回IP_ADAPTER_INDEX_MAP結構的數位。 GetInterfaceInfo 所傳回的IP_INTERFACE_INFO結構至少包含一個IP_ADAPTER_INDEX_MAP結構，即使 IP_INTERFACE_INFO 結構的 NumAdapters 成員表示未啟用任何具有 IPv4 的網路適配器也一樣。當 GetInterfaceInfo 所傳回之IP_INTERFACE_INFO結構的 NumAdapters 成員為零時，未定義IP_INTERFACE_INFO結構中所傳回之單一IP_ADAPTER_INDEX_MAP結構的成員值。

如果 AdapterInfo 參數指向之IP_ADAPTER_INDEX_MAP結構的 Name 成員是 NULL，IpReleaseAddress 函式會傳回ERROR_INVALID_PARAMETER。

沒有函式可用來發行或更新 IPv6 位址。這只能藉由執行 Ipconfig 命令來完成：

ipconfig /release6

ipconfig /renew6

範例

下列範例會擷取本機系統上已啟用IPv4的網路適配器清單，然後釋放並更新清單中第一張適配卡的IPv4位址。

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

規格需求

需求	值
最低支援的用戶端	Windows 2000 Professional [僅限傳統型應用程式]
最低支援的伺服器	Windows 2000 Server [僅限桌面應用程式]
目標平台	Windows
標頭	iphlpapi.h
程式庫	Iphlpapi.lib
Dll	Iphlpapi.dll