Fonction GetPerTcpConnectionEStats (iphlpapi.h)

Article
08/24/2023

La fonction GetPerTcpConnectionEStats récupère des statistiques étendues pour une connexion TCP IPv4.

Syntaxe

IPHLPAPI_DLL_LINKAGE ULONG GetPerTcpConnectionEStats(
        PMIB_TCPROW     Row,
        TCP_ESTATS_TYPE EstatsType,
  [out] PUCHAR          Rw,
        ULONG           RwVersion,
        ULONG           RwSize,
  [out] PUCHAR          Ros,
        ULONG           RosVersion,
        ULONG           RosSize,
  [out] PUCHAR          Rod,
        ULONG           RodVersion,
        ULONG           RodSize
);

Paramètres

Row

Pointeur vers une structure MIB_TCPROW pour une connexion TCP IPv4.

EstatsType

Type de statistiques étendues pour TCP demandé. Ce paramètre détermine les données et le format des informations retournées dans les paramètres Rw, Rod et Ros si l’appel réussit.

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 .

Valeur	Signification
TcpConnectionEstatsSynOpts	Cette valeur demande des informations d’échange SYN pour une connexion TCP. Seules les informations statiques en lecture seule sont disponibles pour cette valeur d’énumération. Si le paramètre Ros n’était pas NULL et que la fonction réussit, la mémoire tampon pointée par le paramètre Ros doit contenir une structure TCP_ESTATS_SYN_OPTS_ROS_v0 .
TcpConnectionEstatsData	Cette valeur demande des informations de transfert de données étendues pour une connexion TCP. Seules les informations dynamiques en lecture seule et les informations de lecture/écriture sont disponibles pour cette valeur d’énumération. Si le paramètre Rw n’était pas NULL et que la fonction réussit, la mémoire tampon pointée par le paramètre Rw doit contenir une structure TCP_ESTATS_DATA_RW_v0 . Si des informations de transfert de données étendues ont été activées pour cette connexion TCP, que le paramètre Rod n’était pas NULL et que la fonction réussit, la mémoire tampon vers laquelle pointe le paramètre Rod doit contenir une structure TCP_ESTATS_DATA_ROD_v0 .
TcpConnectionEstatsSndCong	Cette valeur demande une congestion de l’expéditeur pour une connexion TCP. Les trois types d’informations (statiques en lecture seule, dynamiques en lecture seule et informations en lecture/écriture) sont disponibles pour cette valeur d’énumération. Si le paramètre Rw n’était pas NULL et que la fonction réussit, la mémoire tampon pointée par le paramètre Rw doit contenir une structure TCP_ESTATS_SND_CONG_RW_v0 . Si le paramètre Ros n’était pas NULL et que la fonction réussit, la mémoire tampon pointée par le paramètre Ros doit contenir une structure TCP_ESTATS_SND_CONG_ROS_v0 . Si les informations de congestion de l’expéditeur ont été activées pour cette connexion TCP, que le paramètre Rod n’était pas NULL et que la fonction réussit, la mémoire tampon pointée par le paramètre Rod doit contenir une structure TCP_ESTATS_SND_CONG_ROD_v0 .
TcpConnectionEstatsPath	Cette valeur demande des informations de mesure de chemin étendues pour une connexion TCP. Seules les informations dynamiques en lecture seule et les informations de lecture/écriture sont disponibles pour cette valeur d’énumération. Si le paramètre Rw n’était pas NULL et que la fonction réussit, la mémoire tampon pointée par le paramètre Rw doit contenir une structure TCP_ESTATS_PATH_RW_v0 . Si les informations de mesure de chemin étendu ont été activées pour cette connexion TCP, que le paramètre Rod n’était pas NULL et que la fonction réussit, la mémoire tampon vers laquelle pointe le paramètre Rod doit contenir une structure TCP_ESTATS_PATH_ROD_v0 .
TcpConnectionEstatsSendBuff	Cette valeur demande des informations de mise en file d’attente de sortie étendues pour une connexion TCP. Seules les informations dynamiques en lecture seule et les informations de lecture/écriture sont disponibles pour cette valeur d’énumération. Si le paramètre Rw n’était pas NULL et que la fonction réussit, la mémoire tampon pointée par le paramètre Rw doit contenir une structure TCP_ESTATS_SEND_BUFF_RW_v0 . Si les informations de mise en file d’attente de sortie étendues ont été activées pour cette connexion TCP, le paramètre Rod n’était pas NULL et la fonction réussit, la mémoire tampon vers laquelle pointe le paramètre Rod doit contenir une structure TCP_ESTATS_SEND_BUFF_ROD_v0 .
TcpConnectionEstatsRec	Cette valeur demande des informations de récepteur local étendues pour une connexion TCP. Seules les informations dynamiques en lecture seule et les informations de lecture/écriture sont disponibles pour cette valeur d’énumération. Si le paramètre Rw n’était pas NULL et que la fonction réussit, la mémoire tampon pointée par le paramètre Rw doit contenir une structure TCP_ESTATS_REC_RW_v0 . Si les informations étendues du récepteur local ont été activées pour cette connexion TCP, le paramètre Rod n’était pas NULL et la fonction réussit, la mémoire tampon vers laquelle pointe le paramètre Rod doit contenir une structure TCP_ESTATS_REC_ROD_v0 .
TcpConnectionEstatsObsRec	Cette valeur demande des informations étendues sur le récepteur distant pour une connexion TCP. Seules les informations dynamiques en lecture seule et les informations de lecture/écriture sont disponibles pour cette valeur d’énumération. Si le paramètre Rw n’était pas NULL et que la fonction réussit, la mémoire tampon pointée par le paramètre Rw doit contenir une structure TCP_ESTATS_OBS_REC_RW_v0 . Si les informations étendues du récepteur distant ont été activées pour cette connexion TCP, que le paramètre Rod n’était pas NULL et que la fonction réussit, la mémoire tampon pointée par le paramètre Rod doit contenir une structure TCP_ESTATS_OBS_REC_ROD_v0 .
TcpConnectionEstatsBandwidth	Cette valeur demande des statistiques d’estimation de la bande passante pour une connexion TCP sur la bande passante. Seules les informations dynamiques en lecture seule et les informations de lecture/écriture sont disponibles pour cette valeur d’énumération. Si le paramètre Rw n’était pas NULL et que la fonction réussit, la mémoire tampon pointée par le paramètre Rw doit contenir une structure TCP_ESTATS_BANDWIDTH_RW_v0 . Si les statistiques d’estimation de bande passante ont été activées pour cette connexion TCP, le paramètre Rod n’était pas NULL et la fonction réussit, la mémoire tampon pointée par le paramètre Rod doit contenir une structure TCP_ESTATS_BANDWIDTH_ROD_v0 .
TcpConnectionEstatsFineRtt	Cette valeur demande des statistiques d’estimation précises du temps d’aller-retour (RTT) pour une connexion TCP. Seules les informations dynamiques en lecture seule et les informations de lecture/écriture sont disponibles pour cette valeur d’énumération. Si le paramètre Rw n’était pas NULL et que la fonction réussit, la mémoire tampon pointée par le paramètre Rw doit contenir une structure TCP_ESTATS_FINE_RTT_RW_v0 . Si des statistiques d’estimation RTT affinées ont été activées pour cette connexion TCP, le paramètre Rod n’était pas NULL et la fonction réussit, la mémoire tampon vers laquelle pointe le paramètre Rod doit contenir une structure TCP_ESTATS_FINE_RTT_ROD_v0 .

