Fonction SetIpInterfaceEntry (netioapi.h)

Article
08/25/2023

La fonction SetIpInterfaceEntry définit les propriétés d’une interface IP sur l’ordinateur local.

Syntaxe

IPHLPAPI_DLL_LINKAGE _NETIOAPI_SUCCESS_ NETIOAPI_API SetIpInterfaceEntry(
  [in, out] PMIB_IPINTERFACE_ROW Row
);

Paramètres

[in, out] Row

Pointeur vers une entrée de structure MIB_IPINTERFACE_ROW pour une interface. Lors de l’entrée, le membre Famille du MIB_IPINTERFACE_ROW doit être défini sur AF_INET6 ou AF_INET et le membre InterfaceLuid ou InterfaceIndex du MIB_IPINTERFACE_ROW doit être spécifié. Lors d’un retour réussi, le membre InterfaceLuid du MIB_IPINTERFACE_ROW est renseigné si le membre InterfaceIndex de l’entrée MIB_IPINTERFACE_ROW a été 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_FILE_NOT_FOUND	Le système ne peut pas trouver le fichier spécifié. Cette erreur est retournée si l’interface réseau LUID ou l’index d’interface spécifié par le membre InterfaceLuid ou InterfaceIndex du MIB_IPINTERFACE_ROW pointé vers le paramètre Row n’était pas une valeur sur l’ordinateur local.
ERROR_INVALID_PARAMETER	Un paramètre non valide a été transmis à la fonction. Cette erreur est retournée si un pointeur NULL est transmis dans le paramètre Row , si le membre Family du MIB_IPINTERFACE_ROW pointé par le paramètre Row n’a pas été spécifié comme AF_INET ou AF_INET6, ou si les deux membres InterfaceLuid ou InterfaceIndex du MIB_IPINTERFACE_ROW pointés par le paramètre Row n’ont pas été spécifiés.
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_IPINTERFACE_ROW pointé par le paramètre Row ne correspond pas à la famille d’adresses IP spécifiée dans le membre Family dans la structure MIB_IPINTERFACE_ROW .
Autres	Utilisez FormatMessage pour obtenir la chaîne de message pour l’erreur retournée.

Remarques

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

La fonction SetIpInterfaceEntry peut être utilisée pour modifier une entrée d’interface IP existante.

Lors de l’entrée, le membre Family de la structure MIB_IPINTERFACE_ROW pointée par le paramètre Row doit être initialisé en AF_INET ou AF_INET6. En outre, lors de l’entrée, au moins un des membres suivants de la structure MIB_IPINTERFACE_ROW pointée vers le paramètre Row doit être initialisé : InterfaceLuid ou InterfaceIndex.

Les champs sont utilisés dans l’ordre indiqué ci-dessus. Par conséquent, si l’interfaceLuid est spécifiée, ce membre est utilisé pour déterminer l’interface. 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.

À la sortie, le membre InterfaceLuid de la structure MIB_IPINTERFACE_ROW pointée par le paramètre Row est renseigné si l’InterfaceIndex a été spécifié.

Les membres MaxReassemblySize, MinRouterAdvertisementInterval, MaxRouterAdvertisementInterval , Connected, SupportsWakeUpPatterns, SupportsNeighborDiscovery, SupportsRouterDiscovery, ReachableTime, TransmitOffload et ReceiveOffload de la structure MIB_IPINTERFACE_ROW pointée vers la ligne sont ignorés lorsque la fonction SetIpInterfaceEntry 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 SetIpInterfaceEntry .

Une application appelle généralement la fonction GetIpInterfaceTable pour récupérer les entrées d’interface IP sur l’ordinateur local ou appelle la fonction GetIpInterfaceEntry pour récupérer uniquement l’entrée d’interface IP à modifier. La structure MIB_IPINTERFACE_ROW pour l’entrée d’interface IP spécifique peut ensuite être modifiée et un pointeur vers cette structure passé à la fonction SetIpInterfaceEntry dans le paramètre Row . Toutefois, pour IPv4, une application ne doit pas essayer de modifier le membre SitePrefixLength de la structure MIB_IPINTERFACE_ROW . Pour IPv4, le membre SitePrefixLength doit avoir la valeur 0.

Une autre méthode possible pour modifier une entrée d’interface IP existante consiste à utiliser la fonction InitializeIpInterfaceEntry pour initialiser les champs d’une entrée de structure MIB_IPINTERFACE_ROW avec des valeurs par défaut. Ensuite, définissez le membre Family et les membres InterfaceIndex ou InterfaceLuid dans la structure MIB_IPINTERFACE_ROW pointée par le paramètre Row pour qu’ils correspondent à l’interface IP à modifier. Une application peut ensuite modifier les champs de l’entrée MIB_IPINTERFACE_ROW qu’elle souhaite modifier, puis appeler la fonction SetIpInterfaceEntry . Toutefois, pour IPv4, une application ne doit pas essayer de modifier le membre SitePrefixLength de la structure MIB_IPINTERFACE_ROW . Pour IPv4, le membre SitePrefixLength doit avoir la valeur 0. Cette approche doit être prudente, car la seule façon de déterminer tous les champs en cours de modification consiste à comparer les champs du MIB_IPINTERFACE_ROW de l’entrée d’interface IP spécifique avec les champs définis par la fonction InitializeIpInterfaceEntry lorsqu’un MIB_IPINTERFACE_ROW est initialisé aux valeurs par défaut.

L’accès simultané non privilégié à plusieurs réseaux de différentes exigences de sécurité crée un trou de sécurité et permet à une application non privilégiée de relayer accidentellement des données entre les deux réseaux. Un exemple typique est l’accès simultané à un réseau privé virtuel (VPN) et à Internet. Windows Server 2003 et Windows XP utilisent un modèle d’hôte faible, où RAS empêche cet accès simultané en augmentant la métrique de routage de tous les itinéraires par défaut sur d’autres interfaces. Ainsi, tout le trafic est acheminé via l’interface VPN, ce qui interrompt la connectivité réseau.

Sur Windows Vista et versions ultérieures, un modèle d’hôte fort est utilisé par défaut. Si une adresse IP source est spécifiée dans la recherche d’itinéraire à l’aide de GetBestRoute2 ou GetBestRoute, la recherche d’itinéraire est limitée à l’interface de l’adresse IP source. La modification de la métrique d’itinéraire par RAS n’a aucun effet, car la liste des itinéraires potentiels n’a même pas l’itinéraire pour l’interface VPN permettant ainsi le trafic vers Internet. Le membre DisableDefaultRoutes du MIB_IPINTERFACE_ROW peut être utilisé pour désactiver l’utilisation de la route par défaut sur une interface. Ce membre peut être utilisé comme mesure de sécurité par les clients VPN pour restreindre le tunneling fractionné lorsque le tunneling fractionné n’est pas requis par le client VPN. Un client VPN peut appeler la fonction SetIpInterfaceEntry pour définir le membre DisableDefaultRoutes sur TRUE si nécessaire. Un client VPN peut interroger l’état actuel du membre DisableDefaultRoutes en appelant la fonction GetIpInterfaceEntry .

The

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

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 (inclure Iphlpapi.h)
Bibliothèque	Iphlpapi.lib
DLL	Iphlpapi.dll