SERIAL_TIMEOUTS-Struktur (ntddser.h)

Artikel
02/26/2024

Die SERIAL_TIMEOUTS-Struktur gibt die Timeoutparameter für Lese- und Schreibvorgänge über den seriellen Port an.

Syntax

typedef struct _SERIAL_TIMEOUTS {
  ULONG ReadIntervalTimeout;
  ULONG ReadTotalTimeoutMultiplier;
  ULONG ReadTotalTimeoutConstant;
  ULONG WriteTotalTimeoutMultiplier;
  ULONG WriteTotalTimeoutConstant;
} SERIAL_TIMEOUTS, *PSERIAL_TIMEOUTS;

Member

ReadIntervalTimeout

Die maximale Zeitspanne in Millisekunden, die zwischen zwei aufeinanderfolgenden Bytes in einem Lesevorgang zulässig ist. Ein Lesevorgang, der dieses maximale Timeout überschreitet. Dieser Höchstwert gilt nicht für das Zeitintervall, das vor dem Lesen des ersten Bytes liegt. Der Wert 0 (null) gibt an, dass Intervalltimeouts nicht verwendet werden. Weitere Informationen finden Sie in den Hinweisen.

ReadTotalTimeoutMultiplier

Die maximale Zeit in Millisekunden, die pro Byte in einem Lesevorgang zulässig ist. Ein Lesevorgang, der dieses maximale Timeout überschreitet. Weitere Informationen finden Sie unter Hinweise.

ReadTotalTimeoutConstant

Die maximale Zusätzliche Zeit in Millisekunden, die pro Lesevorgang zulässig ist. Ein Lesevorgang, der dieses maximale Timeout überschreitet. Weitere Informationen finden Sie unter Hinweise.

WriteTotalTimeoutMultiplier

Die maximale Gesamtzeit in Millisekunden, die pro Byte in einem Schreibvorgang zulässig ist. Ein Schreibvorgang, der dieses maximale Timeout überschreitet. Weitere Informationen finden Sie unter Hinweise.

WriteTotalTimeoutConstant

Die maximale Zusätzliche Zeit in Millisekunden, die pro Schreibvorgang zulässig ist. Ein Schreibvorgang, der dieses maximale Timeout überschreitet. Weitere Informationen finden Sie unter Hinweise.

Hinweise

Die SERIAL_TIMEOUTS-Struktur wird von IOCTL_SERIAL_SET_TIMEOUTS- und IOCTL_SERIAL_GET_TIMEOUTS-E /A-Steuerungsanforderungen verwendet. Eine IOCTL_SERIAL_SET_TIMEOUTS E/A-Steuerungsanforderung verwendet diese Struktur, um einen Satz von Timeoutparametern für den seriellen Port anzugeben, der für Lese- und Schreibvorgänge verwendet werden soll. Eine IOCTL_SERIAL_GET_TIMEOUTS E/A-Steuerungsanforderung verwendet diese Struktur, um die Timeoutparameter abzurufen, die von der vorherigen IOCTL_SERIAL_SET_TIMEOUTS-Anforderung festgelegt wurden.

Eine Lese- oder Schreibanforderung wird erfolgreich abgeschlossen, wenn entweder die angegebene Anzahl von Bytes übertragen wird oder der angeforderte Lese- oder Schreibvorgang ein Zeitüberschreitung auftritt. Die Anforderung gibt den STATUS_SUCCESS status Code zurück, um anzugeben, dass die angegebene Anzahl von Bytes übertragen wurde. Die Anforderung gibt den STATUS_TIMEOUT status Code zurück, um anzugeben, dass für den Vorgang ein Timeout aufgetreten ist.

Wenn eine IRP_MJ_READ-Anforderung einen Lesevorgang angibt, der ntₒtₐl Bytes lang ist, wird die maximale Zeitspanne tmₐₓ, die der serielle Port für den Abschluss des Vorgangs zulässt, wie folgt berechnet:

Tmₐₓ = Ntₒtₐl * ReadTotalTimeoutMultiplier + ReadTotalTimeoutConstant

Eine Leseanforderung, die dieses Maximum überschreitet, wird abgeschlossen, wenn das Timeout auftritt, und gibt den STATUS_TIMEOUT status Code zurück. Das Feld Information des E/A-status blocks gibt die Anzahl der Bytes an, die vor dem Timeout erfolgreich gelesen wurden.

Wenn eine IRP_MJ_WRITE-Anforderung einen Schreibvorgang angibt, der ntₒtₐl Bytes lang ist, wird die maximale Zeitspanne tmₐₓ, die der serielle Port für den Abschluss des Vorgangs zulässt, wie folgt berechnet:

Tmₐₓ = Ntₒtₐl * WriteTotalTimeoutMultiplier + WriteTotalTimeoutConstant

Eine Schreibanforderung, die dieses Maximum überschreitet, wird abgeschlossen, wenn das Timeout auftritt, und gibt den STATUS_TIMEOUT status Code zurück. Das Feld Information des E/A-status blocks gibt die Anzahl der Bytes an, die vor dem Timeout erfolgreich geschrieben wurden.

Die maximale Zeit, Tmₐₓ, die für den Abschluss eines Lese- oder Schreibvorgangs zulässig ist, wird immer ab dem Zeitpunkt gemessen, an dem der serielle Port den angeforderten Vorgang startet, und nicht ab dem Zeitpunkt, an dem der Client die Anforderung übermittelt.

