struttura SERIAL_TIMEOUTS (ntddser.h)
La struttura SERIAL_TIMEOUTS specifica i parametri di timeout per le operazioni di lettura e scrittura dalla porta seriale.
Sintassi
typedef struct _SERIAL_TIMEOUTS {
ULONG ReadIntervalTimeout;
ULONG ReadTotalTimeoutMultiplier;
ULONG ReadTotalTimeoutConstant;
ULONG WriteTotalTimeoutMultiplier;
ULONG WriteTotalTimeoutConstant;
} SERIAL_TIMEOUTS, *PSERIAL_TIMEOUTS;
Members
ReadIntervalTimeout
Quantità massima di tempo, in millisecondi, consentita tra due byte consecutivi in un'operazione di lettura. Operazione di lettura che supera il timeout massimo. Questo valore massimo non si applica all'intervallo di tempo che precede la lettura del primo byte. Un valore pari a zero indica che i timeout dell'intervallo non vengono utilizzati. Per altre informazioni, vedere la sezione Osservazioni.
ReadTotalTimeoutMultiplier
Quantità massima di tempo, in millisecondi, consentita per byte in un'operazione di lettura. Operazione di lettura che supera il timeout massimo. Per altre informazioni, vedere Osservazioni.
ReadTotalTimeoutConstant
Quantità massima di tempo aggiuntivo, in millisecondi, consentita per ogni operazione di lettura. Operazione di lettura che supera il timeout massimo. Per altre informazioni, vedere Osservazioni.
WriteTotalTimeoutMultiplier
Tempo totale massimo, in millisecondi, consentito per byte in un'operazione di scrittura. Operazione di scrittura che supera questo timeout massimo. Per altre informazioni, vedere Osservazioni.
WriteTotalTimeoutConstant
Quantità massima di tempo aggiuntivo, in millisecondi, consentita per ogni operazione di scrittura. Operazione di scrittura che supera questo timeout massimo. Per altre informazioni, vedere Osservazioni.
Commenti
La struttura SERIAL_TIMEOUTS viene usata dalle richieste di controllo IOCTL_SERIAL_SET_TIMEOUTS e IOCTL_SERIAL_GET_TIMEOUTS I/O. Una richiesta di controllo I/O IOCTL_SERIAL_SET_TIMEOUTS usa questa struttura per specificare un set di parametri di timeout per la porta seriale da usare per le operazioni di lettura e scrittura. Una richiesta di controllo I/O IOCTL_SERIAL_GET_TIMEOUTS usa questa struttura per recuperare i parametri di timeout impostati dalla richiesta di IOCTL_SERIAL_SET_TIMEOUTS precedente.
Una richiesta di lettura o scrittura viene completata correttamente quando si trasferisce il numero specificato di byte o si verifica il timeout dell'operazione di lettura o scrittura richiesta. La richiesta restituisce il codice di stato STATUS_SUCCESS per indicare che il numero specificato di byte è stato trasferito. La richiesta restituisce il codice di stato STATUS_TIMEOUT per indicare il timeout dell'operazione.
Se una richiesta di IRP_MJ_READ specifica un'operazione di lettura ntₒtₐl byte di lunghezza, la quantità massima di tempo, Tmₐₓ, che la porta seriale consente il completamento dell'operazione viene calcolata come segue:
Tmₐₓ = Ntₒtₐl * ReadTotalTimeoutMultiplier + ReadTotalTimeoutConstant
Una richiesta di lettura che supera questo valore massimo viene completata quando si verifica il timeout e restituisce il codice di stato STATUS_TIMEOUT. Il campo Informazioni del blocco di stato di I/O indica il numero di byte letti correttamente prima del timeout.
Se una richiesta di IRP_MJ_WRITE specifica un'operazione di scrittura ntₒtₐl byte di lunghezza, la quantità massima di tempo, Tmₐₓ, che la porta seriale consente il completamento dell'operazione viene calcolata come segue:
Tmₐₓ = Ntₒtₐl * WriteTotalTimeoutMultiplier + WriteTotalTimeoutConstant
Una richiesta di scrittura che supera questo valore massimo viene completata quando si verifica il timeout e restituisce il codice di stato STATUS_TIMEOUT. Il campo Informazioni del blocco di stato di I/O indica il numero di byte scritti correttamente prima del timeout.
Il tempo massimo, Tmₐₓ, consentito per il completamento di un'operazione di lettura o scrittura viene sempre misurato da quando la porta seriale avvia l'operazione richiesta e non da quando il client invia la richiesta.
Se ReadIntervalTimeout, ReadTotalTimeoutMultiplier e ReadTotalTimeoutConstant sono tutti zero, le operazioni di lettura non si verifica mai il timeout. Se WriteTotalTimeoutMultiplier e WriteTotalTimeoutConstant sono entrambi zero, le operazioni di scrittura non si verificano mai il timeout.
Se ReadIntervalTimeout è zero, non esiste un intervallo massimo tra byte consecutivi nelle operazioni di lettura e i timeout sono basati esclusivamente sui membri ReadTotalTimeoutMultiplier e ReadTotalTimeoutConstant .
Se readTotalTimeoutMultiplier e ReadTotalTimeoutConstant sono zero e ReadIntervalTimeout è minore di MAXULONG e maggiore di zero, un'operazione di lettura scade solo se l'intervallo tra una coppia di byte ricevuti consecutivamente supera ReadIntervalTimeout. Se vengono usati questi tre valori di timeout e il buffer di input della porta seriale è vuoto quando viene inviata una richiesta di lettura alla porta, questa richiesta non si verifica mai fino a quando la porta riceve almeno un byte di nuovi dati.
Se ReadIntervalTimeout è impostato su MAXULONG e ReadTotalTimeoutConstant e ReadTotalTimeoutMultiplier sono zero, una richiesta di lettura viene completata immediatamente con i byte già ricevuti, anche se non sono stati ricevuti byte. In questo caso, la richiesta di lettura restituisce il codice di stato STATUS_SUCCESS.
Se sia ReadIntervalTimeout che ReadTotalTimeoutMultiplier sono impostati su MAXULONG e ReadTotalTimeoutConstant è impostato su un valore maggiore di zero e minore di MAXULONG, una richiesta di lettura si comporta come segue:
- Se sono presenti byte nel buffer di input della porta seriale, la richiesta di lettura viene completata immediatamente con i byte presenti nel buffer e restituisce il codice di stato STATUS_SUCCESS.
- Se nel buffer di input non sono presenti byte, la porta seriale attende fino all'arrivo di un byte e quindi completa immediatamente la richiesta di lettura con un byte di dati e restituisce il codice di stato STATUS_SUCCESS.
- Se non arrivano byte entro il tempo specificato da ReadTotalTimeoutConstant, il timeout della richiesta di lettura, imposta il campo Informazioni del blocco di stato di I/O su zero e restituisce il codice di stato STATUS_TIMEOUT.
È possibile usare un timeout dell'intervallo di lettura per rilevare la fine di un flusso di dati in ingresso quando la lunghezza del flusso di dati non è nota in anticipo. Se una richiesta di lettura usa questa tecnica, un codice di stato di completamento STATUS_TIMEOUT indica in genere che la richiesta è stata completata correttamente.
Un timeout dell'intervallo di lettura si verifica quando l'intervallo tra byte in ingresso supera il valore ReadIntervalTimeout . Gli intervalli di timeout vengono misurati rispetto all'orologio di sistema e l'accuratezza della misurazione del timeout è limitata dalla granularità dell'orologio di sistema. Di conseguenza, un timeout può verificarsi tra un tick di clock di sistema precedente e un tick successivo all'intervallo di timeout specificato, a seconda del punto in cui esattamente l'ora di inizio e di fine di questo intervallo rientrano tra i tick dell'orologio di sistema. I timeout potrebbero verificarsi anche in un secondo momento se l'elaborazione dell'interruzione dell'orologio di sistema è ritardata dall'elaborazione degli interrupt per altri dispositivi. Se un intervallo di timeout specificato è vicino o inferiore al periodo tra i tick del clock di sistema, il timeout potrebbe verificarsi immediatamente, senza alcun ritardo.
Un modo possibile per misurare in modo più accurato intervalli di timeout più piccoli consiste nel ridurre il tempo tra i tick del clock di sistema, ma è probabile che ciò aumenti il consumo di energia. Inoltre, la riduzione del periodo di clock di sistema potrebbe non raggiungere in modo affidabile una granularità del clock di sistema più fine, a meno che l'elaborazione correlata agli interrupt dei vari driver nella piattaforma non possa essere garantita per ritardare l'elaborazione di interruzioni dell'orologio di sistema.
La struttura SERIAL_TIMEOUTS è simile alla struttura COMMTIMEOUTS , usata dalle funzioni SetCommTimeouts e GetCommTimeouts in modalità utente.
Per altre informazioni, vedere Impostazione dei timeout di lettura e scrittura per un dispositivo seriale.
Requisiti
| Requisito | Valore |
|---|---|
| Client minimo supportato | Supportato a partire da Windows 2000. |
| Intestazione | ntddser.h |