Funzione GetPerTcpConnectionEStats (iphlpapi.h)

Articolo
08/24/2023

La funzione GetPerTcpConnectionEStats recupera le statistiche estese per una connessione TCP IPv4.

Sintassi

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

Parametri

Row

Puntatore a una struttura MIB_TCPROW per una connessione TCP IPv4.

EstatsType

Tipo di statistiche estese per TCP richiesto. Questo parametro determina i dati e il formato delle informazioni restituite nei parametri Rw, Rod e Ros se la chiamata ha esito positivo.

Questo parametro può essere uno dei valori del tipo di enumerazione TCP_ESTATS_TYPE definito nel file di intestazione Tcpestats.h .

Valore	Significato
TcpConnectionEstatsSynOpts	Questo valore richiede informazioni di scambio SYN per una connessione TCP. Per questo valore di enumerazione sono disponibili solo informazioni statiche di sola lettura. Se il parametro Ros non era NULL e la funzione ha esito positivo, il buffer a cui punta il parametro Ros deve contenere una struttura TCP_ESTATS_SYN_OPTS_ROS_v0 .
TcpConnectionEstatsData	Questo valore richiede informazioni di trasferimento dati estese per una connessione TCP. Per questo valore di enumerazione sono disponibili solo informazioni dinamiche di sola lettura/scrittura. Se il parametro Rw non era NULL e la funzione ha esito positivo, il buffer a cui punta il parametro Rw deve contenere una struttura TCP_ESTATS_DATA_RW_v0. Se le informazioni di trasferimento dati estese sono state abilitate per questa connessione TCP , il parametro Rod non era NULL e la funzione ha esito positivo, il buffer a cui punta il parametro Rod deve contenere una struttura TCP_ESTATS_DATA_ROD_v0 .
TcpConnectionEstatsSndCong	Questo valore richiede la congestione del mittente per una connessione TCP. Tutti e tre i tipi di informazioni (informazioni dinamiche di sola lettura e di sola lettura e scrittura) sono disponibili per questo valore di enumerazione. Se il parametro Rw non era NULL e la funzione ha esito positivo, il buffer a cui punta il parametro Rw deve contenere una struttura TCP_ESTATS_SND_CONG_RW_v0. Se il parametro Ros non è NULL e la funzione ha esito positivo, il buffer a cui punta il parametro Ros deve contenere una struttura TCP_ESTATS_SND_CONG_ROS_v0 . Se le informazioni sulla congestione del mittente sono state abilitate per questa connessione TCP, il parametro Rod non era NULL e la funzione ha esito positivo, il buffer a cui punta il parametro Rod deve contenere una struttura TCP_ESTATS_SND_CONG_ROD_v0 .
TcpConnectionEstatsPath	Questo valore richiede informazioni di misurazione del percorso estese per una connessione TCP. Per questo valore di enumerazione sono disponibili solo informazioni dinamiche di sola lettura/scrittura. Se il parametro Rw non era NULL e la funzione ha esito positivo, il buffer a cui punta il parametro Rw deve contenere una struttura TCP_ESTATS_PATH_RW_v0. Se le informazioni di misurazione del percorso esteso sono state abilitate per questa connessione TCP, il parametro Rod non era NULL e la funzione ha esito positivo, il buffer a cui punta il parametro Rod deve contenere una struttura TCP_ESTATS_PATH_ROD_v0 .
TcpConnectionEstatsSendBuff	Questo valore richiede informazioni di accodamento di output estese per una connessione TCP. Per questo valore di enumerazione sono disponibili solo informazioni dinamiche di sola lettura/scrittura. Se il parametro Rw non era NULL e la funzione ha esito positivo, il buffer a cui punta il parametro Rw deve contenere una struttura TCP_ESTATS_SEND_BUFF_RW_v0 . Se le informazioni di accodamento di output estese sono state abilitate per questa connessione TCP, il parametro Rod non era NULL e la funzione ha esito positivo, il buffer a cui punta il parametro Rod deve contenere una struttura TCP_ESTATS_SEND_BUFF_ROD_v0 .
TcpConnectionEstatsRec	Questo valore richiede informazioni sul ricevitore locale estese per una connessione TCP. Per questo valore di enumerazione sono disponibili solo informazioni dinamiche di sola lettura/scrittura. Se il parametro Rw non era NULL e la funzione ha esito positivo, il buffer a cui punta il parametro Rw deve contenere una struttura TCP_ESTATS_REC_RW_v0 . Se le informazioni sul ricevitore locale estese sono state abilitate per questa connessione TCP, il parametro Rod non era NULL e la funzione ha esito positivo, il buffer a cui punta il parametro Rod deve contenere una struttura TCP_ESTATS_REC_ROD_v0 .
TcpConnectionEstatsObsRec	Questo valore richiede informazioni sul ricevitore remoto estese per una connessione TCP. Per questo valore di enumerazione sono disponibili solo informazioni dinamiche di sola lettura/scrittura. Se il parametro Rw non era NULL e la funzione ha esito positivo, il buffer a cui punta il parametro Rw deve contenere una struttura TCP_ESTATS_OBS_REC_RW_v0 . Se le informazioni del ricevitore remoto estese sono state abilitate per questa connessione TCP , il parametro Rod non era NULL e la funzione ha esito positivo, il buffer a cui punta il parametro Rod deve contenere una struttura TCP_ESTATS_OBS_REC_ROD_v0 .
TcpConnectionEstatsBandwidth	Questo valore richiede statistiche di stima della larghezza di banda per una connessione TCP sulla larghezza di banda. Per questo valore di enumerazione sono disponibili solo informazioni dinamiche di sola lettura/scrittura. Se il parametro Rw non era NULL e la funzione ha esito positivo, il buffer a cui punta il parametro Rw deve contenere una struttura TCP_ESTATS_BANDWIDTH_RW_v0. Se le statistiche di stima della larghezza di banda sono state abilitate per questa connessione TCP , il parametro Rod non era NULL e la funzione ha esito positivo, il buffer a cui punta il parametro Rod deve contenere una struttura TCP_ESTATS_BANDWIDTH_ROD_v0 .
TcpConnectionEstatsFineRtt	Questo valore richiede statistiche di stima RTT (round trip con granularità fine) per una connessione TCP. Per questo valore di enumerazione sono disponibili solo informazioni dinamiche di sola lettura/scrittura. Se il parametro Rw non era NULL e la funzione ha esito positivo, il buffer a cui punta il parametro Rw deve contenere una struttura TCP_ESTATS_FINE_RTT_RW_v0 . Se le statistiche di stima RTT con granularità fine sono state abilitate per questa connessione TCP, il parametro Rod non era NULL e la funzione ha esito positivo, il buffer a cui punta il parametro Rod deve contenere una struttura TCP_ESTATS_FINE_RTT_ROD_v0 .

