Поделиться через

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

  • Статья

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

Синтаксис

IPHLPAPI_DLL_LINKAGE DWORD SetIpForwardEntry(
  [in] PMIB_IPFORWARDROW pRoute
);

Параметры

[in] pRoute

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

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

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

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

Код возврата Описание
ERROR_ACCESS_DENIED
 Отказано в доступе". Эта ошибка возвращается в Windows Vista и Windows Server 2008 при следующих условиях: у пользователя отсутствуют необходимые права администратора на локальном компьютере или приложение не работает в расширенной оболочке в качестве встроенного администратора (администратор запуска от имени).
ERROR_FILE_NOT_FOUND
 Системе не удается найти указанный файл. Эта ошибка возвращается в Windows Vista и более поздних версиях, если не удалось найти сетевой интерфейс, указанный членом dwForwardIfIndexструктуры MIB_IPFORWARDROW , на которую указывает параметр pRoute .
ERROR_INVALID_PARAMETER
 Параметр pRoute имеет значение NULL, или SetIpForwardEntry не может считывать данные из памяти, на которую указывает pRoute, или один из элементов структуры MIB_IPFORWARDROW является недопустимым.
ERROR_NOT_FOUND
 Элемент не найден. Эта ошибка возвращается в Windows Vista и более поздних версиях, когда функция DeleteIpForwardEntry , а затем функция SetIpForwardEntry вызываются для той же записи таблицы маршрутов IPv4.
ERROR_NOT_SUPPORTED
 Запрос не поддерживается. Это значение возвращается, если транспорт IPv4 не настроен на локальном компьютере. Эта ошибка также возвращается в Windows Server 2003 и более ранних версиях, если на локальном компьютере не настроен стек TCP/IP.
Другое
 Используйте FormatMessage , чтобы получить строку сообщения для возвращенной ошибки.

Комментарии

Члену dwForwardProtoструктуры MIB_IPFORWARDROW, на которую указывает параметр маршрута, необходимо задать значение MIB_IPPROTO_NETMGMT в противном случае SetIpForwardEntry завершится ошибкой. Идентификаторы протокола маршрутизации используются для определения сведений о маршрутах для указанного протокола маршрутизации. Например, MIB_IPPROTO_NETMGMT используется для определения сведений о маршруте для IP-маршрутизации, заданной с помощью управления сетью, например протокола DHCP, ПРОТОКОЛА SNMP или путем вызовов функций CreateIpForwardEntry, DeleteIpForwardEntry или SetIpForwardEntry .

В Windows Vista и Windows Server 2008 метрика маршрута, указанная в элементе dwForwardMetric1 структуры MIB_IPFORWARDROW , на которую указывает параметр pRoute , представляет собой сочетание метрики маршрута, добавленной в метрику интерфейса, указанную в элементе MetricMIB_IPINTERFACE_ROW структуры связанного интерфейса. Таким образом, элемент dwForwardMetric1 структуры MIB_IPFORWARDROW должен быть равен или больше элемента Metric связанной MIB_IPINTERFACE_ROW структуры. Если приложение хочет задать для метрики маршрута значение 0, то элемент dwForwardMetric1 структуры MIB_IPFORWARDROW должен быть равен значению метрики интерфейса, указанной в элементе Метрика связанной структуры MIB_IPINTERFACE_ROW . Приложение может получить метрику интерфейса, вызвав функцию GetIpInterfaceEntry .

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

Элемент dwForwardAge , на MIB_IPFORWARDROW структуру, на которую указывает параметр маршрута , в настоящее время не используется SetIpForwardEntry. Член dwForwardAge используется только в том случае, если служба маршрутизации и удаленного доступа (RRAS) запущена, и только для маршрутов типа MIB_IPPROTO_NETMGMT , как определено на странице справочника по идентификаторам протоколов . Если для dwForwardAge задано значение INFINITE, маршрут не будет удален в зависимости от времени ожидания.

альфа. Любое другое значение dwForwardAge указывает время в секундах, пока стек TCP/IP удалит маршрут из таблицы маршрутизации сети.

Маршрут, измененный SetIpForwardEntry , будет автоматически иметь значение по умолчанию для dwForwardAge INFINITE.

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

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

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

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

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

Примеры

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

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

Windows Vista и более поздних версий: При вызове функции DeleteIpForwardEntry и SetIpForwardEntry для одной и той же записи таблицы маршрутов в Windows Vista и более поздних версиях возвращается ERROR_NOT_FOUND. Правильный способ репликации этого примера в Windows Vista и более поздних версий — использовать функцию CreateIpForwardEntry для создания новой записи таблицы маршрутов, а затем удаления старой записи таблицы маршрутизации путем вызова функции DeleteIpForwardEntry .

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

// #ifndef WIN32_LEAN_AND_MEAN
// #define WIN32_LEAN_AND_MEAN
// #endif

// #pragma warning(push)
// #pragma warning(disable: 4127)

// #include <windows.h>

#include <winsock2.h>
#include <ws2tcpip.h>
#include <iphlpapi.h>
#include <stdio.h>

#define MALLOC(x) HeapAlloc(GetProcessHeap(), 0, (x))
#define FREE(x) HeapFree(GetProcessHeap(), 0, (x))
/* Note: could also use malloc() and free() */

int main()
{

    // Declare and initialize variables.

    /* variables used for SetIfForwardEntry */

    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
    DWORD i;

// Find out how big our buffer needs to be.
    dwStatus = GetIpForwardTable(pIpForwardTable, &dwSize, bOrder);
    if (dwStatus == ERROR_INSUFFICIENT_BUFFER) {
        // Allocate the memory for the table
        pIpForwardTable = (PMIB_IPFORWARDTABLE) malloc(dwSize);
        if (pIpForwardTable == NULL) {
            printf("Unable to allocate memory for the IPFORWARDTALE\n");
            exit(1);
        }
        // Now get the table.
        dwStatus = GetIpForwardTable(pIpForwardTable, &dwSize, bOrder);
    }

    if (dwStatus != ERROR_SUCCESS) {
        printf("getIpForwardTable failed.\n");
        if (pIpForwardTable)
            free(pIpForwardTable);
        exit(1);
    }
// Search for the row in the table we want. The default gateway has a destination
// of 0.0.0.0. Notice that we continue looking through the table, but copy only
// one row. This is so that if there happen to be multiple default gateways, we can
// be sure to delete them all.
    for (i = 0; i < pIpForwardTable->dwNumEntries; i++) {
        if (pIpForwardTable->table[i].dwForwardDest == 0) {
            // We have found the default gateway.
            if (!pRow) {
                // Allocate some memory to store the row in. This is easier than filling
                // in the row structure ourselves, and we can be sure to change only the
                // gateway address.
                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 the other properties of the route will
// be the same as they were previously.
    pRow->dwForwardNextHop = NewGateway;

// Create a new route entry for the default gateway.
    dwStatus = SetIpForwardEntry(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 resources.
    if (pIpForwardTable)
        free(pIpForwardTable);
    if (pRow)
        free(pRow);
}

Требования

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

См. также раздел

CreateIpForwardEntry

DeleteIpForwardEntry

GetIpForwardTable

GetIpInterfaceEntry

Справочник по вспомогательным функциям IP

Начальная страница вспомогательного ip-адреса

MIB_IPFORWARDROW

MIB_IPINTERFACE_ROW