| UID | title | description | helpviewer_keywords | old-location | tech.root | ms.assetid | ms.date | ms.keywords | req.header | req.include-header | req.target-type | req.target-min-winverclnt | req.target-min-winversvr | req.kmdf-ver | req.umdf-ver | req.ddi-compliance | req.unicode-ansi | req.idl | req.max-support | req.namespace | req.assembly | req.type-library | req.lib | req.dll | req.irql | targetos | req.typenames | req.redist | ms.custom | f1_keywords | dev_langs | topic_type | api_type | api_location | api_name | |||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
NF:iphlpapi.IpReleaseAddress |
IpReleaseAddress function (iphlpapi.h) |
The IpReleaseAddress function releases an IPv4 address previously obtained through the Dynamic Host Configuration Protocol (DHCP). |
|
iphlp\ipreleaseaddress.htm |
IpHlp |
d937ea44-1ca3-49e0-913d-fb77888d05fc |
12/05/2018 |
IpReleaseAddress, IpReleaseAddress function [IP Helper], _iphlp_ipreleaseaddress, iphlp.ipreleaseaddress, iphlpapi/IpReleaseAddress |
iphlpapi.h |
Windows |
Windows 2000 Professional [desktop apps only] |
Windows 2000 Server [desktop apps only] |
Iphlpapi.lib |
Iphlpapi.dll |
Windows |
19H1 |
|
|
|
|
|
|
The IpReleaseAddress function releases an IPv4 address previously obtained through the Dynamic Host Configuration Protocol (DHCP).
A pointer to an IP_ADAPTER_INDEX_MAP structure that specifies the adapter associated with the IPv4 address to release.
If the function succeeds, the return value is NO_ERROR.
If the function fails, use FormatMessage to obtain the message string for the returned error.
| Return code | Description |
|---|---|
|
One of the parameters is invalid. This error is returned if the AdapterInfo parameter is NULL or if the Name member of the PIP_ADAPTER_INDEX_MAP structure pointed to by the AdapterInfo parameter is invalid. |
|
An exception occurred during the request to DHCP for the release of the IPv4 address. |
|
Use FormatMessage to obtain the message string for the returned error. |
The IpReleaseAddress function is specific to IPv4 and releases only an IPv4 address previously obtained through the Dynamic Host Configuration Protocol (DHCP). The Name member of the IP_ADAPTER_INDEX_MAP structure pointed to by the AdapterInfo parameter is the only member used to determine the DHCP address to release.
An array of IP_ADAPTER_INDEX_MAP structures is returned in the IP_INTERFACE_INFO structure by the GetInterfaceInfo function. The IP_INTERFACE_INFO structure returned by GetInterfaceInfo contains at least one IP_ADAPTER_INDEX_MAP structure even if the NumAdapters member of the IP_INTERFACE_INFO structure indicates that no network adapters with IPv4 are enabled. When the NumAdapters member of the IP_INTERFACE_INFO structure returned by GetInterfaceInfo is zero, the value of the members of the single IP_ADAPTER_INDEX_MAP structure returned in the IP_INTERFACE_INFO structure is undefined.
If the Name member of the IP_ADAPTER_INDEX_MAP structure pointed to by the AdapterInfo parameter is NULL, the IpReleaseAddress function returns ERROR_INVALID_PARAMETER.
There are no functions available for releasing or renewing an IPv6 address. This can only be done by executing the Ipconfig command:
ipconfig /release6
ipconfig /renew6
The following example retrieves the list of network adapters with IPv4 enabled on the local system, then releases and renews the IPv4 address for the first adapter in the list.
#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;
}