SetUnicastIpAddressEntry, fonction (netioapi.h)
La fonction SetUnicastIpAddressEntry définit les propriétés d’une entrée d’adresse IP de monodiffusion existante sur l’ordinateur local.
Syntaxe
IPHLPAPI_DLL_LINKAGE _NETIOAPI_SUCCESS_ NETIOAPI_API SetUnicastIpAddressEntry(
[in] const MIB_UNICASTIPADDRESS_ROW *Row
);
Paramètres
[in] Row
Pointeur vers une entrée de structure MIB_UNICASTIPADDRESS_ROW pour une entrée d’adresse IP de monodiffusion existante.
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 |
|---|---|
|
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). |
|
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 Row , si le membre Address du MIB_UNICASTIPADDRESS_ROW pointé par le paramètre Row n’a pas été défini sur une adresse IPv4 ou IPv6 de monodiffusion valide, ou si les membres InterfaceLuid ou InterfaceIndex du MIB_UNICASTIPADDRESS_ROW pointés par le paramètre Row n’ont pas été spécifiés.
Cette erreur est également retournée pour d’autres erreurs dans les valeurs définies pour les membres de la structure MIB_UNICASTIPADDRESS_ROW . Ces erreurs sont les suivantes : si le membre ValidLifetime est inférieur au membre PreferredLifetime , si le membre PrefixOrigin est défini sur IpPrefixOriginUnchanged et que SuffixOrigin n’est pas défini sur IpSuffixOriginUnchanged, si le membre PrefixOrigin n’est pas défini sur IpPrefixOriginUnchanged et que SuffixOrigin est défini sur IpSuffixOriginUnchanged, si prefixOriginUnchanged le membre n’est pas défini sur une valeur de l’énumération NL_PREFIX_ORIGIN , si le membre SuffixOrigin n’est pas défini sur une valeur de l’énumération NL_SUFFIX_ORIGIN , ou si le membre OnLinkPrefixLength est défini sur une valeur supérieure à la longueur de l’adresse IP, en bits (32 pour une adresse IPv4 en monodiffusion ou 128 pour une adresse IPv6 monodiffusion). |
|
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_UNICASTIPADDRESS_ROW pointé par le paramètre Row est introuvable. |
|
La demande n'est pas prise en charge. Cette erreur est retournée si aucune pile IPv4 ne se trouve sur l’ordinateur local et si une adresse IPv4 a été spécifiée dans le membre AddressMIB_UNICASTIPADDRESS_ROW pointé par le paramètre Ligne ou si aucune pile IPv6 ne se trouve sur l’ordinateur local et qu’une adresse IPv6 a été spécifiée dans le membre Address . |
|
Utilisez FormatMessage pour obtenir la chaîne de message de l’erreur retournée. |
Remarques
La fonction SetUnicastIpAddressEntry est définie sur Windows Vista et versions ultérieures.
La fonction GetUnicastIpAddressEntry est normalement utilisée pour récupérer une entrée de structure MIB_UNICASTIPADDRESS_ROW existante à modifier. Une application peut ensuite modifier les membres de l’entrée MIB_UNICASTIPADDRESS_ROW qu’elle souhaite modifier, puis appeler la fonction SetUnicastIpAddressEntry .
Une application peut appeler la fonction InitializeUnicastIpAddressEntry pour initialiser les membres d’une entrée de structure MIB_UNICASTIPADDRESS_ROW avec des valeurs par défaut avant d’apporter des modifications. Toutefois, l’application enregistre normalement le membre InterfaceLuid ou InterfaceIndex avant d’appeler InitializeUnicastIpAddressEntry et restaure l’un de ces membres après l’appel.
Le membre Address dans la structure MIB_UNICASTIPADDRESS_ROW pointée vers le paramètre Row doit être initialisé vers une adresse IPv4 ou IPv6 et une famille de monodiffusion valides. En outre, au moins un des membres suivants dans la structure MIB_UNICASTIPADDRESS_ROW pointant vers le paramètre Row doit être initialisé : InterfaceLuid ou InterfaceIndex.
Les champs sont utilisés dans l’ordre indiqué ci-dessus. Ainsi, si l’InterfaceLuid est spécifié, 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.
Si le membre OnLinkPrefixLength du MIB_UNICASTIPADDRESS_ROW pointé par le paramètre Row est défini sur 255, SetUnicastIpAddressEntry définit les propriétés d’adresse IP de monodiffusion de sorte que le membre OnLinkPrefixLength soit égal à la longueur de l’adresse IP. Par conséquent, pour une adresse IPv4 en monodiffusion, OnLinkPrefixLength a la valeur 32 et OnLinkPrefixLength est défini sur 128 pour une adresse IPv6 en monodiffusion. Si cela entraîne un masque de sous-réseau incorrect pour une adresse IPv4 ou un préfixe de lien incorrect pour une adresse IPv6, l’application doit définir ce membre sur la valeur correcte avant d’appeler SetUnicastIpAddressEntry.
Les membres DadState, ScopeId et CreationTimeStamp de la structure MIB_UNICASTIPADDRESS_ROW pointée par la ligne sont ignorés lorsque la fonction SetUnicastIpAddressEntry 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 SetUnicastIpAddressEntry . Le membre ScopeId est automatiquement déterminé par l’interface sur laquelle l’adresse a été ajoutée.
La fonction SetUnicastIpAddressEntry ne peut être appelée que par un utilisateur connecté en tant que membre du groupe Administrateurs. Si SetUnicastIpAddressEntry 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 SetUnicastIpAddressEntry 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 |
Voir aussi
Informations de référence sur les fonctions d’assistance IP