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;
Membri
ReadIntervalTimeout
Quantità massima di tempo, espressa in millisecondi, consentita tra due byte consecutivi in un'operazione di lettura. Operazione di lettura che supera questo 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 Osservazioni.
ReadTotalTimeoutMultiplier
Quantità massima di tempo, espressa in millisecondi, consentita per byte in un'operazione di lettura. Operazione di lettura che supera questo 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 questo 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.
Osservazioni
La struttura SERIAL_TIMEOUTS viene utilizzata dalle richieste di controllo di I/O IOCTL_SERIAL_SET_TIMEOUTS e IOCTL_SERIAL_GET_TIMEOUTSIOCTL_SERIAL_SET_TIMEOUTS. Una richiesta di controllo di 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 di 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 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, ReadTotalTimeoutMultipliere ReadTotalTimeoutConstant sono tutte zero, le operazioni di lettura non si verificano mai un timeout. Se writeTotalTimeoutMultiplier e writeTotalTimeoutConstant sono entrambe zero, le operazioni di scrittura non si verificano mai un timeout.
Se readIntervalTimeout è pari a zero, non esiste alcun intervallo massimo tra i byte consecutivi nelle operazioni di lettura e i timeout si basano esclusivamente sui ReadTotalTimeoutMultiplier e membri ReadTotalTimeoutConstant.
Se sia ReadTotalTimeoutMultiplier che ReadTotalTimeoutConstant sono pari a 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 questi tre valori di timeout vengono usati e il buffer di input della porta seriale è vuoto quando viene inviata una richiesta di lettura alla porta, questa richiesta non scade mai fino a quando la porta riceve almeno un byte di nuovi dati.
Se ReadIntervalTimeout è impostato su MAXULONG e entrambi ReadTotalTimeoutConstant e ReadTotalTimeoutMultiplier sono zero, una richiesta di lettura viene completata immediatamente con i byte che sono già stati 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 vengono impostati su MAXULONG e ReadTotalTimeoutConstant viene 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 l'unico byte di dati e restituisce il codice di stato STATUS_SUCCESS.
- Se non arrivano byte entro il tempo specificato da ReadTotalTimeoutConstant, si verifica il timeout della richiesta di lettura, imposta il campo Information 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 i 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 dell'orologio di sistema precedente e un tick successivo all'intervallo di timeout specificato, a seconda della posizione in cui esattamente l'ora di inizio e di fine di questo intervallo rientrano tra i tick dell'orologio di sistema. I timeout possono verificarsi anche in un secondo momento se l'elaborazione dell'interruzione dell'orologio di sistema viene ritardata dall'elaborazione di interruzioni per altri dispositivi. Se un intervallo di timeout specificato è vicino o inferiore al periodo tra i tick dell'orologio 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 dell'orologio di sistema, ma è probabile che ciò aumenti il consumo di energia. Inoltre, la riduzione del periodo di clock di sistema potrebbe non ottenere in modo affidabile una granularità del clock di sistema più fine, a meno che l'elaborazione correlata agli interrupt dai 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 di COMMTIMEOUTS, usata dalle funzioni SetCommTimeouts in modalità utente SetCommTimeouts e GetCommTimeouts.
Per altre informazioni, vedere Impostazione di timeout di lettura e scrittura per un dispositivo seriale.
Fabbisogno
| Requisito | Valore |
|---|---|
| client minimo supportato | Supportato a partire da Windows 2000. |
| intestazione | ntddser.h |