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

Статья
08/24/2023

Функция DeleteIpForwardEntry удаляет существующий маршрут в таблице маршрутизации IPv4 локального компьютера.

Синтаксис

IPHLPAPI_DLL_LINKAGE DWORD DeleteIpForwardEntry(
  [in] PMIB_IPFORWARDROW pRoute
);

Параметры

[in] pRoute

Указатель на структуру MIB_IPFORWARDROW . Эта структура указывает сведения, определяющие маршрут для удаления. Вызывающий объект должен указать значения для членов структуры dwForwardIfIndex, dwForwardDest, dwForwardMask, dwForwardNextHop и dwForwardProto .

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

Функция возвращает NO_ERROR (ноль), если подпрограмма выполнена успешно.

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

Код ошибки	Значение
ERROR_ACCESS_DENIED	Отказано в доступе". Эта ошибка возвращается в Windows Vista и Windows Server 2008 при нескольких условиях, которые включают следующее: у пользователя отсутствуют необходимые права администратора на локальном компьютере или приложение не работает в расширенной оболочке в качестве встроенного администратора (администратора запуска от имени администратора).
ERROR_INVALID_PARAMETER	Входной параметр недопустим, никаких действий не было выполнено. Эта ошибка возвращается, если параметр pRoute имеет значение NULL, член dwForwardMaskструктуры PMIB_IPFORWARDROW не является допустимой маской подсети IPv4, элемент dwForwardIfIndex имеет значение NULL или один из других элементов структуры MIB_IPFORWARDROW является недопустимым.
ERROR_NOT_FOUND	Параметр pRoute указывает на несуществующую запись маршрута.
ERROR_NOT_SUPPORTED	Транспорт IPv4 не настроен на локальном компьютере.
(другое)	Функция может возвращать другие коды ошибок.

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

Член dwForwardProtoMIB_IPFORWARDROW указателя структуры по параметру route должен иметь значение MIB_IPPROTO_NETMGMT в противном случае DeleteIpForwardEntry завершится ошибкой . Идентификаторы протокола маршрутизации используются для идентификации сведений о маршруте для указанного протокола маршрутизации. Например, MIB_IPPROTO_NETMGMT используется для определения сведений о маршруте для IP-маршрутизации, заданной с помощью управления сетью, например протокола DHCP, snmp или вызовов функций CreateIpForwardEntry, DeleteIpForwardEntry или SetIpForwardEntry .

В Windows Vista и Windows Server 2008 Метод DeleteIpForwardEntry работает только с интерфейсами с одним вложенным интерфейсом (где интерфейс LUID и подинтерфес LUID совпадают). Элемент dwForwardIfIndex структуры MIB_IPFORWARDROW определяет интерфейс .

Некоторые элементы структуры MIB_IPFORWARDROW , на которые указывает параметр маршрута , в настоящее время не используются в CreateIpForwardEntry. К этим элементам относятся dwForwardPolicy, dwForwardType, dwForwardAge, dwForwardNextHopAS, dwForwardMetric1, dwForwardMetric2, dwForwardMetric3, dwForwardMetric4 и dwForwardMetric5.

Чтобы изменить существующий маршрут в таблице маршрутизации IPv4, используйте функцию SetIpForwardEntry . Чтобы получить таблицу маршрутизации IPv4, вызовите функцию GetIpForwardTable .

В Windows Vista и более поздних версиях функция DeleteIpForwardEntry может вызываться только пользователем, вошедшего в систему как член группы "Администраторы". Если метод DeleteIpForwardEntry вызывается пользователем, который не является членом группы администраторов, вызов функции завершится ошибкой и ERROR_ACCESS_DENIED возвращается.

Функция DeleteIpForwardEntry также может завершиться сбоем из-за контроля учетных записей пользователей (UAC) в Windows Vista и более поздних версиях. Если приложение, содержащее эту функцию, выполняется пользователем, вошедшего в систему как член группы администраторов, отличный от встроенного администратора, этот вызов завершится ошибкой, если приложение не было отмечено в файле манифеста с параметром requestedExecutionLevel , для которого задано значение requireAdministrator. Если в приложении отсутствует этот файл манифеста, пользователь, вошедший в систему как член группы администраторов, отличный от встроенного администратора, должен выполнить приложение в расширенной оболочке в качестве встроенного администратора (администратора запуска от имени), чтобы эта функция была успешной.

