Función IpReleaseAddress (iphlpapi.h)

Artículo
03/05/2024

La función IpReleaseAddress libera una dirección IPv4 obtenida previamente a través del Protocolo de configuración dinámica de host (DHCP).

Sintaxis

IPHLPAPI_DLL_LINKAGE DWORD IpReleaseAddress(
  [in] PIP_ADAPTER_INDEX_MAP AdapterInfo
);

Parámetros

[in] AdapterInfo

Puntero a una estructura de IP_ADAPTER_INDEX_MAP que especifica el adaptador asociado a la dirección IPv4 que se va a liberar.

Valor devuelto

Si la función se ejecuta correctamente, el valor devuelto es NO_ERROR.

Si se produce un error en la función, use FormatMessage para obtener la cadena de mensaje para el error devuelto.

Código devuelto	Descripción
ERROR_INVALID_PARAMETER	Uno de los parámetros no es válido. Este error se devuelve si el parámetro AdapterInfo es NULL o si el miembro Name de la estructura PIP_ADAPTER_INDEX_MAP a la que apunta el parámetro AdapterInfo no es válido.
ERROR_PROC_NOT_FOUND	Se produjo una excepción durante la solicitud a DHCP para la versión de la dirección IPv4.
Otros	Use FormatMessage para obtener la cadena de mensaje para el error devuelto.

Comentarios

La función IpReleaseAddress es específica de IPv4 y libera solo una dirección IPv4 obtenida anteriormente a través del Protocolo de configuración dinámica de host (DHCP). El miembro Name de la estructura IP_ADAPTER_INDEX_MAP a la que apunta el parámetro AdapterInfo es el único miembro utilizado para determinar la dirección DHCP que se va a liberar.

La función GetInterfaceInfo devuelve una matriz de estructuras de IP_ADAPTER_INDEX_MAP en la estructura IP_INTERFACE_INFO. La estructura IP_INTERFACE_INFO devuelta por GetInterfaceInfo contiene al menos una estructura de IP_ADAPTER_INDEX_MAP incluso si el miembro NumAdapters de la estructura IP_INTERFACE_INFO indica que no hay adaptadores de red con IPv4 habilitados. Cuando el miembro NumAdapters de la estructura de IP_INTERFACE_INFO devuelto por GetInterfaceInfo es cero, el valor de los miembros de la estructura de IP_ADAPTER_INDEX_MAP única devuelta en la estructura de IP_INTERFACE_INFO no está definida.

Si el miembro Name de la estructura de IP_ADAPTER_INDEX_MAP apuntado por el parámetro AdapterInfo es NULL, la función IpReleaseAddress devuelve ERROR_INVALID_PARAMETER.

No hay funciones disponibles para liberar o renovar una dirección IPv6. Esto solo se puede hacer ejecutando el comando Ipconfig:

ipconfig /release6

ipconfig /renew6

Ejemplos

En el ejemplo siguiente se recupera la lista de adaptadores de red con IPv4 habilitado en el sistema local y, a continuación, se libera y renueva la dirección IPv4 para el primer adaptador de la lista.

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

Requisitos

Requisito	Value
Cliente mínimo compatible	Windows 2000 Professional [solo aplicaciones de escritorio]
Servidor mínimo compatible	Windows 2000 Server [solo aplicaciones de escritorio]
Plataforma de destino	Windows
Encabezado	iphlpapi.h
Library	Iphlpapi.lib
Archivo DLL	Iphlpapi.dll