[out] Rw

Puntatore a un buffer per ricevere le informazioni di lettura/scrittura. Questo parametro può essere un puntatore NULL se un'applicazione non vuole recuperare informazioni di lettura/scrittura per la connessione TCP.

RwVersion

Versione delle informazioni di lettura/scrittura richieste. Il valore supportato corrente è una versione di zero.

RwSize

Dimensioni, in byte, del buffer a cui punta il parametro Rw .

[out] Ros

Puntatore a un buffer per ricevere informazioni statiche di sola lettura. Questo parametro può essere un puntatore NULL se un'applicazione non vuole recuperare informazioni statiche di sola lettura per la connessione TCP.

RosVersion

Versione delle informazioni statiche di sola lettura richieste. Il valore supportato corrente è una versione di zero.

RosSize

Dimensioni, in byte, del buffer a cui punta il parametro Ros .

[out] Rod

Puntatore a un buffer per ricevere informazioni dinamiche di sola lettura. Questo parametro può essere un puntatore NULL se un'applicazione non vuole recuperare informazioni dinamiche di sola lettura per la connessione TCP.

RodVersion

Versione delle informazioni dinamiche di sola lettura richieste. Il valore supportato corrente è una versione di zero.

RodSize

Dimensioni, in byte, del buffer a cui punta il parametro Rod .

Valore restituito

Se la funzione ha esito positivo, il valore restituito è NO_ERROR.

Se la funzione ha esito negativo, il valore restituito è uno dei codici di errore seguenti.

Codice restituito	Descrizione
ERROR_INSUFFICIENT_BUFFER	Un buffer passato a una funzione è troppo piccolo. Questo errore viene restituito se il buffer puntato ai parametri Rw, Ros o Rod non è sufficiente per ricevere i dati. Questo errore viene restituito anche se uno dei buffer specificati puntati dai parametri Rw, Ros o Rod è NULL, ma una lunghezza è stata specificata nell'oggetto RwSize, RosSize o RodSize associato. Questo valore di errore viene restituito in Windows Vista e Windows Server 2008.
ERROR_INVALID_PARAMETER	Parametro non corretto. Questo errore viene restituito se il parametro Row è un puntatore NULL .
ERROR_INVALID_USER_BUFFER	Il buffer utente fornito non è valido per l'operazione richiesta. Questo errore viene restituito se uno dei buffer specificati puntati dai parametri Rw, Ros o Rod è NULL, ma una lunghezza è stata specificata nell'oggetto RwSize, RosSize o RodSize associato. Di conseguenza, questo errore viene restituito se vengono soddisfatte le condizioni seguenti: Il parametro Row è un puntatore NULL e il parametro RwSize è diverso da zero. Il parametro Ros è un puntatore NULL e il parametro RosSize è diverso da zero. Il parametro Rod è un puntatore NULL e il parametro RodSize è diverso da zero. Questo valore di errore viene restituito in Windows 7 e Windows Server 2008 R2.
ERROR_NOT_FOUND	Questa voce richiesta non è stata trovata. Questo errore viene restituito se la connessione TCP specificata nel parametro Row non è stata trovata.
ERROR_NOT_SUPPORTED	La richiesta non è supportata. Questo errore viene restituito se il parametro RwVersion, RosVersion o RodVersion non è impostato su zero.
Altri	Usare FormatMessage per ottenere la stringa di messaggio per l'errore restituito.

