EVT_SERCX2_CONTROL コールバック関数 (sercx.h)

  • [アーティクル]

EvtSerCx2Control イベント コールバック関数は、シリアル I/O 制御要求を処理するために、シリアル フレームワーク拡張機能 (SerCx2) のバージョン 2 によって呼び出されます。

構文

EVT_SERCX2_CONTROL EvtSercx2Control;

NTSTATUS EvtSercx2Control(
  [in] WDFDEVICE Device,
  [in] WDFREQUEST Request,
  [in] size_t OutputBufferLength,
  [in] size_t InputBufferLength,
  [in] ULONG IoControlCode
)
{...}

パラメーター

[in] Device

シリアル コントローラーを表すフレームワーク デバイス オブジェクトへの WDFDEVICE ハンドル。 シリアル コントローラー ドライバーは、EvtDriverDeviceAdd コールバック関数でこのオブジェクトを作成しました。 詳細については、「SerCx2InitializeDevice」を参照してください。

[in] Request

シリアル I/O 制御要求を表すフレームワーク要求オブジェクトに対する WDFREQUEST ハンドル。

[in] OutputBufferLength

Request パラメーターで指定されたシリアル I/O 制御要求の出力バッファーの長さ (バイト単位)。

[in] InputBufferLength

Request パラメーターで指定されたシリアル I/O 制御要求の入力バッファーの長さ (バイト単位)。

[in] IoControlCode

Request パラメーターで指定されたシリアル I/O 制御要求からの I/O 制御コード (IOCTL) を指定します。 シリアル I/O 制御要求の IOCTL は Ntddser.h ヘッダー ファイルで定義されています。 詳細については、「解説」を参照してください。

戻り値

EvtSerCx2Control 関数は、呼び出しが成功した場合にSTATUS_SUCCESSを返します。 それ以外の場合は、適切なエラー状態コードが返されます。

備考

シリアル コントローラー ドライバーでは、この関数を実装する必要があります。 ドライバーは、シリアル コント ローラーのフレームワーク デバイス オブジェクトの初期化を完了する SerCx2InitializeDevice メソッドの呼び出しで関数を登録します。

EvtSerCx2Control 関数を使用すると、SerCx2 で処理できない特定のシリアル I/O コントロール要求をドライバーが処理できます。 SerCx2 は、Ntddser.h ヘッダー ファイルで定義されているシリアル IOCTL のサブセットに対するすべての処理を処理します。 ただし、SerCx2 は、ハードウェアに依存する操作を実行するシリアル I/O 制御要求を処理するドライバーに依存します。

SerCx2 がシリアル コントローラー ドライバーでのみ処理できるシリアル I/O 制御要求を受信すると、SerCx2 は、EvtSerCx2Control 関数を呼び出して、I/O コントロール要求をドライバーに渡します。 ドライバーは、この要求を完了する必要があります。 特定の I/O 制御要求のサポートを実装していないドライバーは、STATUS_NOT_SUPPORTEDエラー状態コードを使用して、この I/O 制御要求を完了する必要があります。

I/O 制御要求を完了するために、ドライバーは通常、WdfRequestComplete メソッドを呼び出し、入力パラメーターとして、Request パラメーター値と、要求が成功したかどうかを示す状態値を指定します。 この状態値は、要求の状態ブロックに書き込まれます。

EvtSerCx2Control 関数の戻り値は、この関数が I/O 制御要求の状態ブロックに書き込む状態値と常に一致する必要があります。 SerCx2 の現在の実装では、この戻り値は無視されます。

SerCx2 は、次の表に示す IOCTL を処理するために、EvtSerCx2Control 関数を呼び出します。 テーブルの右側の列は、特定の IOCTL のサポートを実装するために、EvtSerCx2Control 関数が必要かどうかを示します。

I/O 制御要求名 必須または省略可能
IOCTL_SERIAL_CLR_DTR 随意
IOCTL_SERIAL_CLR_RTS 必須
IOCTL_SERIAL_GET_BAUD_RATE 必須
IOCTL_SERIAL_GET_COMMSTATUS 必須
IOCTL_SERIAL_GET_DTRRTS 必須
IOCTL_SERIAL_GET_HANDFLOW 必須
IOCTL_SERIAL_GET_LINE_CONTROL 必須
IOCTL_SERIAL_GET_MODEM_CONTROL 必須
IOCTL_SERIAL_GET_MODEMSTATUS 必須
IOCTL_SERIAL_GET_PROPERTIES 必須
IOCTL_SERIAL_SET_BAUD_RATE 必須
IOCTL_SERIAL_SET_BREAK_OFF 必須
IOCTL_SERIAL_SET_BREAK_ON 必須
IOCTL_SERIAL_SET_DTR 随意
IOCTL_SERIAL_SET_FIFO_CONTROL 随意
IOCTL_SERIAL_SET_HANDFLOW 必須
IOCTL_SERIAL_SET_LINE_CONTROL 必須
IOCTL_SERIAL_SET_MODEM_CONTROL 必須
IOCTL_SERIAL_SET_RTS 必須
 

