SetIpStatisticsEx, fonction (iphlpapi.h)

Article
08/24/2023

La fonction SetIpStatisticsEx active ou désactive le transfert IP et définit la valeur de durée de vie (TTL) par défaut pour l’ordinateur local.

Syntaxe

IPHLPAPI_DLL_LINKAGE ULONG SetIpStatisticsEx(
  [in] PMIB_IPSTATS Statistics,
       ULONG        Family
);

Paramètres

[in] Statistics

Pointeur vers une structure MIB_IPSTATS . L’appelant doit définir les membres dwForwarding et dwDefaultTTL de cette structure sur les nouvelles valeurs. Pour conserver l’un des membres à sa valeur actuelle, utilisez MIB_USE_CURRENT_TTL ou MIB_USE_CURRENT_FORWARDING.

Family

Famille d’adresses pour laquelle le transfert et la durée de vie doivent être définis.

Les valeurs possibles pour la famille d’adresses sont répertoriées dans le fichier d’en-tête Winsock2.h . Notez que les valeurs de la famille d’adresses AF_ et des constantes de famille de protocole PF_ sont identiques (par exemple , AF_INET et PF_INET), de sorte que l’une ou l’autre constante peut être utilisée.

Sur le Kit de développement logiciel (SDK) Windows publié pour Windows Vista et versions ultérieures, la organization des fichiers d’en-tête a changé et les valeurs possibles pour ce membre sont définies dans le fichier d’en-tête Ws2def.h. Notez que le fichier d’en-tête Ws2def.h est automatiquement inclus dans Winsock2.h et ne doit jamais être utilisé directement.

Les valeurs actuellement prises en charge sont AF_INET et AF_INET6.

Valeur	Signification
AF_INET 2	Famille d’adresses IPv4 (Internet Protocol version 4). Lorsque ce paramètre est spécifié, cette fonction définit les options de transfert et de durée de vie pour les entrées IPv4.
AF_INET6 23	Famille d’adresses IPv6 (Internet Protocol version 6). Lorsque ce paramètre est spécifié, cette fonction définit les options de transfert et de durée de vie pour les entrées IPv6.

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	Accès 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 pIpStats ou si le paramètre Family n’a pas été défini sur AF_INET et AF_INET6. Cette erreur est également retournée si le membre dwForwarding dans la structure MIB_IPSTATS pointée par le paramètre pIpStats contient une valeur autre que MIB_IP_NOT_FORWARDING, MIB_IP_FORWARDING ou MIB_USE_CURRENT_FORWARDING.
ERROR_NOT_SUPPORTED	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 AF_INET a été spécifié dans le paramètre Family ou si aucune pile IPv6 ne se trouve sur l’ordinateur local et AF_INET6 a été spécifié dans le membre Family .
Autres	Utilisez FormatMessage pour obtenir la chaîne de message de l’erreur retournée.

Notes

Pour définir uniquement la durée de vie par défaut, l’appelant peut également utiliser la fonction SetIpTTL .

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

Spécifications


Client minimal pris en charge	Windows Vista [applications de bureau uniquement]
Serveur minimal pris en charge	Windows Server 2003 [applications de bureau uniquement]
Plateforme cible	Windows
En-tête	iphlpapi.h
Bibliothèque	Iphlpapi.lib
DLL	Iphlpapi.dll