GetPerTcpConnectionEStats-Funktion (iphlpapi.h)

Artikel
08/24/2023

Die GetPerTcpConnectionEStats-Funktion ruft erweiterte Statistiken für eine IPv4-TCP-Verbindung ab.

Syntax

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
);

Parameter

Row

Ein Zeiger auf eine MIB_TCPROW-Struktur für eine IPv4-TCP-Verbindung.

EstatsType

Der Typ der für TCP angeforderten erweiterten Statistiken. Dieser Parameter bestimmt die Daten und das Format der Informationen, die in den Parametern Rw, Rod und Ros zurückgegeben werden, wenn der Aufruf erfolgreich ist.

Dieser Parameter kann einer der Werte aus dem TCP_ESTATS_TYPE Enumerationstyp sein, der in der Headerdatei "Tcpestats.h " definiert ist.

Wert	Bedeutung
TcpConnectionEstatsSynOpts	Dieser Wert fordert den SYN-Austausch von Informationen für eine TCP-Verbindung an. Für diesen Enumerationswert sind nur schreibgeschützte statische Informationen verfügbar. Wenn der Ros-Parameter nicht NULL war und die Funktion erfolgreich ist, sollte der Puffer, auf den der Ros-Parameter verweist, eine TCP_ESTATS_SYN_OPTS_ROS_v0 Struktur enthalten.
TcpConnectionEstatsData	Dieser Wert fordert erweiterte Datenübertragungsinformationen für eine TCP-Verbindung an. Für diesen Enumerationswert sind nur schreibgeschützte dynamische Informationen und Lese-/Schreibinformationen verfügbar. Wenn der Rw-Parameter nicht NULL war und die Funktion erfolgreich ist, sollte der Puffer, auf den der Rw-Parameter verweist, eine TCP_ESTATS_DATA_RW_v0-Struktur enthalten. Wenn erweiterte Datenübertragungsinformationen für diese TCP-Verbindung aktiviert wurden, der Rod-Parameter nicht NULL war und die Funktion erfolgreich ist, sollte der Puffer, auf den der Rod-Parameter verweist, eine TCP_ESTATS_DATA_ROD_v0 Struktur enthalten.
TcpConnectionEstatsSndCong	Dieser Wert fordert eine Absenderüberlastung für eine TCP-Verbindung an. Alle drei Arten von Informationen (schreibgeschützte statische, schreibgeschützte dynamische Informationen und Lese-/Schreibinformationen) sind für diesen Enumerationswert verfügbar. Wenn der Rw-Parameter nicht NULL ist und die Funktion erfolgreich ist, sollte der Puffer, auf den der Rw-Parameter verweist, eine TCP_ESTATS_SND_CONG_RW_v0-Struktur enthalten. Wenn der Ros-Parameter nicht NULL ist und die Funktion erfolgreich ist, sollte der Puffer, auf den der Ros-Parameter verweist, eine TCP_ESTATS_SND_CONG_ROS_v0-Struktur enthalten. Wenn informationen zur Absenderüberlastung für diese TCP-Verbindung aktiviert wurden, der Rod-Parameter nicht NULL war und die Funktion erfolgreich ist, sollte der Puffer, auf den der Rod-Parameter verweist, eine TCP_ESTATS_SND_CONG_ROD_v0 Struktur enthalten.
TcpConnectionEstatsPath	Dieser Wert fordert informationen zur Messung erweiterter Pfade für eine TCP-Verbindung an. Für diesen Enumerationswert sind nur schreibgeschützte dynamische Informationen und Lese-/Schreibinformationen verfügbar. Wenn der Rw-Parameter nicht NULL war und die Funktion erfolgreich ist, sollte der Puffer, auf den der Rw-Parameter verweist, eine TCP_ESTATS_PATH_RW_v0-Struktur enthalten. Wenn erweiterte Pfadmessungsinformationen für diese TCP-Verbindung aktiviert wurden, der Rod-Parameter nicht NULL war und die Funktion erfolgreich ist, sollte der Puffer, auf den der Rod-Parameter verweist, eine TCP_ESTATS_PATH_ROD_v0-Struktur enthalten.
TcpConnectionEstatsSendBuff	Dieser Wert fordert erweiterte Ausgabewarteschlangeninformationen für eine TCP-Verbindung an. Für diesen Enumerationswert sind nur schreibgeschützte dynamische Informationen und Lese-/Schreibinformationen verfügbar. Wenn der Rw-Parameter nicht NULL ist und die Funktion erfolgreich ist, sollte der Puffer, auf den der Rw-Parameter verweist, eine TCP_ESTATS_SEND_BUFF_RW_v0-Struktur enthalten. Wenn erweiterte Ausgabewarteschlangeninformationen für diese TCP-Verbindung aktiviert wurden, der Rod-Parameter nicht NULL war und die Funktion erfolgreich ist, sollte der Puffer, auf den der Rod-Parameter verweist, eine TCP_ESTATS_SEND_BUFF_ROD_v0 Struktur enthalten.
TcpConnectionEstatsRec	Dieser Wert fordert erweiterte lokale Empfängerinformationen für eine TCP-Verbindung an. Für diesen Enumerationswert sind nur schreibgeschützte dynamische Informationen und Lese-/Schreibinformationen verfügbar. Wenn der Rw-Parameter nicht NULL ist und die Funktion erfolgreich ist, sollte der Puffer, auf den der Rw-Parameter verweist, eine TCP_ESTATS_REC_RW_v0-Struktur enthalten. Wenn erweiterte lokale Empfängerinformationen für diese TCP-Verbindung aktiviert wurden, der Rod-Parameter nicht NULL war und die Funktion erfolgreich ist, sollte der Puffer, auf den der Rod-Parameter verweist, eine TCP_ESTATS_REC_ROD_v0 Struktur enthalten.
TcpConnectionEstatsObsRec	Dieser Wert fordert erweiterte Remoteempfängerinformationen für eine TCP-Verbindung an. Für diesen Enumerationswert sind nur schreibgeschützte dynamische Informationen und Lese-/Schreibinformationen verfügbar. Wenn der Rw-Parameter nicht NULL ist und die Funktion erfolgreich ist, sollte der Puffer, auf den der Rw-Parameter verweist, eine TCP_ESTATS_OBS_REC_RW_v0-Struktur enthalten. Wenn erweiterte Remoteempfängerinformationen für diese TCP-Verbindung aktiviert wurden, der Rod-Parameter nicht NULL war und die Funktion erfolgreich ist, sollte der Puffer, auf den der Rod-Parameter verweist, eine TCP_ESTATS_OBS_REC_ROD_v0 Struktur enthalten.
TcpConnectionEstatsBandwidth	Dieser Wert fordert Bandbreitenschätzungsstatistiken für eine TCP-Verbindung auf Bandbreite an. Für diesen Enumerationswert sind nur schreibgeschützte dynamische Informationen und Lese-/Schreibinformationen verfügbar. Wenn der Rw-Parameter nicht NULL ist und die Funktion erfolgreich ist, sollte der Puffer, auf den der Rw-Parameter verweist, eine TCP_ESTATS_BANDWIDTH_RW_v0-Struktur enthalten. Wenn die Bandbreitenschätzungsstatistiken für diese TCP-Verbindung aktiviert wurden, der Rod-Parameter nicht NULL war und die Funktion erfolgreich ist, sollte der Puffer, auf den der Rod-Parameter verweist, eine TCP_ESTATS_BANDWIDTH_ROD_v0 Struktur enthalten.
TcpConnectionEstatsFineRtt	Dieser Wert fordert eine differenzierte RtT-Schätzungsstatistik (Roundtrip time) für eine TCP-Verbindung an. Für diesen Enumerationswert sind nur schreibgeschützte dynamische Informationen und Lese-/Schreibinformationen verfügbar. Wenn der Rw-Parameter nicht NULL ist und die Funktion erfolgreich ist, sollte der Puffer, auf den der Rw-Parameter verweist, eine TCP_ESTATS_FINE_RTT_RW_v0-Struktur enthalten. Wenn für diese TCP-Verbindung differenzierte RTT-Schätzstatistiken aktiviert wurden, der Rod-Parameter nicht NULL war und die Funktion erfolgreich ist, sollte der Puffer, auf den der Rod-Parameter verweist, eine TCP_ESTATS_FINE_RTT_ROD_v0-Struktur enthalten.

