Funzione SetPerTcpConnectionEStats (iphlpapi.h)
La funzione SetPerTcpConnectionEStats imposta un valore nelle informazioni di lettura/scrittura per una connessione TCP IPv4. Questa funzione viene usata per abilitare o disabilitare le statistiche estese per una connessione TCP IPv4.
Sintassi
IPHLPAPI_DLL_LINKAGE ULONG SetPerTcpConnectionEStats(
PMIB_TCPROW Row,
TCP_ESTATS_TYPE EstatsType,
PUCHAR Rw,
ULONG RwVersion,
ULONG RwSize,
ULONG Offset
);
Parametri
Row
Puntatore a una struttura MIB_TCPROW per una connessione TCP IPv4.
EstatsType
Tipo di statistiche estese da impostare per TCP. Questo parametro determina i dati e il formato delle informazioni previste nel parametro Rw .
Questo parametro può essere uno dei valori del tipo di enumerazione TCP_ESTATS_TYPE definito nel file di intestazione Tcpestats.h .
Rw
Puntatore a un buffer contenente le informazioni di lettura/scrittura da impostare. Il buffer deve contenere un valore dall'enumerazione TCP_BOOLEAN_OPTIONAL per ogni membro della struttura che specifica la modalità di aggiornamento di ogni membro.
RwVersion
Versione delle informazioni di lettura/scrittura da impostare. Questo parametro deve essere impostato su zero per Windows Vista, Windows Server 2008 e Windows 7.
RwSize
Dimensioni, in byte, del buffer a cui punta il parametro Rw .
Offset
Offset, in byte, al membro della struttura a cui punta il parametro Rw da impostare. Questo parametro è attualmente inutilizzato e deve essere impostato su zero.
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 |
|---|---|
|
Accesso negato. Questo errore viene restituito in diverse condizioni che includono quanto segue: l'utente non dispone dei privilegi amministrativi necessari nel computer locale o l'applicazione non è in esecuzione in una shell avanzata come amministratore predefinito (amministratore RunAs). |
|
Il buffer utente fornito non è valido per l'operazione richiesta. Questo errore viene restituito se il parametro Row è un puntatore NULL e il parametro RwSize è diverso da zero. |
|
Parametro non corretto. Questo errore viene restituito se il parametro Row è un puntatore NULL . |
|
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 o Offset non è impostato su 0. |
|
Usare FormatMessage per ottenere la stringa di messaggio per l'errore restituito. |
Commenti
La funzione SetPerTcpConnectionEStats è definita in Windows Vista e versioni successive.
La funzione SetPerTcpConnectionEStats viene usata per abilitare o disabilitare le statistiche estese in una connessione TCP IPv4 passata nel parametro Row . Le statistiche estese su una connessione TCP sono disabilitate per impostazione predefinita. La funzione SetPerTcpConnectionEStats viene usata per impostare il valore di un membro nelle informazioni di lettura/scrittura per le statistiche estese per una connessione TCP IPv4. Il tipo e il formato della struttura da impostare sono specificati dal parametro EstatsType . Il parametro Rw contiene un puntatore alla struttura passata. Tutti i membri della struttura a cui punta il parametro Rw devono essere specificati.
L'unica versione delle statistiche di connessione TCP attualmente supportate è zero. Quindi il parametro RwVersion passato a SetPerTcpConnectionEStats deve essere impostato su 0.
La struttura a cui fa riferimento il parametro Rw passato questa funzione dipende dal valore di enumerazione passato nel parametro EstatsType . La tabella seguente indica il tipo di struttura che deve essere passato nel parametro Rw per ogni possibile tipo di parametro EstatsType .
| EstatsType | Struttura puntata da Rw |
|---|---|
| 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 |
Il parametro Offset è attualmente inutilizzato e deve essere impostato su 0. Le possibili strutture a cui punta il parametro Rw hanno tutti un singolo membro, ad eccezione della struttura TCP_ESTATS_BANDWIDTH_RW_v0 . Quando il parametro EstatsType è impostato su TcpConnectionEstatsBandwidth, la struttura TCP_ESTATS_BANDWIDTH_RW_v0 puntata dal parametro Rw deve avere entrambi i membri della struttura impostati sui valori preferiti in una singola chiamata alla funzione SetPerTcpConnectionEStats .
Se il parametro RwSize è impostato su 0, la funzione SetPerTcpConnectionEStats restituisce NO_ERROR e non apporta modifiche allo stato delle statistiche estese.
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 SetPerTcpConnectionEStats deve essere una voce per una connessione TCP IPv4 esistente.
Dopo aver abilitato le statistiche estese in una connessione TCP per IPv4, le applicazioni chiamano la funzione GetPerTcpConnectionEStats per recuperare statistiche estese sulla connessione TCP.
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.
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 Windows Server 2008. 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 in Windows Vista o Windows Server 2008 manca 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 questa funzione.
Nelle versioni di Windows precedenti a Windows 10 versione 1709 (Fall Creators Update), è possibile usare SetPerTcpConnectionEStats per disabilitare e riabilitare le statistiche in una connessione, causando la reimpostazione di eventuali contatori delle statistiche su zero. A partire da Windows 10, versione 1709 (Fall Creators Update), alcuni contatori delle statistiche non vengono reimpostati quando le statistiche sono disabilitate e riabilitabili. Inoltre, se due applicazioni monitorano le statistiche per la stessa connessione, un'applicazione può confondere l'altra disabilitando le statistiche. Per questi motivi, è consigliabile che l'applicazione non disabilita le statistiche sulle connessioni. Per rilevare le modifiche nel tempo, è necessario salvare i valori del contatore letti da una chiamata precedente a GetPerTcpConnectionEStats e sottraerli da tali valori letti da una chiamata successiva.
Requisiti
| Requisito | Valore |
|---|---|
| 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 |