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

[アーティクル]
02/26/2024

EvtSerCx2CustomReceiveTransactionStart イベントコールバック関数は、シリアルフレームワーク拡張機能 (SerCx2) のバージョン 2 によって呼び出され、カスタム受信トランザクションを開始します。

構文

EVT_SERCX2_CUSTOM_RECEIVE_TRANSACTION_START EvtSercx2CustomReceiveTransactionStart;

void EvtSercx2CustomReceiveTransactionStart(
  [in] SERCX2CUSTOMRECEIVETRANSACTION CustomReceiveTransaction,
  [in] WDFREQUEST Request,
  [in] PMDL Mdl,
  [in] ULONG Offset,
  [in] ULONG Length
)
{...}

パラメーター

[in] CustomReceiveTransaction

カスタム receive-transaction オブジェクトへの SERCX2CUSTOMRECEIVETRANSACTION ハンドル。シリアルコントローラードライバーは、このオブジェクトを作成するために SerCx2CustomReceiveTransactionCreate メソッドを以前に呼び出しました。

[in] Request

カスタム受信トランザクションに関連付けられているフレームワーク要求オブジェクトへのハンドル。ドライバーは、この要求を完了する責任があります。この要求はクライアントから送信された IRP_MJ_READ 要求ではない可能性があるため、シリアルコントローラードライバーはこの要求を使用して読み取りバッファーにアクセスしないでください。この要求は、主にキャンセル、完了、およびキュー転送に使用されます (必要な場合)。クライアントの読み取り要求の読み取りバッファーにアクセスするには、 Mdl、 Offset、 Length の各パラメーターを使用します。

[in] Mdl

カスタム受信トランザクションの読み取りバッファーにまたがっているメモリページを記述する MDL へのポインター。データ転送の散布/収集リストでは、 Offset パラメーターと Length パラメーターで指定されたこのメモリの領域が使用されます。

[in] Offset

データ転送の開始オフセット。このパラメーターは、MDL によって記述されたバッファー領域の先頭からのバイトオフセットです。 MDL でバッファー領域の合計 N バイトが指定されている場合、 Offset の有効な値は 0 から N から 1 の範囲になります。

[in] Length

データ転送のサイズ (バイト単位)。 MDL でバッファー領域の N バイトの合計が指定されている場合、 Length の使用可能な値は 1 から N – Offset の範囲になります。

戻り値

なし

解説

シリアルコントローラードライバーは、カスタム受信トランザクションオブジェクトを作成する場合、この関数を実装する必要があります。ドライバーは、このオブジェクトを作成する SerCx2CustomReceiveTransactionCreate 呼び出しに関数を登録します。

SerCx2 が EvtSerCx2CustomReceiveTransactionStart 関数を呼び出した後、シリアルコントローラードライバーは、シリアルコントローラーハードウェアの受信 FIFO から読み取り要求のバッファーにデータを移動するカスタムデータ転送メカニズムをプログラミングしてトランザクションを開始します。要求をすぐに完了できない限り、 EvtSerCx2CustomReceiveTransactionStart 関数が戻る前に、ドライバーは WdfRequestMarkCancelableEx などのメソッドを呼び出して要求を取り消し可能としてマークする必要があります。

EvtSerCx2CustomReceiveTransactionStart 関数がトランザクションを開始すると、SerCx2 は定期的に EvtSerCx2CustomReceiveTransactionQueryProgress イベントコールバック関数を呼び出して、シリアルコントローラードライバーによるこのトランザクションの実行の進行状況を監視します。トランザクションが完了し、ドライバーが保留中の読み取り要求を完了すると、SerCx2 は EvtSerCx2CustomReceiveTransactionCleanup イベントコールバック関数を呼び出します (ドライバーがこの関数を実装している場合)。

シリアルコントローラードライバーが EvtSerCx2CustomReceiveTransactionInitialize イベントコールバック関数を実装している場合、SerCx2 は EvtSerCx2CustomReceiveTransactionStart 関数を呼び出す前にこの関数を呼び出します。 EvtSerCx2CustomReceiveTransactionStart 呼び出しの直前に、EvtSerCx2CustomReceiveTransactionInitialize 呼び出しが返された後、SerCx2 は読み取り要求がタイムアウトするかどうかを検出するタイマーを開始します。詳細については、SERIAL_TIMEOUTSの合計タイムアウトの説明を参照してください。

カスタムデータ転送メカニズムがバスマスター DMA デバイスの場合、 EvtSerCx2CustomReceiveTransactionStart 関数は WdfDmaTransactionInitializeUsingOffset などのメソッドを呼び出して、 Mdl、 Offset、 Length パラメーターによって記述された読み取りバッファーを使用する DMA トランザクションを開始できます。

Request パラメーターで識別される要求オブジェクトにプライベートコンテキストのストレージが含まれている場合、シリアルコントローラードライバーがコンテキストに初めてアクセスする際に、このストレージが初期化されていない可能性があります。最初のアクセスでは、ドライバーは通常、0 でコンテキストを入力し、必要に応じて、0 以外の初期値を必要とするコンテキスト内のフィールドを明示的に設定する必要があります。

詳細については、「 SerCx2 Custom-Receive トランザクション」を参照してください。

例

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

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

EVT_SERCX2_CUSTOM_RECEIVE_TRANSACTION_START  MyCustomReceiveTransactionStart;

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

_Use_decl_annotations_
VOID
  MyCustomReceiveTransactionStart(
    SERCX2CUSTOMRECEIVETRANSACTION  CustomReceiveTransaction,
    WDFREQUEST  Request,
    PMDL  Mdl,
    ULONG  Offset,
    ULONG  Length
    )
  {...}

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

要件

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