EVT_SERCX2_SET_WAIT_MASK コールバック関数 (sercx.h)
EvtSerCx2SetWaitMask イベント コールバック関数は、シリアル フレームワーク拡張機能 (SerCx2) のバージョン 2 によって呼び出され、待機マスクで指定されたハードウェア イベントのセットを監視するようにシリアル コントローラーを構成します。
構文
EVT_SERCX2_SET_WAIT_MASK EvtSercx2SetWaitMask;
void EvtSercx2SetWaitMask(
[in] WDFDEVICE Device,
[in] WDFREQUEST Request,
[in] ULONG WaitMask
)
{...}
パラメーター
[in] Device
シリアル コントローラーを表すフレームワーク デバイス オブジェクトへの WDFDEVICE ハンドル。 シリアル コントローラー ドライバーは、 EvtDriverDeviceAdd コールバック関数でこのオブジェクトを作成しました。 詳細については、「 SerCx2InitializeDevice」を参照してください。
[in] Request
IOCTL_SERIAL_SET_WAIT_MASK要求を表すフレームワーク要求オブジェクトに対する WDFREQUEST ハンドル。
[in] WaitMask
新しい待機マスク。 詳細については、「解説」を参照してください。
戻り値
なし
解説
シリアル コントローラー ドライバーでは、オプションとしてこの関数を実装できます。 実装されている場合、ドライバーは、シリアル コントローラーのフレームワーク デバイス オブジェクトの初期化を完了する SerCx2InitializeDevice メソッドの呼び出しに関数を登録します。
SerCx がクライアントから IOCTL_SERIAL_SET_WAIT_MASK 要求を受信すると、SerCx2 の要求ハンドラーは EvtSerCx2SetWaitMask 関数を呼び出して実装されている場合は、待機マスクが変更されたことをドライバーに通知します。 待機マスクが 0 以外の場合、ドライバーはすぐに新しい待機マスク内のイベントの監視を開始し、以前 の EvtSerCx2SetWaitMask 呼び出しで指定されていた古い待機マスクを破棄します。 新しい待機マスクが 0 の場合、ドライバーは古い待機マスクを破棄し、待機マスク イベントの監視を停止します。 待機マスクで指定できるイベントの種類の詳細については、「 SERIAL_EV_XXX」を参照してください。
ドライバーがこの関数を実装していない場合、SerCx2 はエラー状態コードSTATUS_NOT_SUPPORTEDを使用してすべての IOCTL_SERIAL_SET_WAIT_MASK 要求に失敗します。
待機マスク内のイベントを監視するために、 EvtSerCx2SetWaitMask 関数は通常、これらのイベントの割り込みを有効にします。 その後、待機マスク内のイベントが検出されると、シリアル コントローラー ドライバーは SerCx2CompleteWait メソッドを呼び出して、SerCx2 にイベントを通知します。
EvtSerCx2SetWaitMask 関数は、Request パラメーターが指すIOCTL_SERIAL_SET_WAIT_MASK要求を完了する役割を担います。 シリアル コントローラー ドライバーは、必要な割り込みを有効にした後、 WdfRequestComplete メソッドを呼び出し、入力パラメーターとして Request パラメーター値と状態値を指定して、要求が成功したかどうかを示します。
シリアル コントローラー ドライバーが WdfRequestComplete を呼び出して要求を完了する前に、ドライバーは、古い待機マスクのイベントが原因で保留中である可能性がある SerCx2CompleteWait への呼び出しを完了する必要があります。
最初に、クライアントがシリアル ポートへの論理接続を開き、最初 の EvtSerCx2SetWaitMask 呼び出しの前に待機マスクは実質的にゼロになり、シリアル コントローラー ドライバーは SERIAL_EV_XXX イベントを監視しません。
SerCx2 は、次の SERIAL_EV_XXX イベント フラグのいずれかを含む待機マスクを持つIOCTL_SERIAL_SET_WAIT_MASK要求 に 失敗します。
- SERIAL_EV_PERR
- SERIAL_EV_RING
- SERIAL_EV_RXFLAG
実装されている場合、 EvtSerCx2SetWaitMask 関数は次のイベント フラグをサポートする必要があります。
- SERIAL_EV_CTS
- SERIAL_EV_BREAK
- SERIAL_EV_ERR
例
EvtSerCx2SetWaitMask コールバック関数を定義するには、まず、定義するコールバック関数の種類を識別する関数宣言を指定する必要があります。 Windows には、ドライバーのコールバック関数の種類のセットが用意されています。 コールバック関数の種類を使用して関数を宣言すると、ドライバー、静的ドライバー検証ツール (SDV)、およびその他の検証ツールのコード分析でエラーが検出され、Windows オペレーティング システム用のドライバーを記述するための要件になります。
たとえば、 という名前MySetWaitmaskの EvtSerCx2SetWaitMask コールバック関数を定義するには、次のコード例に示すように、EVT_SERCX2_SET_WAIT_MASK関数型を使用します。
EVT_SERCX2_SET_WAIT_MASK MySetWaitmask;
次に、コールバック関数を次のように実装します。
_Use_decl_annotations_
VOID
MySetWaitmask(
WDFDEVICE Device,
WDFREQUEST Request,
ULONG WaitMask
)
{...}
EVT_SERCX2_SET_WAIT_MASK関数型は、Sercx.h ヘッダー ファイルで定義されています。 コード分析ツールを実行するときにエラーをより正確に識別するには、 Use_decl_annotations 注釈を関数定義に追加してください。 Use_decl_annotations注釈を使用すると、ヘッダー ファイル内のEVT_SERCX2_SET_WAIT_MASK関数型に適用される注釈が確実に使用されます。 関数宣言の要件の詳細については、「 KMDF ドライバーの関数ロール型を使用した関数の宣言」を参照してください。 Use_decl_annotationsの詳細については、「関数の動作に注釈を付ける」を参照してください。
要件
| 要件 | 値 |
|---|---|
| サポートされている最小のクライアント | Windows 8.1以降で使用できます。 |
| 対象プラットフォーム | デスクトップ |
| Header | sercx.h |
| IRQL | IRQL <= DISPATCH_LEVELで呼び出されます。 |