DeleteIpForwardEntry, fonction (iphlpapi.h)
La fonction DeleteIpForwardEntry supprime une route existante dans la table de routage IPv4 de l’ordinateur local.
Syntaxe
IPHLPAPI_DLL_LINKAGE DWORD DeleteIpForwardEntry(
[in] PMIB_IPFORWARDROW pRoute
);
Paramètres
[in] pRoute
Pointeur vers une structure MIB_IPFORWARDROW . Cette structure spécifie les informations qui identifient l’itinéraire à supprimer. L’appelant doit spécifier des valeurs pour les membres dwForwardIfIndex, dwForwardDest, dwForwardMask, dwForwardNextHop et dwForwardProto de la structure.
Valeur retournée
La fonction retourne NO_ERROR (zéro) si la routine réussit.
Si la fonction échoue, la valeur de retour est l’un des codes d’erreur suivants.
| Code d'erreur | Signification |
|---|---|
|
Accès 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). |
|
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 dwForwardMask de la structure PMIB_IPFORWARDROW n’est pas un masque de sous-réseau IPv4 valide, si le membre dwForwardIfIndex a la valeur NULL ou si l’un des autres membres de la structure MIB_IPFORWARDROW n’est pas valide. |
|
Le paramètre pRoute pointe vers une entrée de route qui n’existe pas. |
|
Le transport IPv4 n’est pas configuré sur l’ordinateur local. |
|
La fonction peut retourner d’autres codes d’erreur. |
Si la fonction échoue, utilisez FormatMessage pour obtenir la chaîne de message correspondant à l’erreur retournée.
Notes
Le membre dwForwardProto de MIB_IPFORWARDROW pointeur de structure vers par le paramètre de route doit être défini sur MIB_IPPROTO_NETMGMT sinon , DeleteIpForwardEntry é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, 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, DeleteIpForwardEntry 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és vers le paramètre de route ne sont actuellement pas utilisés par CreateIpForwardEntry. Ces membres incluent dwForwardPolicy, dwForwardType, dwForwardAge, dwForwardNextHopAS, dwForwardMetric1, dwForwardMetric2, dwForwardMetric3, dwForwardMetric4 et dwForwardMetric5.
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 DeleteIpForwardEntry ne peut être appelée que par un utilisateur connecté en tant que membre du groupe Administrateurs. Si DeleteIpForwardEntry 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 DeleteIpForwardEntry 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.
Exemples
L’exemple de code suivant montre comment remplacer la passerelle par défaut par NewGateway. En appelant GetIpForwardTable, la modification de la passerelle, puis l’appel de SetIpForwardEntry ne modifient pas l’itinéraire, mais en ajoutent un nouveau. S’il existe plusieurs passerelles par défaut, ce code les supprimera. Sachez 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 = 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);
}
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 la fonction d’assistance IP