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

[アーティクル]
10/30/2024

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 呼び出しの前に待機マスクは実質的に 0 になり、シリアルコントローラードライバーは SERIAL_EV_XXX イベントを監視しません。

SerCx2 は、次の SERIAL_EV_XXX イベントフラグのいずれかを含む待機マスクを持つ IOCTL_SERIAL_SET_WAIT_MASK 要求に失敗します。

SERIAL_EV_PERR
SERIAL_EV_RING
SERIAL_EV_RXFLAG

したがって、EvtSerCx2SetWaitMask 関数に提供される待機マスクには、前の一覧のイベントフラグが含まれることはありません。

実装されている場合、EvtSerCx2SetWaitMask 関数は、次のイベントフラグをサポートする必要があります。

SERIAL_EV_CTS
SERIAL_EV_BREAK
SERIAL_EV_ERR

また、シリアルコントローラーに データセット ready (DSR) 信号ラインがある場合、EvtSerCx2SetWaitMask 関数はSERIAL_EV_DSRをサポートする必要があります。オプションとして、ドライバーは、SERIAL_EV_XXXで説明されている他のイベントフラグのいずれかをサポートできます。待機マスクでドライバーがサポートしていないイベントが指定されている場合、EvtSerCx2SetWaitMask 関数は要求を失敗させ、要求の状態値をSTATUS_INVALID_PARAMETERに設定する必要があります。

例

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

たとえば、という名前の MySetWaitmask コールバック関数を定義するには、次のコード例に示すように、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以降で使用できます。
ターゲットプラットフォームの	デスクトップ
ヘッダー	sercx.h
IRQL	IRQL <= DISPATCH_LEVEL で呼び出されます。

次の方法で共有

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

構文

パラメーター

戻り値

備考

例

必要条件

関連項目

フィードバック

その他のリソース