Commenti

La funzione GetPerTcpConnectionEStats è definita in Windows Vista e versioni successive.

La funzione GetPerTcpConnectionEStats è progettata per usare TCP per diagnosticare i problemi di prestazioni sia nella rete che nell'applicazione. Se un'applicazione basata su rete esegue un problema, TCP può determinare se il collo di bottiglia è nel mittente, il ricevitore o la rete stessa. Se il collo di bottiglia si trova nella rete, TCP può fornire informazioni specifiche sulla sua natura.

La funzione GetPerTcpConnectionEStats recupera le statistiche estese per la connessione TCP IPv4 passata nel parametro Row . Il tipo di statistiche estese recuperate viene specificato nel parametro EstatsType . Le statistiche estese su questa connessione TCP devono essere state abilitate in precedenza dalle chiamate alla funzione SetPerTcpConnectionEStats per tutti i valori TCP_ESTATS_TYPE tranne quando TcpConnectionEstatsSynOpts viene passato nel parametro EstatsType .

La funzione GetTcpTable viene usata per recuperare la tabella di connessione TCP IPv4 nel computer locale. Questa funzione restituisce una struttura MIB_TCPTABLE che contiene una matrice di voci MIB_TCPROW . Il parametro Row passato alla funzione GetPerTcpConnectionEStats deve essere una voce per una connessione TCP IPv4 esistente.

L'unica versione delle statistiche di connessione TCP attualmente supportate è zero. I parametri RwVersion, RosVersion e RodVersion passati a GetPerTcpConnectionEStats devono essere impostati su 0.

Per informazioni sulle statistiche TCP estese su una connessione IPv6, vedere le funzioni GetPerTcp6ConnectionEStats e SetPerTcp6ConnectionEStats .

La funzione SetPerTcpConnectionEStats può essere chiamata solo da un utente connesso come membro del gruppo Administrators. Se SetPerTcpConnectionEStats viene chiamato da un utente che non è membro del gruppo Administrators, la chiamata alla funzione avrà esito negativo e ERROR_ACCESS_DENIED viene restituita. Questa funzione può anche non riuscire a causa del controllo account utente (UAC) in Windows Vista e versioni successive. Se un'applicazione contenente questa funzione viene eseguita da un utente connesso come membro del gruppo Administrators diverso dall'amministratore predefinito, questa chiamata avrà esito negativo a meno che l'applicazione non sia stata contrassegnata nel file manifesto con un set requestedExecutionLevel per richiedereAdministrator. Se l'applicazione manca di questo file manifesto, un utente ha eseguito l'accesso come membro del gruppo Administrators diverso dall'amministratore predefinito, deve quindi eseguire l'applicazione in una shell avanzata come amministratore predefinito (amministratore RunAs) per la riuscita di questa funzione.

Il chiamante di GetPerTcpConnectionEStats deve controllare il campo EnableCollection nello struct Rw restituito e, se non TRUEè , il chiamante deve ignorare i dati negli struct Ros e Rod . Se EnableCollection è impostato su FALSE, i dati restituiti in Ros e Rod non sono definiti. Ad esempio, una condizione in cui questo può verificarsi è quando si usa GetPerTcpConnectionEStats per recuperare statistiche estese per una connessione TCP IPv4 e si è precedentemente chiamato SetPerTcpConnectionEStats per abilitare le statistiche estese. Se la chiamata SetPerTcpConnectionEStats ha esito negativo, le chiamate successive a GetPerTcpConnectionEStats restituiranno dati casuali senza significato e non statistiche TCP estese. È possibile osservare che l'esempio seguente viene eseguito come amministratore e come utente normale.

Esempio

Per un esempio di codice, vedere la sezione Esempi nell'argomento della funzione GetPerTcp6ConnectionEStats .

Requisiti


Client minimo supportato	Windows Vista [solo app desktop]
Server minimo supportato	Windows Server 2008 [solo app desktop]
Piattaforma di destinazione	Windows
Intestazione	iphlpapi.h
Libreria	Iphlpapi.lib
DLL	Iphlpapi.dll