SERIAL_TIMEOUTS 構造体 (ntddser.h)

[アーティクル]
08/07/2023

SERIAL_TIMEOUTS構造体は、シリアルポートによる読み取りおよび書き込み操作のタイムアウトパラメーターを指定します。

構文

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

メンバー

ReadIntervalTimeout

読み取り操作で 2 つの連続するバイト間で許可される最大時間 (ミリ秒単位)。この最大タイムアウトを超える読み取り操作。この最大値は、最初のバイトの読み取り前の時間間隔には適用されません。値 0 は、間隔のタイムアウトが使用されないことを示します。詳細については、「解説」を参照してください。

ReadTotalTimeoutMultiplier

読み取り操作でバイトごとに許可される最大時間 (ミリ秒単位)。この最大タイムアウトを超える読み取り操作。詳細については、「解説」を参照してください。

ReadTotalTimeoutConstant

読み取り操作ごとに許可される最大追加時間 (ミリ秒単位)。この最大タイムアウトを超える読み取り操作。詳細については、「解説」を参照してください。

WriteTotalTimeoutMultiplier

書き込み操作でバイトごとに許可される最大合計時間 (ミリ秒単位)。この最大タイムアウトを超える書き込み操作。詳細については、「解説」を参照してください。

WriteTotalTimeoutConstant

書き込み操作ごとに許可される最大追加時間 (ミリ秒単位)。この最大タイムアウトを超える書き込み操作。詳細については、「解説」を参照してください。

注釈

SERIAL_TIMEOUTS構造体は、IOCTL_SERIAL_SET_TIMEOUTSおよびIOCTL_SERIAL_GET_TIMEOUTS I/O 制御要求によって使用されます。 IOCTL_SERIAL_SET_TIMEOUTS I/O 制御要求では、この構造体を使用して、読み取りおよび書き込み操作に使用するシリアルポートのタイムアウトパラメーターのセットを指定します。 IOCTL_SERIAL_GET_TIMEOUTS I/O 制御要求では、この構造体を使用して、前のIOCTL_SERIAL_SET_TIMEOUTS要求によって設定されたタイムアウトパラメーターを取得します。

指定したバイト数が転送されるか、要求された読み取りまたは書き込み操作がタイムアウトしたときに、読み取りまたは書き込み要求が正常に完了します。要求は、指定したバイト数が転送されたことを示すSTATUS_SUCCESS状態コードを返します。要求は、操作がタイムアウトしたことを示すSTATUS_TIMEOUT状態コードを返します。

IRP_MJ_READ要求で Ntₒtₐl バイトの長さ、最大時間(Tmₐₓ)の読み取り操作が指定されている場合、シリアルポートで操作の完了が許可される読み取り操作は次のように計算されます。

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

この最大値を超える読み取り要求は、タイムアウトが発生したときに完了し、STATUS_TIMEOUT状態コードを返します。 I/O 状態ブロックの Information フィールドは、タイムアウトが発生するまでに正常に読み取られたバイト数を示します。

IRP_MJ_WRITE要求で、Ntₒtₐl バイトの長さ、最大時間 (Tmₐₓ)、シリアルポートで操作の完了が許可される書き込み操作が指定されている場合は、次のように計算されます。

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

この最大値を超える書き込み要求は、タイムアウトが発生したときに完了し、STATUS_TIMEOUT状態コードを返します。 I/O 状態ブロックの Information フィールドは、タイムアウトが発生する前に正常に書き込まれたバイト数を示します。

読み取りまたは書き込み操作の完了が許可される最大時間 Tmₐₓ は、クライアントが要求を送信した時点からではなく、シリアルポートが要求された操作を開始した時点から常に測定されます。

ReadIntervalTimeout、ReadTotalTimeoutMultiplier、および ReadTotalTimeoutConstant がすべて 0 の場合、読み取り操作はタイムアウトしません。WriteTotalTimeoutMultiplier と WriteTotalTimeoutConstant の両方が 0 の場合、書き込み操作はタイムアウトしません。