上の表に、SerCx2 が EvtSerCx2Control 関数に提示するすべてのシリアル IOCTL を示します。 この一覧にない IOCTL の場合、SerCx2 は IOCTL を処理するか、IOCTL を直ちに失敗させ、要求の状態をSTATUS_NOT_SUPPORTEDに設定します。 SerCx2 は IOCTL_SERIAL_APPLY_DEFAULT_CONFIGURATION 要求を処理しますが、このような要求の処理中に、EvtSerCx2ApplyConfig イベント コールバック関数を呼び出します。 SerCx2 は IOCTL_SERIAL_PURGE 要求を処理しますが、このような要求の処理中にイベント コールバック関数 EvtSerCx2PurgeFifos を呼び出す場合があります。 SerCx は IOCTL_SERIAL_SET_WAIT_MASK 要求の事前処理を行いますが、そのような要求の処理を完了するために、イベント コールバック関数 EvtSerCx2SetWaitMask を呼び出します (実装されている場合)。 シリアル IOCTL の SerCx2 サポートの詳細については、「シリアル I/O 要求インターフェイスのを参照してください。

IOCTL_SERIAL_CLR_DTRとIOCTL_SERIAL_SET_DTR

シリアル コントローラー ドライバーの EvtSerCx2Control 関数が IOCTL_SERIAL_SET_DTR 要求をサポートしている場合、この関数は IOCTL_SERIAL_CLR_DTR 要求もサポートする必要があります。その逆も同様です。 ドライバーがこれら 2 つの要求をサポートしていない場合、IOCTL_SERIAL_GET_DTRRTS 要求のドライバーのハンドラーは、この要求の出力値のSERIAL_DTR_STATE フラグ ビットを 0 に設定する必要があります。

IOCTL_SERIAL_GET_DTRRTS

シリアル コントローラー ドライバーの EvtSerCx2Control 関数は、IOCTL_SERIAL_GET_DTRRTS 要求をサポートする必要がありますが、この要求のドライバーのハンドラーは、この要求の出力値のSERIAL_RTS_STATE フラグ ビットのみをサポートする必要があります。 オプションとして、ドライバーはSERIAL_DTR_STATE フラグ ビットをサポートすることもできます。 SERIAL_DTR_STATE フラグ ビットがサポートされていない場合は、このビットを 0 に設定します。

IOCTL_SERIAL_GET_COMMSTATUS

シリアル コントローラー ドライバーの EvtSerCx2Control 関数は、IOCTL_SERIAL_GET_COMMSTATUS 要求をサポートする必要がありますが、この要求で使用される SERIAL_STATUS 構造体の次のメンバーのみをサポートするには、この要求のドライバーのハンドラーが必要です。

  • エラー
  • HoldReasons
オプションとして、ドライバーは、さらにこの構造体の他のメンバーのいずれかをサポートできます。 サポートされていないメンバーをすべて 0 に設定します。

IOCTL_SERIAL_GET_PROPERTIES

