Функция CreateIpForwardEntry (iphlpapi.h)
Функция CreateIpForwardEntry создает маршрут в таблице маршрутизации IPv4 локального компьютера.
Синтаксис
IPHLPAPI_DLL_LINKAGE DWORD CreateIpForwardEntry(
[in] PMIB_IPFORWARDROW pRoute
);
Параметры
[in] pRoute
Указатель на структуру MIB_IPFORWARDROW , указывающую сведения для нового маршрута. Вызывающий объект должен указать значения для всех членов этой структуры. Вызывающий объект должен указать MIB_IPPROTO_NETMGMT для члена dwForwardProtoMIB_IPFORWARDROW.
Возвращаемое значение
Функция возвращает NO_ERROR (ноль), если функция выполнена успешно.
Если функция завершается сбоем, возвращается один из следующих кодов ошибок.
| Код возврата | Описание |
|---|---|
|
Отказано в доступе". Эта ошибка возвращается в Windows Vista и Windows Server 2008 при нескольких условиях, которые включают следующее: у пользователя отсутствуют необходимые права администратора на локальном компьютере или приложение не работает в расширенной оболочке в качестве встроенного администратора (администратора запуска от имени администратора). |
|
Входной параметр недопустим, никаких действий не было выполнено. Эта ошибка возвращается, если параметр pRoute имеет значение NULL, члену dwForwardProtoMIB_IPFORWARDROW не присвоено значение MIB_IPPROTO_NETMGMT, член dwForwardMaskструктуры PMIB_IPFORWARDROW не является допустимой маской подсети IPv4 или один из других элементов структуры MIB_IPFORWARDROW является недопустимым. |
|
Транспорт IPv4 не настроен на локальном компьютере. |
|
Используйте FormatMessage , чтобы получить строку сообщения для возвращаемой ошибки. |
Комментарии
Член dwForwardProtoструктуры MIB_IPFORWARDROW , на которую указывает параметр route , должен иметь значение MIB_IPPROTO_NETMGMT в противном случае CreateIpForwardEntry завершится ошибкой . Идентификаторы протокола маршрутизации используются для идентификации сведений о маршруте для указанного протокола маршрутизации. Например, MIB_IPPROTO_NETMGMT используется для определения сведений о маршрутах для IP-маршрутизации, заданных с помощью управления сетью, например протокола DHCP, SNMP или вызовов функций CreateIpForwardEntry, DeleteIpForwardEntry или SetIpForwardEntry .
В Windows Vista и Windows Server 2008 метрика маршрута, указанная в элементе dwForwardMetric1 структуры MIB_IPFORWARDROW , на которую указывает параметр pRoute , представляет собой сочетание метрики маршрута, добавленной в метрику интерфейса, указанную в элементе Metricструктуры MIB_IPINTERFACE_ROW связанного интерфейса. Таким образом, элемент dwForwardMetric1 структуры MIB_IPFORWARDROW должен быть равен или больше элемента Metric связанной MIB_IPINTERFACE_ROW структуры. Если приложение хочет задать для метрики маршрута значение 0, то член dwForwardMetric1структуры MIB_IPFORWARDROW должен быть равен значению метрики интерфейса, указанной в элементе Metric связанной структуры MIB_IPINTERFACE_ROW . Приложение может получить метрику интерфейса, вызвав функцию GetIpInterfaceEntry .
В Windows Vista и Windows Server 2008 CreateIpForwardEntry работает только с интерфейсами с одним вложенным интерфейсом (где интерфейс LUID и подинтерфесНЫЙ LUID совпадают). Элемент dwForwardIfIndex структуры MIB_IPFORWARDROW определяет интерфейс .
Некоторые элементы структуры MIB_IPFORWARDROW , на которые указывает параметр маршрута , в настоящее время не используются в CreateIpForwardEntry. К ним относятся dwForwardPolicy, dwForwardType, dwForwardAge, dwForwardNextHopAS, dwForwardMetric2, dwForwardMetric3, dwForwardMetric4 и dwForwardMetric5.
Новый маршрут, созданный createIpForwardEntry , будет автоматически иметь значение по умолчанию для dwForwardAge infinite.
Чтобы изменить существующий маршрут в таблице маршрутизации IPv4, используйте функцию SetIpForwardEntry . Чтобы получить таблицу маршрутизации IPv4, вызовите функцию GetIpForwardTable .
В Windows Vista и более поздних версиях функцию CreateIpForwardEntry может вызывать только пользователь, выполнивший вход в качестве члена группы администраторов. Если метод CreateIpForwardEntry вызывается пользователем, который не является членом группы администраторов, вызов функции завершится ошибкой и ERROR_ACCESS_DENIED возвращается.
Функция CreateIpForwardEntry также может завершиться сбоем из-за контроля учетных записей пользователей (UAC) в Windows Vista и более поздних версиях. Если приложение, содержащее эту функцию, выполняется пользователем, вошедшего в систему как член группы администраторов, отличный от встроенного администратора, этот вызов завершится ошибкой, если приложение не было отмечено в файле манифеста с параметром requestedExecutionLevel , для которого задано значение requireAdministrator. Если в приложении отсутствует этот файл манифеста, пользователь, вошедший в систему как член группы администраторов, отличный от встроенного администратора, должен выполнить приложение в расширенной оболочке в качестве встроенного администратора (администратора запуска от имени), чтобы эта функция была успешной.
Примеры
В следующем примере показано, как изменить шлюз по умолчанию на NewGateway. Простое вызов GetIpForwardTable, изменение шлюза, а затем вызов SetIpForwardEntry не изменит маршрут, а просто добавит новый. Если по какой-либо причине существует несколько шлюзов по умолчанию, этот код удалит их. Обратите внимание, что новый шлюз должен быть жизнеспособным; В противном случае TCP/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 = 0xDDCCBBAA; // this is in host order Ip Address AA.BB.CC.DD is DDCCBBAA
unsigned int 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
if (!(pIpForwardTable = (PMIB_IPFORWARDTABLE) malloc(dwSize))) {
printf("Malloc failed. Out of memory.\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 we 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 = 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 resources
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 |
См. также раздел
Справочник по вспомогательной функции IP