Wenn ReadIntervalTimeout, ReadTotalTimeoutMultiplier und ReadTotalTimeoutConstant alle null sind, wird bei Lesevorgängen kein Timeout ausgeführt. Wenn WriteTotalTimeoutMultiplier und WriteTotalTimeoutConstant beide null sind, wird bei Schreibvorgängen kein Timeout ausgeführt.

Wenn ReadIntervalTimeout null ist, gibt es kein maximales Intervall zwischen aufeinanderfolgenden Bytes in Lesevorgängen, und Timeouts basieren ausschließlich auf den Elementen ReadTotalTimeoutMultiplier und ReadTotalTimeoutConstant .

Wenn sowohl ReadTotalTimeoutMultiplier als auch ReadTotalTimeoutConstant null sind und ReadIntervalTimeout kleiner als MAXULONG und größer als 0 ist, ist ein Lesevorgang nur dann zeitlos, wenn das Intervall zwischen einem Paar aufeinanderfolgender empfangener Bytes ReadIntervalTimeout überschreitet. Wenn diese drei Timeoutwerte verwendet werden und der Eingabepuffer des seriellen Ports leer ist, wenn eine Leseanforderung an den Port gesendet wird, tritt für diese Anforderung erst ein Timeout auf, nachdem der Port mindestens ein Byte neuer Daten empfangen hat.

Wenn ReadIntervalTimeout auf MAXULONG festgelegt ist und sowohl ReadTotalTimeoutConstant als auch ReadTotalTimeoutMultiplier null sind, wird eine Leseanforderung sofort mit den bereits empfangenen Bytes abgeschlossen, auch wenn keine Bytes empfangen wurden. In diesem Fall gibt die Leseanforderung den STATUS_SUCCESS status Code zurück.

Wenn sowohl ReadIntervalTimeout als auch ReadTotalTimeoutMultiplier auf MAXULONG festgelegt sind und ReadTotalTimeoutConstant auf einen Wert größer 0 und kleiner als MAXULONG festgelegt ist, verhält sich eine Leseanforderung wie folgt:

Wenn im Eingabepuffer des seriellen Ports Bytes vorhanden sind, wird die Leseanforderung sofort mit den Bytes abgeschlossen, die sich im Puffer befinden, und gibt den STATUS_SUCCESS status Code zurück.
Wenn der Eingabepuffer keine Bytes enthält, wartet der serielle Port, bis ein Byte eintrifft, und schließt dann sofort die Leseanforderung mit dem einen Datenbyte ab und gibt den STATUS_SUCCESS status Code zurück.
Wenn innerhalb der durch ReadTotalTimeoutConstant angegebenen Zeit keine Bytes eingehen, tritt für die Leseanforderung ein Timeout auf, legt das Feld Information des E/A-status-Blocks auf Null fest und gibt den STATUS_TIMEOUT status Code zurück.

Eine IOCTL_SERIAL_SET_TIMEOUTS-Anforderung schlägt fehl und gibt einen INVALID_PARAMETER Fehler status Code zurück, wenn ReadIntervalTimeout undReadTotalTimeoutConstant auf MAXULONG festgelegt sind.

Ein Leseintervalltimeout kann verwendet werden, um das Ende eines eingehenden Datenstroms zu erkennen, wenn die Länge des Datenstroms im Voraus nicht bekannt ist. Wenn eine Leseanforderung dieses Verfahren verwendet, bedeutet ein STATUS_TIMEOUT Abschluss status Code in der Regel, dass die Anforderung erfolgreich abgeschlossen wurde.

Ein Timeout für Leseintervalle tritt auf, wenn das Intervall zwischen eingehenden Bytes den Wert ReadIntervalTimeout überschreitet. Timeoutintervalle werden relativ zur Systemuhr gemessen, und die Genauigkeit der Timeoutmessung wird durch die Granularität der Systemuhr begrenzt. Daher kann ein Timeout zwischen einem Systemuhrtakt früher und einem Tick später als das angegebene Timeoutintervall auftreten, je nachdem, wo genau die Start- und Endzeiten dieses Intervalls zwischen den Takten der Systemuhr liegen. Timeouts können auch später auftreten, wenn die Verarbeitung von Unterbrechungen der Systemuhr durch die Interruptverarbeitung für andere Geräte verzögert wird. Wenn ein angegebenes Timeoutintervall nahe oder kleiner als der Zeitraum zwischen systemtaktenden Ticks ist, kann das Timeout sofort und ohne Verzögerung auftreten.

Eine mögliche Möglichkeit, kleinere Timeoutintervalle genauer zu messen, besteht darin, die Zeit zwischen den Ticks der Systemuhr zu verringern, aber dies ist wahrscheinlich, dass der Stromverbrauch erhöht wird. Darüber hinaus kann die Reduzierung des Systemuhrzeitraums möglicherweise nicht zuverlässig eine feinere Systemuhrgranularität erzielen, es sei denn, die interruptbezogene Verarbeitung durch die verschiedenen Treiber auf der Plattform kann garantiert werden, dass die Verarbeitung von Systemuhrunterbrechungen nicht verzögert wird.

Die SERIAL_TIMEOUTS-Struktur ähnelt der COMMTIMEOUTS-Struktur , die von den Funktionen SetCommTimeouts und GetCommTimeouts im Benutzermodus verwendet wird.

Weitere Informationen finden Sie unter Festlegen von Lese- und Schreibtimeouts für ein serielles Gerät.