[out] Rw

Ein Zeiger auf einen Puffer zum Empfangen der Lese-/Schreibinformationen. Dieser Parameter kann ein NULL-Zeiger sein, wenn eine Anwendung keine Lese-/Schreibinformationen für die TCP-Verbindung abrufen möchte.

RwVersion

Die Version der angeforderten Lese-/Schreibinformationen. Der aktuell unterstützte Wert ist eine Version von null.

RwSize

Die Größe des Puffers in Bytes, auf den der Rw-Parameter verweist.

[out] Ros

Ein Zeiger auf einen Puffer zum Empfangen schreibgeschützter statischer Informationen. Dieser Parameter kann ein NULL-Zeiger sein, wenn eine Anwendung keine schreibgeschützten statischen Informationen für die TCP-Verbindung abrufen möchte.

RosVersion

Die Version der angeforderten schreibgeschützten statischen Informationen. Der aktuell unterstützte Wert ist eine Version von null.

RosSize

Die Größe des Puffers in Bytes, auf den der Ros-Parameter verweist.

[out] Rod

Ein Zeiger auf einen Puffer zum Empfangen schreibgeschützter dynamischer Informationen. Dieser Parameter kann ein NULL-Zeiger sein, wenn eine Anwendung keine schreibgeschützten dynamischen Informationen für die TCP-Verbindung abrufen möchte.