[out] Rw

Pointeur vers une mémoire tampon pour recevoir les informations de lecture/écriture. Ce paramètre peut être un pointeur NULL si une application ne souhaite pas récupérer les informations de lecture/écriture pour la connexion TCP.

RwVersion

Version des informations de lecture/écriture demandées. La valeur actuelle prise en charge est une version de zéro.

RwSize

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

[out] Ros

Pointeur vers une mémoire tampon pour recevoir des informations statiques en lecture seule. Ce paramètre peut être un pointeur NULL si une application ne souhaite pas récupérer des informations statiques en lecture seule pour la connexion TCP.

RosVersion

Version des informations statiques en lecture seule demandées. La valeur actuelle prise en charge est une version de zéro.

RosSize

Taille, en octets, de la mémoire tampon pointée par le paramètre Ros .

[out] Rod

Pointeur vers une mémoire tampon pour recevoir des informations dynamiques en lecture seule. Ce paramètre peut être un pointeur NULL si une application ne souhaite pas récupérer des informations dynamiques en lecture seule pour la connexion TCP.

RodVersion

Version des informations dynamiques en lecture seule demandées. La valeur actuelle prise en charge est une version de zéro.

RodSize

Taille, en octets, de la mémoire tampon pointée par le paramètre Rod .

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_INSUFFICIENT_BUFFER	Une mémoire tampon passée à une fonction est trop petite. Cette erreur est retournée si la mémoire tampon pointée vers par les paramètres Rw, Ros ou Rod n’est pas suffisamment grande pour recevoir les données. Cette erreur s’est également retournée si l’une des mémoires tampons spécifiées pointées par les paramètres Rw, Ros ou Rod a la valeur NULL, mais qu’une longueur a été spécifiée dans le RwSize, RosSize ou RodSize associé. Cette valeur d’erreur est retournée sur Windows Vista et Windows Server 2008.
ERROR_INVALID_PARAMETER	Le paramètre est incorrect. Cette erreur est retournée si le paramètre Row est un pointeur NULL .
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 l’une des mémoires tampons spécifiées pointées par les paramètres Rw, Ros ou Rod a la valeur NULL, mais qu’une longueur a été spécifiée dans le RwSize, RosSize ou RodSize associé. Par conséquent, cette erreur est retournée si l’une des conditions suivantes est remplie : Le paramètre Row est un pointeur NULL et le paramètre RwSize est différent de zéro. Le paramètre Ros est un pointeur NULL et le paramètre RosSize est différent de zéro. Le paramètre Rod est un pointeur NULL et le paramètre RodSize est différent de zéro. Cette valeur d’erreur est retournée sur Windows 7 et Windows Server 2008 R2.
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, RosVersion ou RodVersion n’est pas défini sur zéro.
Autres	Utilisez FormatMessage pour obtenir la chaîne de message pour l’erreur retournée.

