SetIpForwardEntry2, fonction (netioapi.h)

Article
02/29/2024

La fonction SetIpForwardEntry2 définit les propriétés d’une entrée de route IP sur l’ordinateur local.

Syntaxe

IPHLPAPI_DLL_LINKAGE _NETIOAPI_SUCCESS_ NETIOAPI_API SetIpForwardEntry2(
  [in] const MIB_IPFORWARD_ROW2 *Route
);

Paramètres

[in] Route

Pointeur vers une entrée de structure MIB_IPFORWARD_ROW2 pour une entrée de route IP. Le membre DestinationPrefix du MIB_IPFORWARD_ROW2 doit être défini sur un préfixe de destination IP valide, le membre NextHop du MIB_IPFORWARD_ROW2 doit être défini sur une famille d’adresses IP et une adresse IP valides, et le membre InterfaceLuid ou InterfaceIndex du MIB_IPFORWARD_ROW2 doit être spécifié.

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 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).
ERROR_INVALID_PARAMETER	Un paramètre non valide a été transmis à la fonction. Cette erreur est retournée si un pointeur NULL est passé dans le paramètre Route , si le membre DestinationPrefix du MIB_IPFORWARD_ROW2 pointé par le paramètre Route n’a pas été spécifié, si le membre NextHop du MIB_IPFORWARD_ROW2 pointé par le paramètre Route n’a pas été spécifié, ou les deux membres InterfaceLuid ou InterfaceIndex du MIB_IPFORWARD_ROW2 pointés par route le paramètre n’a pas été spécifié.
ERROR_NOT_FOUND	L’interface spécifiée est introuvable. Cette erreur est retournée si l’interface réseau spécifiée par le membre InterfaceLuid ou InterfaceIndex du MIB_IPFORWARD_ROW2 pointé par le paramètre Route est introuvable.
Autres	Utilisez FormatMessage pour obtenir la chaîne de message de l’erreur retournée.

Remarques

La fonction SetIpForwardEntry2 est définie sur Windows Vista et versions ultérieures.

La fonction SetIpForwardEntry2 permet de définir les propriétés d’une entrée de route IP existante sur un ordinateur local.

Le membre DestinationPrefix dans la structure MIB_IPFORWARD_ROW2 pointée par le paramètre Route doit être initialisé avec un préfixe d’adresse IP et une famille valides. Le membre NextHop dans la structure MIB_IPFORWARD_ROW2 pointée par le paramètre Route doit être initialisé sur une adresse IP et une famille valides. En outre, au moins un des membres suivants dans la structure MIB_IPFORWARD_ROW2 pointant vers le paramètre Route doit être initialisé sur l’interface : InterfaceLuid ou InterfaceIndex.

Les champs sont utilisés dans l’ordre indiqué ci-dessus. Ainsi, si InterfaceLuid est spécifié, ce membre est utilisé pour déterminer l’interface sur laquelle ajouter l’adresse IP de monodiffusion. Si aucune valeur n’a été définie pour le membre InterfaceLuid (les valeurs de ce membre ont été définies sur zéro), le membre InterfaceIndex est ensuite utilisé pour déterminer l’interface.

Le décalage de la métrique d’itinéraire spécifié dans le membre Métrique de la structure MIB_IPFORWARD_ROW2 pointée par le paramètre Route ne représente qu’une partie de la métrique d’itinéraire complète. La métrique complète est une combinaison de ce décalage de métrique d’itinéraire ajouté à la métrique d’interface spécifiée dans le membre Métrique de la structure MIB_IPINTERFACE_ROW de l’interface associée. Une application peut récupérer la métrique d’interface en appelant la fonction GetIpInterfaceEntry .

Les membres Age et Origin de la structure MIB_IPFORWARD_ROW2 pointées par la ligne sont ignorés lorsque la fonction SetIpForwardEntry2 est appelée. Ces membres sont définis par la pile réseau et ne peuvent pas être modifiés à l’aide de la fonction SetIpForwardEntry2 .

La fonction SetIpForwardEntry2 échoue si les membres DestinationPrefix et NextHop du MIB_IPFORWARD_ROW2 pointés par le paramètre Route ne correspondent pas à une entrée de route IP sur l’interface spécifiée.

La fonction SetIpForwardEntry2 ne peut être appelée que par un utilisateur connecté en tant que membre du groupe Administrateurs. Si SetIpForwardEntry2 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 SetIpForwardEntry2 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.

Configuration requise

Condition requise	Valeur
Client minimal pris en charge	Windows Vista [applications de bureau uniquement]
Serveur minimal pris en charge	Windows Server 2008 [applications de bureau uniquement]
Plateforme cible	Windows
En-tête	netioapi.h (include Iphlpapi.h)
Bibliothèque	Iphlpapi.lib
DLL	Iphlpapi.dll