SetPerTcpConnectionEStats, fonction (iphlpapi.h)

Article
03/14/2023

La fonction SetPerTcpConnectionEStats définit une valeur dans les informations de lecture/écriture pour une connexion TCP IPv4. Cette fonction est utilisée pour activer ou désactiver des statistiques étendues pour une connexion TCP IPv4.

Syntaxe

IPHLPAPI_DLL_LINKAGE ULONG SetPerTcpConnectionEStats(
  PMIB_TCPROW     Row,
  TCP_ESTATS_TYPE EstatsType,
  PUCHAR          Rw,
  ULONG           RwVersion,
  ULONG           RwSize,
  ULONG           Offset
);

Paramètres

Row

Pointeur vers une structure MIB_TCPROW pour une connexion TCP IPv4.

EstatsType

Type de statistiques étendues que TCP doit définir. Ce paramètre détermine les données et le format des informations attendues dans le paramètre Rw .

Ce paramètre peut être l’une des valeurs du type d’énumération TCP_ESTATS_TYPE défini dans le fichier d’en-tête Tcpestats.h .

Rw

Pointeur vers une mémoire tampon qui contient les informations de lecture/écriture à définir. La mémoire tampon doit contenir une valeur de l’énumération TCP_BOOLEAN_OPTIONAL pour chaque membre de structure qui spécifie comment chaque membre doit être mis à jour.

RwVersion

Version des informations de lecture/écriture à définir. Ce paramètre doit être défini sur zéro pour Windows Vista, Windows Server 2008 et Windows 7.

RwSize

Taille, en octets, de la mémoire tampon vers laquelle pointe le paramètre Rw .

Offset

Décalage, en octets, du membre dans la structure vers lequel pointe le paramètre Rw à définir. Ce paramètre n’est actuellement pas utilisé et doit être défini sur zéro.

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_USER_BUFFER	La mémoire tampon utilisateur fournie n’est pas valide pour l’opération demandée. Cette erreur est retournée si le paramètre Row est un pointeur NULL et si le paramètre RwSize est différent de zéro.
ERROR_INVALID_PARAMETER	Le paramètre est incorrect. Cette erreur est retournée si le paramètre Row est un pointeur NULL .
ERROR_NOT_FOUND	Cette entrée demandée est introuvable. Cette erreur est retournée si la connexion TCP spécifiée dans le paramètre Row est introuvable.
ERROR_NOT_SUPPORTED	La demande n'est pas prise en charge. Cette erreur est retournée si le paramètre RwVersion ou Offset n’est pas défini sur 0.
Autres	Utilisez FormatMessage pour obtenir la chaîne de message de l’erreur retournée.

Remarques

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

La fonction SetPerTcpConnectionEStats permet d’activer ou de désactiver des statistiques étendues sur une connexion TCP IPv4 passée dans le paramètre Row . Les statistiques étendues sur une connexion TCP sont désactivées par défaut. La fonction SetPerTcpConnectionEStats permet de définir la valeur d’un membre dans les informations de lecture/écriture pour les statistiques étendues d’une connexion TCP IPv4. Le type et le format de la structure à définir sont spécifiés par le paramètre EstatsType . Le paramètre Rw contient un pointeur vers la structure passée. Tous les membres de la structure pointés vers par le paramètre Rw doivent être spécifiés.

La seule version des statistiques de connexion TCP actuellement prise en charge est la version zéro. Par conséquent, le paramètre RwVersion passé à SetPerTcpConnectionEStats doit être défini sur 0.

La structure vers laquelle pointe le paramètre Rw passé cette fonction dépend de la valeur d’énumération passée dans le paramètre EstatsType . Le tableau suivant indique le type de structure qui doit être passé dans le paramètre Rw pour chaque type de paramètre EstatsType possible.

EstatsType	Structure pointée par Rw
TcpConnectionEstatsData	TCP_ESTATS_DATA_RW_v0
TcpConnectionEstatsSndCong	TCP_ESTATS_SND_CONG_RW_v0
TcpConnectionEstatsPath	TCP_ESTATS_PATH_RW_v0
TcpConnectionEstatsSendBuff	TCP_ESTATS_SEND_BUFF_RW_v0
TcpConnectionEstatsRec	TCP_ESTATS_REC_RW_v0
TcpConnectionEstatsObsRec	TCP_ESTATS_OBS_REC_RW_v0
TcpConnectionEstatsBandwidth	TCP_ESTATS_BANDWIDTH_RW_v0
TcpConnectionEstatsFineRtt	TCP_ESTATS_FINE_RTT_RW_v0

Le paramètre Offset est actuellement inutilisé et doit être défini sur 0. Les structures possibles pointées par le paramètre Rw ont toutes un seul membre à l’exception de la structure TCP_ESTATS_BANDWIDTH_RW_v0 . Lorsque le paramètre EstatsType est défini sur TcpConnectionEstatsBandwidth, la structure TCP_ESTATS_BANDWIDTH_RW_v0 pointée par le paramètre Rw doit avoir les deux membres de structure définis sur les valeurs préférées dans un seul appel à la fonction SetPerTcpConnectionEStats .

Si le paramètre RwSize a la valeur 0, la fonction SetPerTcpConnectionEStats retourne NO_ERROR et n’apporte aucune modification à la status de statistiques étendues.

La fonction GetTcpTable est utilisée pour récupérer la table de connexion TCP IPv4 sur l’ordinateur local. Cette fonction retourne une structure MIB_TCPTABLE qui contient un tableau d’entrées MIB_TCPROW . Le paramètre Row passé à la fonction SetPerTcpConnectionEStats doit être une entrée pour une connexion TCP IPv4 existante.

Une fois les statistiques étendues activées sur une connexion TCP pour IPv4, les applications appellent la fonction GetPerTcpConnectionEStats pour récupérer les statistiques étendues sur la connexion TCP.

La fonction GetPerTcpConnectionEStats est conçue pour utiliser TCP pour diagnostiquer les problèmes de performances dans le réseau et l’application. Si une application réseau fonctionne mal, TCP peut déterminer si le goulot d’étranglement se trouve dans l’expéditeur, le récepteur ou le réseau lui-même. Si le goulot d’étranglement se trouve dans le réseau, TCP peut fournir des informations spécifiques sur sa nature.

Pour plus d’informations sur les statistiques TCP étendues sur une connexion IPv6, consultez les fonctions GetPerTcp6ConnectionEStats et SetPerTcp6ConnectionEStats .

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

Dans les versions de Windows antérieures à Windows 10, version 1709 (Fall Creators Update), vous pouvez utiliser SetPerTcpConnectionEStats pour désactiver et réactiver les statistiques sur une connexion, ce qui entraîne la réinitialisation des compteurs de statistiques à zéro. Depuis Windows 10, version 1709 (Fall Creators Update), certains compteurs de statistiques ne se réinitialisent pas lorsque les statistiques sont désactivées et réactivées. En outre, si deux applications surveillent les statistiques pour la même connexion, une application peut confondre l’autre en désactivant les statistiques. Pour ces raisons, nous vous recommandons de ne pas désactiver les statistiques sur les connexions. Pour détecter les modifications au fil du temps, vous devez enregistrer les valeurs de compteur lues par un appel précédent à GetPerTcpConnectionEStats et les soustraire de celles lues par un appel suivant.

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