ReadIntervalTimeout が 0 の場合、読み取り操作で連続するバイト間の最大間隔はなく、タイムアウトは ReadTotalTimeoutMultiplier メンバーと ReadTotalTimeoutConstant メンバーのみに基づいています。

ReadTotalTimeoutMultiplier と ReadTotalTimeoutConstant の両方が 0 で、ReadIntervalTimeout が MAXULONG より小さく、0 より大きい場合、読み取り操作は、連続して受信したバイトのペア間の間隔が ReadIntervalTimeout を超える場合にのみタイムアウトします。これら 3 つのタイムアウト値が使用され、読み取り要求がポートに送信されるときにシリアルポートの入力バッファーが空の場合、ポートが少なくとも 1 バイトの新しいデータを受信するまで、この要求はタイムアウトすることはありません。

ReadIntervalTimeout が MAXULONG に設定されていて、ReadTotalTimeoutConstant と ReadTotalTimeoutMultiplier の両方が 0 の場合、バイトが受信されていない場合でも、既に受信されているバイト数で読み取り要求がすぐに完了します。この場合、読み取り要求はSTATUS_SUCCESS状態コードを返します。

ReadIntervalTimeout と ReadTotalTimeoutMultiplier の両方が MAXULONG に設定され、ReadTotalTimeoutConstant が 0 より大きく MAXULONG より小さい値に設定されている場合、読み取り要求は次のように動作します。

シリアルポートの入力バッファーにバイトがある場合、読み取り要求はバッファー内のバイトですぐに完了し、STATUS_SUCCESS状態コードを返します。
入力バッファーにバイトがない場合、シリアルポートはバイトが到着するまで待機し、すぐに 1 バイトのデータを使用して読み取り要求を完了し、STATUS_SUCCESS状態コードを返します。
ReadTotalTimeoutConstant で指定された時間内にバイトが到着しない場合、読み取り要求はタイムアウトし、I/O 状態ブロックの Information フィールドを 0 に設定し、STATUS_TIMEOUT状態コードを返します。

ReadIntervalTimeout と ReadTotalTimeoutConstant の両方が MAXULONG に設定されている場合、IOCTL_SERIAL_SET_TIMEOUTS要求は失敗し、INVALID_PARAMETERエラー状態コードを返します。

読み取り間隔タイムアウトを使用すると、データストリームの長さが事前にわかっていない場合に、受信データストリームの終了を検出できます。読み取り要求でこの手法が使用されている場合、STATUS_TIMEOUT完了状態コードは通常、要求が正常に完了したことを意味します。

読み取り間隔タイムアウトは、受信バイト間の間隔が ReadIntervalTimeout 値を超えたときに発生します。タイムアウト間隔はシステムクロックに対して測定され、タイムアウト測定の精度はシステムクロックの粒度によって制限されます。その結果、この間隔の開始時刻と終了時刻がシステムクロックティック間の正確な位置に応じて、指定されたタイムアウト間隔より前の 1 つのシステムクロックティックから 1 ティック後の間にタイムアウトが発生する可能性があります。システムクロック割り込み処理が他のデバイスの割り込み処理によって遅延した場合でも、タイムアウトが発生する可能性があります。指定されたタイムアウト間隔がシステムクロックティック間の期間に近いか小さい場合、タイムアウトは遅延なしですぐに発生する可能性があります。

より小さいタイムアウト間隔をより正確に測定する方法として、システムクロックティック間の時間を短縮することが考えられますが、そうすることで電力消費量が増加する可能性があります。さらに、プラットフォーム内のさまざまなドライバーによる割り込みに関連する処理がシステムクロック割り込みの処理を遅らせないことを保証できない限り、システムクロック期間を短縮すると、システムクロックの細分性が確実に向上しない可能性があります。

SERIAL_TIMEOUTS構造体は、ユーザーモードの SetCommTimeouts 関数と GetCommTimeouts 関数で使用される COMMTIMEOUTS 構造体に似ています。

詳細については、「シリアルデバイスの読み取りおよび書き込みタイムアウトの設定」を参照してください。