Funzione GetPerTcpConnectionEStats (iphlpapi.h)
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 |
---|---|
|
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 . |
|
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 . |
|
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 . |
|
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 . |
|
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 . |
|
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 . |
|
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 . |
|
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 . |
|
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 |
---|---|
|
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. |
|
Parametro non corretto. Questo errore viene restituito se il parametro Row è un puntatore NULL . |
|
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:
Questo valore di errore viene restituito in Windows 7 e Windows Server 2008 R2. |
|
Questa voce richiesta non è stata trovata. Questo errore viene restituito se la connessione TCP specificata nel parametro Row non è stata trovata. |
|
La richiesta non è supportata. Questo errore viene restituito se il parametro RwVersion, RosVersion o RodVersion non è impostato su zero. |
|
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 |