Fonction SetIpForwardEntry (iphlpapi.h)

Article
08/24/2023

La fonction SetIpForwardEntry modifie un itinéraire existant dans la table de routage IPv4 de l’ordinateur local.

Syntaxe

IPHLPAPI_DLL_LINKAGE DWORD SetIpForwardEntry(
  [in] PMIB_IPFORWARDROW pRoute
);

Paramètres

[in] pRoute

Pointeur vers une structure MIB_IPFORWARDROW qui spécifie les nouvelles informations pour l’itinéraire existant. L’appelant doit spécifier MIB_IPPROTO_NETMGMT pour le membre dwForwardProto de cette structure. L’appelant doit également spécifier des valeurs pour les membres dwForwardIfIndex, dwForwardDest, dwForwardMask, dwForwardNextHop et dwForwardPolicy de la structure.

Valeur retournée

Si la fonction réussit, la valeur de retour est NO_ERROR.

Si la fonction échoue, la valeur de retour est l’un des codes d’erreur suivants.

Code de retour	Description
ERROR_ACCESS_DENIED	L’accès est refusé. Cette erreur est retournée sur Windows Vista et Windows Server 2008 dans plusieurs conditions qui incluent les suivantes : l’utilisateur n’a pas les privilèges d’administration requis sur l’ordinateur local ou l’application ne s’exécute pas dans un interpréteur de commandes amélioré en tant qu’administrateur intégré (administrateur runas).
ERROR_FILE_NOT_FOUND	Le système ne peut pas trouver le fichier spécifié. Cette erreur est retournée sur Windows Vista et versions ultérieures si l’interface réseau spécifiée par le membre dwForwardIfIndex de la structure MIB_IPFORWARDROW pointée vers le paramètre pRoute est introuvable.
ERROR_INVALID_PARAMETER	Le paramètre pRoute a la valeur NULL ou SetIpForwardEntry ne peut pas lire à partir de la mémoire pointée par pRoute, ou l’un des membres de la structure MIB_IPFORWARDROW n’est pas valide.
ERROR_NOT_FOUND	L’élément est introuvable. L’erreur est retournée sur Windows Vista et les versions ultérieures lorsque la fonction DeleteIpForwardEntry , puis la fonction SetIpForwardEntry sont appelées pour la même entrée de table de routage IPv4.
ERROR_NOT_SUPPORTED	La demande n'est pas prise en charge. Cette valeur est retournée si le transport IPv4 n’est pas configuré sur l’ordinateur local. Cette erreur est également retournée sur Windows Server 2003 et versions antérieures si aucune pile TCP/IP n’est configurée sur l’ordinateur local.
Autres	Utilisez FormatMessage pour obtenir la chaîne de message pour l’erreur retournée.

Remarques

Le membre dwForwardProto de MIB_IPFORWARDROW structure pointée par le paramètre de route doit être défini sur MIB_IPPROTO_NETMGMT sinon , SetIpForwardEntry échouera. Les identificateurs de protocole de routage sont utilisés pour identifier les informations d’itinéraire pour le protocole de routage spécifié. Par exemple, MIB_IPPROTO_NETMGMT est utilisé pour identifier les informations d’itinéraire pour le routage IP défini via la gestion réseau, par exemple le protocole DHCP (Dynamic Host Configuration Protocol), le protocole SNMP (Simple Network Management Protocol) ou par des appels aux fonctions CreateIpForwardEntry, DeleteIpForwardEntry ou SetIpForwardEntry .

Sur Windows Vista et Windows Server 2008, la métrique d’itinéraire spécifiée dans le membre dwForwardMetric1 de la structure MIB_IPFORWARDROW pointée vers le paramètre pRoute représente une combinaison de la métrique d’itinéraire ajoutée à la métrique d’interface spécifiée dans le membre Metric de la structure MIB_IPINTERFACE_ROW de l’interface associée. Par conséquent, le membre dwForwardMetric1 de la structure MIB_IPFORWARDROW doit être égal ou supérieur au membre Metric de la structure MIB_IPINTERFACE_ROW associée. Si une application souhaite définir la métrique d’itinéraire sur 0, le membre dwForwardMetric1 de la structure MIB_IPFORWARDROW doit être défini sur la valeur de la métrique d’interface spécifiée dans le membre Metric de la structure MIB_IPINTERFACE_ROW associée. Une application peut récupérer la métrique d’interface en appelant la fonction GetIpInterfaceEntry .