RodVersion

Die Version der angeforderten schreibgeschützten dynamischen Informationen. Der aktuell unterstützte Wert ist eine Version von null.

RodSize

Die Größe des Puffers in Bytes, auf den der Rod-Parameter verweist.

Rückgabewert

Wenn die Funktion erfolgreich ist, wird der Rückgabewert NO_ERROR.

Wenn die Funktion fehlschlägt, ist der Rückgabewert einer der folgenden Fehlercodes.

Rückgabecode	Beschreibung
ERROR_INSUFFICIENT_BUFFER	Ein an eine Funktion übergebener Puffer ist zu klein. Dieser Fehler wird zurückgegeben, wenn der Puffer, auf den die Parameter Rw, Ros oder Rod verweisen, nicht groß genug ist, um die Daten zu empfangen. Dieser Fehler wird auch zurückgegeben, wenn einer der angegebenen Puffer, auf die durch die Parameter Rw, Ros oder Rod verwiesen wird, NULL ist, aber in der zugeordneten RwSize-, RosSize- oder RodSize-Datei eine Länge angegeben wurde. Dieser Fehlerwert wird unter Windows Vista und Windows Server 2008 zurückgegeben.
ERROR_INVALID_PARAMETER	„Der Parameter ist falsch.“ Dieser Fehler wird zurückgegeben, wenn der Row-Parameter ein NULL-Zeiger ist.
ERROR_INVALID_USER_BUFFER	Der angegebene Benutzerpuffer ist für den angeforderten Vorgang ungültig. Dieser Fehler wird zurückgegeben, wenn einer der angegebenen Puffer, auf die durch die Parameter Rw, Ros oder Rod verwiesen wird, NULL ist, aber eine Länge in der zugeordneten RwSize-, RosSize- oder RodSize-Datei angegeben wurde. Daher wird dieser Fehler zurückgegeben, wenn eine der folgenden Bedingungen erfüllt ist: Der Row-Parameter ist ein NULL-Zeiger , und der RwSize-Parameter ist ungleich null. Der Ros-Parameter ist ein NULL-Zeiger , und der RosSize-Parameter ist ungleich null. Der Rod-Parameter ist ein NULL-Zeiger , und der RodSize-Parameter ist ungleich null. Dieser Fehlerwert wird unter Windows 7 und Windows Server 2008 R2 zurückgegeben.
ERROR_NOT_FOUND	Dieser angeforderte Eintrag wurde nicht gefunden. Dieser Fehler wird zurückgegeben, wenn die im Row-Parameter angegebene TCP-Verbindung nicht gefunden werden konnte.
ERROR_NOT_SUPPORTED	Die Anforderung wird nicht unterstützt. Dieser Fehler wird zurückgegeben, wenn der RwVersion-, RosVersion- oder RodVersion-Parameter nicht auf 0 festgelegt ist.
Andere	Verwenden Sie FormatMessage , um die Nachrichtenzeichenfolge für den zurückgegebenen Fehler abzurufen.

Hinweise

Die GetPerTcpConnectionEStats-Funktion wird unter Windows Vista und höher definiert.

Die GetPerTcpConnectionEStats-Funktion ist für die Verwendung von TCP zur Diagnose von Leistungsproblemen im Netzwerk und in der Anwendung konzipiert. Wenn eine netzwerkbasierte Anwendung eine schlechte Leistung aufweist, kann TCP ermitteln, ob der Engpass im Absender, im Empfänger oder im Netzwerk selbst liegt. Wenn sich der Engpass im Netzwerk befindet, kann TCP spezifische Informationen zu seiner Art bereitstellen.