シリアル コントローラー ドライバーの EvtSerCx2Control 関数は、IOCTL_SERIAL_GET_PROPERTIES 要求をサポートする必要があります。 この要求のドライバーハンドラーは、この要求で使用される SERIAL_COMMPROP 構造体の MaxBaud メンバーを、サポートされる最大ボー レート (ビット/秒 ( bps) に設定する必要があります。 たとえば、シリアル コントローラーが最大ボー レート 115,200 bps をサポートしている場合、ドライバーは MaxBaud = 115200 設定します。

IOCTL_SERIAL_GET_MODEMSTATUS

シリアル コントローラー ドライバー EvtSerCx2Control 関数は、IOCTL_SERIAL_GET_MODEMSTATUS 要求をサポートする必要があります。 この要求のドライバーのハンドラーは、シリアル コントローラー ハードウェアから読み取られた未加工のモデム状態レジスタ値に要求の出力値を設定する必要があります。

IOCTL_SERIAL_GET_HANDFLOWとIOCTL_SERIAL_SET_HANDFLOW

シリアル コントローラー ドライバーの EvtSerCx2Control 関数は、IOCTL_SERIAL_GET_HANDFLOW 要求と IOCTL_SERIAL_SET_HANDFLOW 要求をサポートする必要がありますが、これらの要求に対して定義されているフラグ ビットのサブセットのみをサポートする必要があります。 フラグ ビットは、ControlHandShake に対して定義され、FlowReplace これらの要求で使用される SERIAL_HANDFLOW 構造体のメンバーを します。

ドライバーは、ControlHandshake メンバーで次のフラグ ビットをサポートする必要があります。

  • SERIAL_CTS_HANDSHAKE
オプションとして、ドライバーは、ControlHandshake メンバーに対して定義されている他のフラグ ビットのいずれかをサポートできます。

ドライバーは、FlowReplace メンバーで次のフラグ ビットをサポートする必要があります。

  • SERIAL_RTS_CONTROL
  • SERIAL_RTS_HANDSHAKE
オプションとして、ドライバーは、FlowReplace メンバーに対して定義されている他のフラグ ビットのいずれかをサポートできます。 ただし、これらの他のフラグ ビットが必要な場合はほとんどなく、Microsoft ではサポートを推奨しています。

ControlHandShake または FlowReplace メンバーの特定のフラグ ビット をサポートしていないドライバーは、IOCTL_SERIAL_GET_HANDFLOW 要求の出力値でこのフラグ ビットを 0 に設定する必要があります。 IOCTL_SERIAL_SET_HANDFLOW 要求で、ドライバーがサポートしていない ControlHandshake または FlowReplace フラグ ビット 指定した場合、EvtSerCx2Control 関数は要求を失敗させ、STATUS_INVALID_PARAMETERを返す必要があります。

オプションとして、ドライバーは XonLimit をサポートし、SERIAL_HANDFLOW 構造体の XoffLimit メンバーを できます。 ただし、これらのメンバーが必要になることはほとんどなく、Microsoft ではサポートを推奨しません。 XonLimit および XoffLimit メンバー サポートしていないドライバーは、IOCTL_SERIAL_GET_HANDFLOW 要求の出力値でこれらのメンバーを 0 に設定する必要があります。 IOCTL_SERIAL_SET_HANDFLOW 要求で XonLimit または XoffLimit メンバー 0 以外の を指定し、ドライバーがこれらのメンバーをサポートしていない場合、EvtSerCx2Control 関数は要求に失敗し、STATUS_NOT_IMPLEMENTEDを返す必要があります。

例

EvtSerCx2Control コールバック関数 定義するには、まず、定義するコールバック関数の型を識別する関数宣言を指定する必要があります。 Windows には、ドライバーのコールバック関数の種類のセットが用意されています。 コールバック関数の種類を使用して関数を宣言すると、ドライバーのコード分析、静的ドライバー検証ツール (SDV)、およびその他の検証ツールを すると、エラーが検出され、Windows オペレーティング システムのドライバーを記述するための要件になります。

たとえば、MyControlという名前の EvtSerCx2Control コールバック関数を定義するには、次のコード例に示すように、EVT_SERCX2_CONTROL 関数型を使用します。

EVT_SERCX2_CONTROL  MyControl;

次に、次のようにコールバック関数を実装します。

_Use_decl_annotations_
NTSTATUS
  MyControl(
    WDFDEVICE  Device,
    WDFREQUEST  Request,
    size_t  OutputBufferLength,
    size_t  InputBufferLength,
    ULONG  IoControlCode
    )
  {...}

EVT_SERCX2_CONTROL 関数型は、Sercx.h ヘッダー ファイルで定義されています。 コード分析ツールの実行時にエラーをより正確に識別するには、Use_decl_annotations 注釈を関数定義に追加してください。 Use_decl_annotations 注釈により、ヘッダー ファイル内の EVT_SERCX2_CONTROL 関数型に適用される注釈が確実に使用されます。 関数宣言の要件の詳細については、「KMDF ドライバーの関数ロール型を使用して関数を宣言する」を参照してください。 Use_decl_annotationsの詳細については、「関数の動作に注釈を付ける」を参照してください。

必要条件

要件 価値
サポートされる最小クライアント Windows 8.1以降で使用できます。
ターゲット プラットフォーム の デスクトップ
ヘッダー sercx.h
IRQL IRQL <= DISPATCH_LEVEL で呼び出されます。

関連項目

EvtDriverDeviceAdd の

EvtSerCx2ApplyConfig の

EvtSerCx2PurgeFifos の

EvtSerCx2SetWaitMask

SERIAL_COMMPROP

SERIAL_EV_XXX

SERIAL_HANDFLOW

SERIAL_STATUS

SerCx2InitializeDevice の