Sur Windows Vista et Windows Server 2008, la fonction SetIpForwardEntry fonctionne uniquement sur les interfaces avec une seule sous-interface (où l’interface LUID et la sous-interface LUID sont identiques). Le membre dwForwardIfIndex de la structure MIB_IPFORWARDROW spécifie l’interface.

Le membre dwForwardAge auquel MIB_IPFORWARDROW structure pointée par le paramètre de route n’est actuellement pas utilisé par SetIpForwardEntry. Le membre dwForwardAge est utilisé uniquement si le service de routage et d’accès à distance (RRAS) est en cours d’exécution, puis uniquement pour les itinéraires de type MIB_IPPROTO_NETMGMT comme défini sur la page de référence Identificateurs de protocole . Lorsque dwForwardAge est défini sur INFINITE, l’itinéraire n’est pas supprimé en fonction d’un délai d’attente

Valeur. Toute autre valeur pour dwForwardAge spécifie le nombre de secondes jusqu’à ce que la pile TCP/IP supprime l’itinéraire de la table de routage réseau.

Un itinéraire modifié par SetIpForwardEntry aura automatiquement une valeur par défaut pour dwForwardAge d’INFINITE.

Un certain nombre de membres de la structure MIB_IPFORWARDROW pointées par le paramètre de route ne sont actuellement pas utilisés par SetIpForwardEntry. Ces membres incluent dwForwardPolicy, dwForwardType, dwForwardAge, dwForwardNextHopAS, dwForwardMetric1, dwForwardMetric2, dwForwardMetric3, dwForwardMetric4 et dwForwardMetric5.

Pour créer un itinéraire dans la table de routage IP, utilisez la fonction CreateIpForwardEntry . Pour récupérer la table de routage IP, appelez la fonction GetIpForwardTable .

Sur Windows Vista et versions ultérieures, la fonction SetIpForwardEntry ne peut être appelée que par un utilisateur connecté en tant que membre du groupe Administrateurs. Si SetIpForwardEntry est appelé par un utilisateur qui n’est pas membre du groupe Administrateurs, l’appel de fonction échoue et ERROR_ACCESS_DENIED est retourné.

Cette fonction peut également échouer en raison du contrôle de compte d’utilisateur (UAC) sur Windows Vista et versions ultérieures. Si une application qui contient cette fonction est exécutée par un utilisateur connecté en tant que membre du groupe Administrateurs autre que l’administrateur intégré, cet appel échoue, sauf si l’application a été marquée dans le fichier manifeste avec un paramètre requestedExecutionLevel défini sur requireAdministrator. Si l’application ne dispose pas de ce fichier manifeste, un utilisateur connecté en tant que membre du groupe Administrateurs autre que l’administrateur intégré doit alors exécuter l’application dans un interpréteur de commandes amélioré en tant qu’administrateur intégré (administrateur d’exécution) pour que cette fonction réussisse.

Note Sur Windows NT 4.0 et Windows 2000 et versions ultérieures, cette fonction exécute une opération privilégiée. Pour que cette fonction s’exécute correctement, l’appelant doit être connecté en tant que membre du groupe Administrateurs ou du groupe NetworkConfigurationOperators.

Exemples

L’exemple suivant montre comment remplacer la passerelle par défaut par NewGateway. Le simple fait d’appeler GetIpForwardTable, de modifier la passerelle, puis d’appeler SetIpForwardEntry ne modifie pas l’itinéraire, mais simplement en ajouter un nouveau. Si, pour une raison quelconque, plusieurs passerelles par défaut sont présentes, ce code les supprime. Notez que la nouvelle passerelle doit être viable ; sinon, TCP/IP ignore la modification.

Note L’exécution de ce code modifiera vos tables de routage IP et entraînera probablement l’échec de l’activité réseau.

Windows Vista et versions ultérieures : Lorsque la fonction DeleteIpForwardEntry et la fonction SetIpForwardEntry sont appelées pour la même entrée de table de routage sur Windows Vista et versions ultérieures, ERROR_NOT_FOUND est retourné. Le bon moyen de répliquer cet exemple sur Windows Vista et versions ultérieures consiste à utiliser la fonction CreateIpForwardEntry pour créer la nouvelle entrée de table de routage, puis à supprimer l’ancienne entrée de table de routage en appelant la fonction 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);
}

Configuration requise

Condition requise	Valeur
Client minimal pris en charge	Windows 2000 Professionnel [applications de bureau uniquement]
Serveur minimal pris en charge	Windows 2000 Server [applications de bureau uniquement]
Plateforme cible	Windows
En-tête	iphlpapi.h
Bibliothèque	Iphlpapi.lib
DLL	Iphlpapi.dll