Notes

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

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 destinataire 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.

La fonction GetPerTcpConnectionEStats récupère des statistiques étendues pour la connexion TCP IPv4 transmise dans le paramètre Row . Le type de statistiques étendues récupérées est spécifié dans le paramètre EstatsType . Les statistiques étendues sur cette connexion TCP doivent avoir déjà été activées par les appels à la fonction SetPerTcpConnectionEStats pour toutes les valeurs TCP_ESTATS_TYPE , sauf lorsque TcpConnectionEstatsSynOpts est passé dans le paramètre EstatsType .

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 GetPerTcpConnectionEStats doit être une entrée pour une connexion TCP IPv4 existante.

La seule version des statistiques de connexion TCP actuellement prise en charge est la version zéro. Par conséquent, les paramètres RwVersion, RosVersion et RodVersion passés à GetPerTcpConnectionEStats doivent être définis sur 0.

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 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.

L’appelant de GetPerTcpConnectionEStats doit case activée le champ EnableCollection dans le struct Rw retourné, et s’il n’est pas TRUE, l’appelant doit ignorer les données dans les structs Ros et Rod. Si EnableCollection a la FALSEvaleur , les données retournées dans Ros et Rod ne sont pas définies. Par exemple, une condition dans laquelle cela peut se produire est lorsque vous utilisez GetPerTcpConnectionEStats pour récupérer des statistiques étendues pour une connexion TCP IPv4, et que vous avez précédemment appelé SetPerTcpConnectionEStats pour activer les statistiques étendues . Si l’appel SetPerTcpConnectionEStats échoue, les appels suivants à GetPerTcpConnectionEStats retournent des données aléatoires sans signification, et non des statistiques TCP étendues. Vous pouvez observer cet exemple en exécutant l’exemple ci-dessous en tant qu’administrateur et en tant qu’utilisateur normal.

Exemples

Pour obtenir un exemple de code, consultez la section Exemples dans la rubrique de la fonction GetPerTcp6ConnectionEStats .

Spécifications


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