CreateIpForwardEntry, fonction (iphlpapi.h)
La fonction CreateIpForwardEntry crée un itinéraire dans la table de routage IPv4 de l’ordinateur local.
Syntaxe
IPHLPAPI_DLL_LINKAGE DWORD CreateIpForwardEntry(
[in] PMIB_IPFORWARDROW pRoute
);
Paramètres
[in] pRoute
Pointeur vers une structure de MIB_IPFORWARDROW qui spécifie les informations relatives à la nouvelle route. L’appelant doit spécifier des valeurs pour tous les membres de cette structure. L’appelant doit spécifier MIB_IPPROTO_NETMGMT pour le membre dwForwardProto de MIB_IPFORWARDROW.
Valeur retournée
La fonction retourne NO_ERROR (zéro) si la fonction réussit.
Si la fonction échoue, la valeur de retour est l’un des codes d’erreur suivants.
| Code de retour | Description |
|---|---|
|
Accès refusé. Cette erreur est retournée sur Windows Vista et Windows Server 2008 dans plusieurs conditions, notamment : 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). |
|
Un paramètre d’entrée n’est pas valide, aucune action n’a été effectuée. Cette erreur est retournée si le paramètre pRoute a la valeur NULL, si le membre dwForwardProto de MIB_IPFORWARDROW n’a pas été défini sur MIB_IPPROTO_NETMGMT, si le membre dwForwardMask de la structure PMIB_IPFORWARDROW n’est pas un masque de sous-réseau IPv4 valide ou si l’un des autres membres de la structure MIB_IPFORWARDROW n’est pas valide. |
|
Le transport IPv4 n’est pas configuré sur l’ordinateur local. |
|
Utilisez FormatMessage pour obtenir la chaîne de message de l’erreur retournée. |
Notes
Le membre dwForwardProto de MIB_IPFORWARDROW structure pointée par le paramètre de route doit être défini sur MIB_IPPROTO_NETMGMT sinon , CreateIpForwardEntry é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 par le biais de la gestion réseau, comme 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 par 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 Métrique 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, CreateIpForwardEntry 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.
Un certain nombre de membres de la structure MIB_IPFORWARDROW pointées par le paramètre d’itinéraire ne sont actuellement pas utilisés par CreateIpForwardEntry. Ces membres incluent dwForwardPolicy, dwForwardType, dwForwardAge, dwForwardNextHopAS, dwForwardMetric2, dwForwardMetric3, dwForwardMetric4 et dwForwardMetric5.
Une nouvelle route créée par CreateIpForwardEntry aura automatiquement une valeur par défaut pour dwForwardAge d’INFINITE .
Pour modifier un itinéraire existant dans la table de routage IPv4, utilisez la fonction SetIpForwardEntry . Pour récupérer la table de routage IPv4, appelez la fonction GetIpForwardTable .
Sur Windows Vista et versions ultérieures, la fonction CreateIpForwardEntry ne peut être appelée que par un utilisateur connecté en tant que membre du groupe Administrateurs. Si CreateIpForwardEntry est appelé par un utilisateur qui n’est pas membre du groupe Administrateurs, l’appel de fonction échoue et ERROR_ACCESS_DENIED est retourné.
La fonction CreateIpForwardEntry 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 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 ensuite 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.
Exemples
L’exemple suivant montre comment remplacer la passerelle par défaut par NewGateway. Le simple appel de GetIpForwardTable, la modification de la passerelle, puis l’appel de SetIpForwardEntry ne modifient 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.
#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);
}
Spécifications
| 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 |
Voir aussi
Informations de référence sur les fonctions d’assistance IP