Функция IpRenewAddress (iphlpapi.h)

Статья
08/24/2023

Функция IpRenewAddress продлевает аренду IPv4-адреса, ранее полученного по протоколу DHCP.

Синтаксис

IPHLPAPI_DLL_LINKAGE DWORD IpRenewAddress(
  [in] PIP_ADAPTER_INDEX_MAP AdapterInfo
);

Параметры

[in] AdapterInfo

Указатель на структуру IP_ADAPTER_INDEX_MAP , указывающую адаптер, связанный с IP-адресом для обновления.

Возвращаемое значение

Если функция выполнена успешно, возвращаемое значение будет NO_ERROR.

Если функция завершается сбоем, используйте FormatMessage , чтобы получить строку сообщения для возвращаемой ошибки.

Код возврата	Описание
ERROR_INVALID_PARAMETER	Один из параметров недопустим. Эта ошибка возвращается, если параметр AdapterInfo имеет значение NULL или если элемент Nameструктуры PIP_ADAPTER_INDEX_MAP , на который указывает параметр AdapterInfo , является недопустимым.
ERROR_PROC_NOT_FOUND	Во время запроса к DHCP на продление IPv4-адреса возникло исключение.
Другое	Используйте FormatMessage , чтобы получить строку сообщения для возвращаемой ошибки.

Функция IpRenewAddress зависит от протокола IPv4 и обновляет только IPv4-адрес, ранее полученный по протоколу DHCP. Элемент Name структуры IP_ADAPTER_INDEX_MAP , на который указывает параметр AdapterInfo , является единственным элементом, используемым для определения ОБНОВЛЯемого DHCP-адреса.

Массив структур IP_ADAPTER_INDEX_MAP возвращается в структуре IP_INTERFACE_INFO функцией GetInterfaceInfo . Структура IP_INTERFACE_INFO , возвращаемая GetInterfaceInfo , содержит по крайней мере одну структуру IP_ADAPTER_INDEX_MAP , даже если элемент NumAdaptersструктуры IP_INTERFACE_INFO указывает, что сетевые адаптеры с IPv4 не включены. Если элемент NumAdaptersструктуры IP_INTERFACE_INFO , возвращаемой GetInterfaceInfo , равен нулю, значение членов одной структуры IP_ADAPTER_INDEX_MAP , возвращаемое в структуре IP_INTERFACE_INFO , не определено.

Если элемент Nameструктуры IP_ADAPTER_INDEX_MAP , на который указывает параметр AdapterInfo , имеет значение NULL, функция IpRenewAddress возвращает ERROR_INVALID_PARAMETER.

Нет доступных функций для освобождения или продления IPv6-адреса. Это можно сделать только с помощью команды Ipconfig:

ipconfig /release6

ipconfig /renew6

Примеры

В следующем примере извлекается список сетевых адаптеров с включенным протоколом IPv4 в локальной системе, а затем освобождается и обновляется IPv4-адрес для первого адаптера в списке.

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

Требования


Минимальная версия клиента	Windows 2000 Professional [только классические приложения]
Минимальная версия сервера	Windows 2000 Server [только классические приложения]
Целевая платформа	Windows
Header	iphlpapi.h
Библиотека	Iphlpapi.lib
DLL	Iphlpapi.dll