Примечание В Windows NT 4.0 и Windows 2000 и более поздних версий эта функция выполняет привилегированную операцию. Для успешного выполнения этой функции вызывающий объект должен войти в систему как член группы Администраторы или NetworkConfigurationOperators.

Примеры

В следующем примере кода показано, как изменить шлюз по умолчанию на NewGateway. Вызов GetIpForwardTable, изменение шлюза, а затем вызов SetIpForwardEntry не изменит маршрут, а добавит новый. Если существует несколько шлюзов по умолчанию, этот код удалит их. Имейте в виду, что новый шлюз должен быть жизнеспособным; В противном случае TCP/IP игнорирует изменение.

Примечание Выполнение этого кода приведет к изменению таблиц IP-маршрутизации и, скорее всего, приведет к сбою сетевой активности.

#ifndef WIN32_LEAN_AND_MEAN
#define WIN32_LEAN_AND_MEAN
#endif

#include <windows.h>
#include <winsock2.h>
#include <iphlpapi.h>
#include <stdio.h>
#include <stdlib.h>

#pragma comment(lib, "iphlpapi.lib")

int main()
{
    // Declare and initialize variables
    PMIB_IPFORWARDTABLE pIpForwardTable = NULL;
    PMIB_IPFORWARDROW pRow = NULL;
    DWORD dwSize = 0;
    BOOL bOrder = FALSE;
    DWORD dwStatus = 0;
    DWORD NewGateway = 0xDDBBCCAA;      // this is in host order Ip Address AA.BB.CC.DD is DDCCBBAA

    unsigned int i;

// Identify the required size of the buffer.
    dwStatus = GetIpForwardTable(pIpForwardTable, &dwSize, bOrder);
    if (dwStatus == ERROR_INSUFFICIENT_BUFFER) {
        // Allocate memory for the table.
        if (!(pIpForwardTable = (PMIB_IPFORWARDTABLE) malloc(dwSize))) {
            printf("Malloc failed. Out of memory.\n");
            exit(1);
        }
        // Retrieve the table.
        dwStatus = GetIpForwardTable(pIpForwardTable, &dwSize, bOrder);
    }

    if (dwStatus != ERROR_SUCCESS) {
        printf("getIpForwardTable failed.\n");
        if (pIpForwardTable)
            free(pIpForwardTable);
        exit(1);
    }
// Search for the required row in the table. The default gateway has a destination
// of 0.0.0.0. Be aware the table continues to be searched, but only
// one row is copied. This is to ensure that, if multiple gateways exist, all of them are deleted.
// 
    for (i = 0; i < pIpForwardTable->dwNumEntries; i++) {
        if (pIpForwardTable->table[i].dwForwardDest == 0) {
            // The default gateway was found.
            if (!pRow) {
                // Allocate memory to store the row. This is easier than manually filling
                // the row structure; only the gateway address is changed.
                //
                pRow = (PMIB_IPFORWARDROW) malloc(sizeof (MIB_IPFORWARDROW));
                if (!pRow) {
                    printf("Malloc failed. Out of memory.\n");
                    exit(1);
                }
                // Copy the row.
                memcpy(pRow, &(pIpForwardTable->table[i]),
                       sizeof (MIB_IPFORWARDROW));
            }
            // Delete the old default gateway entry.
            dwStatus = DeleteIpForwardEntry(&(pIpForwardTable->table[i]));

            if (dwStatus != ERROR_SUCCESS) {
                printf("Could not delete old gateway\n");
                exit(1);
            }
        }
    }

// Set the nexthop field to our new gateway. All other properties of the route will
// remain the same.
    pRow->dwForwardNextHop = NewGateway;

// Create a new route entry for the default gateway.
    dwStatus = CreateIpForwardEntry(pRow);

    if (dwStatus == NO_ERROR)
        printf("Gateway changed successfully\n");
    else if (dwStatus == ERROR_INVALID_PARAMETER)
        printf("Invalid parameter.\n");
    else
        printf("Error: %d\n", dwStatus);

// Free the memory. 
    if (pIpForwardTable)
        free(pIpForwardTable);
    if (pRow)
        free(pRow);

    exit(0);
}

Требования


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