Die GetPerTcpConnectionEStats-Funktion ruft erweiterte Statistiken für die im Row-Parameter übergebene IPv4-TCP-Verbindung ab. Der Typ der abgerufenen erweiterten Statistiken wird im Parameter EstatsType angegeben. Erweiterte Statistiken für diese TCP-Verbindung müssen zuvor durch Aufrufe der SetPerTcpConnectionEStats-Funktion für alle TCP_ESTATS_TYPE Werte aktiviert worden sein, außer wenn TcpConnectionEstatsSynOpts im EstatsType-Parameter übergeben wird.

Die GetTcpTable-Funktion wird verwendet, um die IPv4-TCP-Verbindungstabelle auf dem lokalen Computer abzurufen. Diese Funktion gibt eine MIB_TCPTABLE-Struktur zurück, die ein Array von MIB_TCPROW Einträgen enthält. Der An die GetPerTcpConnectionEStats-Funktion übergebene Row-Parameter muss ein Eintrag für eine vorhandene IPv4-TCP-Verbindung sein.

Die einzige unterstützte Version der TCP-Verbindungsstatistik ist Version 0. Daher sollten die an GetPerTcpConnectionEStats übergebenen Parameter RwVersion, RosVersion und RodVersion auf 0 festgelegt werden.

Informationen zu erweiterten TCP-Statistiken für eine IPv6-Verbindung finden Sie in den Funktionen GetPerTcp6ConnectionEStats und SetPerTcp6ConnectionEStats .

Die SetPerTcpConnectionEStats-Funktion kann nur von einem Benutzer aufgerufen werden, der als Mitglied der Gruppe Administratoren angemeldet ist. Wenn SetPerTcpConnectionEStats von einem Benutzer aufgerufen wird, der kein Mitglied der Gruppe Administratoren ist, schlägt der Funktionsaufruf fehl, und ERROR_ACCESS_DENIED wird zurückgegeben. Diese Funktion kann auch aufgrund der Benutzerkontensteuerung (User Account Control, UAC) unter Windows Vista und höher fehlschlagen. Wenn eine Anwendung, die diese Funktion enthält, von einem Benutzer ausgeführt wird, der nicht als mitglied der Gruppe Administratoren als der integrierte Administrator angemeldet ist, schlägt dieser Aufruf fehl, es sei denn, die Anwendung wurde in der Manifestdatei mit einem requestedExecutionLevel-Wert gekennzeichnet, der auf requireAdministrator festgelegt ist. Wenn der Anwendung diese Manifestdatei fehlt, muss ein Benutzer, der sich als anderes Mitglied der Administratorgruppe als der integrierte Administrator angemeldet hat, die Anwendung dann in einer erweiterten Shell als integrierter Administrator (RunAs-Administrator) ausführen, damit diese Funktion erfolgreich ist.

Der Aufrufer von GetPerTcpConnectionEStats sollte das Feld EnableCollection in der zurückgegebenen Rw-Struktur überprüfen, und wenn es nicht TRUEist, sollte der Aufrufer die Daten in den Ros - und Rod-Strukturen ignorieren. Wenn EnableCollection auf FALSEfestgelegt ist, sind die in Ros und Rod zurückgegebenen Daten nicht definiert. Dies kann beispielsweise vorkommen, wenn Sie GetPerTcpConnectionEStats verwenden, um erweiterte Statistiken für eine IPv4-TCP-Verbindung abzurufen, und Sie haben zuvor SetPerTcpConnectionEStats aufgerufen, um erweiterte Statistiken zu aktivieren. Wenn der SetPerTcpConnectionEStats-Aufruf fehlschlägt , geben nachfolgende Aufrufe von GetPerTcpConnectionEStats bedeutungslose zufällige Daten und keine erweiterten TCP-Statistiken zurück. Sie können dieses Beispiel beobachten, indem Sie das folgende Beispiel sowohl als Administrator als auch als normaler Benutzer ausführen.

Beispiele

Ein Codebeispiel finden Sie im Abschnitt Beispiele im Thema GetPerTcp6ConnectionEStats-Funktion .

Anforderungen


Unterstützte Mindestversion (Client)	Windows Vista [nur Desktop-Apps]
Unterstützte Mindestversion (Server)	Windows Server 2008 [nur Desktop-Apps]
Zielplattform	Windows
Kopfzeile	iphlpapi.h
Bibliothek	Iphlpapi.lib
DLL	Iphlpapi.dll