SetPerTcpConnectionEStats-Funktion (iphlpapi.h)
Die SetPerTcpConnectionEStats-Funktion legt einen Wert in den Lese-/Schreibinformationen für eine IPv4-TCP-Verbindung fest. Diese Funktion wird verwendet, um erweiterte Statistiken für eine IPv4-TCP-Verbindung zu aktivieren oder zu deaktivieren.
Syntax
IPHLPAPI_DLL_LINKAGE ULONG SetPerTcpConnectionEStats(
PMIB_TCPROW Row,
TCP_ESTATS_TYPE EstatsType,
PUCHAR Rw,
ULONG RwVersion,
ULONG RwSize,
ULONG Offset
);
Parameter
Row
Ein Zeiger auf eine MIB_TCPROW-Struktur für eine IPv4-TCP-Verbindung.
EstatsType
Der Typ der erweiterten Statistiken, die für TCP festgelegt werden sollen. Dieser Parameter bestimmt die Daten und das Format der Informationen, die im Rw-Parameter erwartet werden.
Dieser Parameter kann einer der Werte aus dem TCP_ESTATS_TYPE Enumerationstyp sein, der in der Tcpestats.h-Headerdatei definiert ist.
Rw
Ein Zeiger auf einen Puffer, der die festzulegenden Lese-/Schreibinformationen enthält. Der Puffer sollte einen Wert aus der TCP_BOOLEAN_OPTIONAL-Enumeration für jedes Strukturmember enthalten, der angibt, wie die einzelnen Member aktualisiert werden sollen.
RwVersion
Die Version der festzulegenden Lese-/Schreibinformationen. Dieser Parameter sollte für Windows Vista, Windows Server 2008 und Windows 7 auf Null festgelegt werden.
RwSize
Die Größe des Puffers in Bytes, auf den der Rw-Parameter verweist.
Offset
Der Offset in Bytes auf das Element in der Struktur, auf das durch den festzulegenden Rw-Parameter verwiesen wird. Dieser Parameter ist derzeit nicht verwendet und muss auf null festgelegt werden.
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 |
|---|---|
|
Zugriff verweigert.“ Dieser Fehler wird unter folgenden Bedingungen zurückgegeben: Dem Benutzer fehlen die erforderlichen Administratorrechte auf dem lokalen Computer, oder die Anwendung wird nicht in einer erweiterten Shell als integrierter Administrator (RunAs-Administrator) ausgeführt. |
|
Der angegebene Benutzerpuffer ist für den angeforderten Vorgang ungültig. Dieser Fehler wird zurückgegeben, wenn der Row-Parameter ein NULL-Zeiger und der RwSize-Parameter nonzero ist. |
|
„Der Parameter ist falsch.“ Dieser Fehler wird zurückgegeben, wenn der Row-Parameter ein NULL-Zeiger ist. |
|
Dieser angeforderte Eintrag wurde nicht gefunden. Dieser Fehler wird zurückgegeben, wenn die im Row-Parameter angegebene TCP-Verbindung nicht gefunden werden konnte. |
|
Die Anforderung wird nicht unterstützt. Dieser Fehler wird zurückgegeben, wenn der RwVersion - oder Offset-Parameter nicht auf 0 festgelegt ist. |
|
Verwenden Sie FormatMessage , um die Nachrichtenzeichenfolge für den zurückgegebenen Fehler abzurufen. |
Hinweise
Die SetPerTcpConnectionEStats-Funktion wird unter Windows Vista und höher definiert.
Die SetPerTcpConnectionEStats-Funktion wird verwendet, um erweiterte Statistiken für eine im Row-Parameter übergebene IPv4-TCP-Verbindung zu aktivieren oder zu deaktivieren. Erweiterte Statistiken für eine TCP-Verbindung sind standardmäßig deaktiviert. Die SetPerTcpConnectionEStats-Funktion wird verwendet, um den Wert eines Elements in den Lese-/Schreibinformationen für erweiterte Statistiken für eine IPv4-TCP-Verbindung festzulegen. Der Typ und das Format der festzulegenden Struktur werden durch den Parameter EstatsType angegeben. Der Rw-Parameter enthält einen Zeiger auf die übergebene Struktur. Alle Elemente in der Struktur, auf die vom Rw-Parameter verwiesen wird, müssen angegeben werden.
Die einzige unterstützte Version der TCP-Verbindungsstatistik ist Version 0. Daher sollte der an SetPerTcpConnectionEStats übergebeneRwVersion-Parameter auf 0 festgelegt werden.
Die Struktur, auf die der Rw-Parameter verweist, der diese Funktion übergeben hat, hängt vom Enumerationswert ab, der im EstatsType-Parameter übergeben wird. In der folgenden Tabelle wird der Strukturtyp angegeben, der im Rw-Parameter für jeden möglichen EstatsType-Parametertyp übergeben werden soll.
| EstatsType | Struktur, auf die rw verweist |
|---|---|
| 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 |
Der Offset-Parameter ist derzeit nicht verwendet und muss auf 0 festgelegt werden. Die möglichen Strukturen, auf die der Rw-Parameter verweist, verfügen alle über ein einzelnes Element mit Ausnahme der TCP_ESTATS_BANDWIDTH_RW_v0-Struktur . Wenn der Parameter EstatsType auf TcpConnectionEstatsBandwidth festgelegt ist, müssen für die TCP_ESTATS_BANDWIDTH_RW_v0 Struktur, auf die vom Rw-Parameter verwiesen wird, beide Strukturmember auf die bevorzugten Werte in einem einzelnen Aufruf der SetPerTcpConnectionEStats-Funktion festgelegt sein.
Wenn der RwSize-Parameter auf 0 festgelegt ist, gibt die SetPerTcpConnectionEStats-Funktion NO_ERROR zurück und nimmt keine Änderungen am erweiterten Statistik-status vor.
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 SetPerTcpConnectionEStats-Funktion übergebene Row-Parameter muss ein Eintrag für eine vorhandene IPv4-TCP-Verbindung sein.
Sobald erweiterte Statistiken für eine TCP-Verbindung für IPv4 aktiviert sind, rufen Anwendungen die GetPerTcpConnectionEStats-Funktion auf, um erweiterte Statistiken für die TCP-Verbindung abzurufen.
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.
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 Windows Server 2008 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 in der Anwendung unter Windows Vista oder Windows Server 2008 diese Manifestdatei fehlt, muss ein Benutzer, der sich als Mitglied der Gruppe Administratoren angemeldet hat, nicht der integrierte Administrator, die Anwendung dann in einer erweiterten Shell als integrierter Administrator (RunAs-Administrator) ausführen, damit diese Funktion erfolgreich ist.
In Windows-Versionen vor Windows 10 Version 1709 (Fall Creators Update) können Sie SetPerTcpConnectionEStats verwenden, um Statistiken für eine Verbindung zu deaktivieren und wiederzuverwenden, sodass alle Statistikindikatoren auf Null zurückgesetzt werden. Ab Windows 10 Version 1709 (Fall Creators Update) werden einige Statistikindikatoren nicht zurückgesetzt, wenn Statistiken deaktiviert und erneut aktiviert werden. Wenn zwei Anwendungen Statistiken für dieselbe Verbindung überwachen, kann eine Anwendung die andere verwirren, indem statistiken deaktiviert werden. Aus diesen Gründen empfehlen wir, dass Ihre Anwendung keine Verbindungsstatistiken deaktiviert. Um Änderungen im Laufe der Zeit zu erkennen, sollten Sie die von einem vorherigen Aufruf von GetPerTcpConnectionEStats gelesenen Zählerwerte speichern und sie von denen subtrahieren, die von einem nachfolgenden Aufruf gelesen werden.
Anforderungen
| Anforderung | Wert |
|---|---|
| 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 |