ipReleaseAddress 函数 (iphlpapi.h)

项目
08/24/2023

IpReleaseAddress 函数释放以前通过动态主机配置协议 (DHCP) 获取的 IPv4 地址。

语法

IPHLPAPI_DLL_LINKAGE DWORD IpReleaseAddress(
  [in] PIP_ADAPTER_INDEX_MAP AdapterInfo
);

参数

[in] AdapterInfo

指向 IP_ADAPTER_INDEX_MAP 结构的指针，该结构指定要发布的 IPv4 地址关联的适配器。

返回值

如果函数成功，则返回值NO_ERROR。

如果函数失败，请使用 FormatMessage 获取返回错误的消息字符串。

返回代码	说明
ERROR_INVALID_PARAMETER	其中一个参数无效。如果 AdapterInfo 参数为 NULL，或者 AdapterInfo 参数指向的 PIP_ADAPTER_INDEX_MAP 结构的 Name 成员无效，则返回此错误。
ERROR_PROC_NOT_FOUND	在向 DHCP 请求释放 IPv4 地址期间发生异常。
其他	使用 FormatMessage 获取返回错误的消息字符串。

注解

IpReleaseAddress 函数特定于 IPv4，仅发布以前通过动态主机配置协议 (DHCP) 获取的 IPv4 地址。 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
Library	Iphlpapi.lib
DLL	Iphlpapi.dll