EVT_SERCX2_CUSTOM_RECEIVE_TRANSACTION_START コールバック関数 (sercx.h)
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
カスタム受信トランザクション オブジェクトへの 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 –オフセットの範囲になります。
戻り値
何一つ
備考
シリアル コントローラー ドライバーは、カスタムの受信トランザクション オブジェクトを作成する場合、この関数を実装する必要があります。 ドライバーは、このオブジェクトを作成する SerCx2CustomReceiveTransactionCreate 呼び出しに関数を登録します。
SerCx2 が EvtSerCx2CustomReceiveTransactionStart 関数を呼び出した後、シリアル コントローラー ドライバーは、シリアル コントローラー ハードウェアの受信 FIFO から読み取り要求のバッファーにデータを移動するカスタム データ転送メカニズムをプログラミングしてトランザクションを開始します。 要求をすぐに完了できない限り、EvtSerCx2CustomReceiveTransactionStart 関数が戻る前に、ドライバーは、WdfRequestMarkCancelableEx などのメソッドを呼び出して、要求をキャンセル可能としてマークする必要があります。
EvtSerCx2CustomReceiveTransactionStart 関数がトランザクションを開始すると、SerCx2 は定期的に EvtSerCx2CustomReceiveTransactionQueryProgress イベント コールバック関数を呼び出して、シリアル コントローラー ドライバーによるこのトランザクションの実行の進行状況を監視します。 トランザクションが完了し、ドライバーが保留中の読み取り要求を完了すると、SerCx2 は、EvtSerCx2CustomReceiveTransactionCleanup イベント コールバック関数を呼び出します (ドライバーがこの関数を実装している場合)。
シリアル コントローラー ドライバーがイベント コールバック関数 EvtSerCx2CustomReceiveTransactionInitialize
カスタム データ転送メカニズムがバス マスター DMA デバイスの場合、 EvtSerCx2CustomReceiveTransactionStart 関数は、WdfDmaTransactionInitializeUsingOffset などのメソッドを呼び出して、Mdl、Offset、および Length パラメーターによって記述された読み取りバッファーを使用する DMA トランザクションを開始できます。
Request パラメーターによって識別される要求オブジェクトにプライベート コンテキストのストレージが含まれている場合、シリアル コントローラー ドライバーが最初にコンテキストにアクセスする際に、このストレージが初期化されていない可能性があります。 最初のアクセスでは、ドライバーは通常、0 でコンテキストを入力する必要がありますし、必要に応じて、0 以外の初期値を必要とするコンテキスト内のフィールドを明示的に設定します。
詳細については、「SerCx2 Custom-Receive Transactions」を参照してください。
例
EvtSerCx2CustomReceiveTransactionStart コールバック関数
たとえば、という名前の MyCustomReceiveTransactionStart コールバック関数を定義するには、次のコード例に示すように、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以降で使用できます。 |
| ターゲット プラットフォーム の |
デスクトップ |
| ヘッダー | sercx.h |
| IRQL | IRQL <= DISPATCH_LEVEL で呼び出されます。 |
関連項目
MDL を
SERCX2CUSTOMRECEIVETRANSACTION
SerCx2CustomReceiveTransactionCreate
WdfDmaTransactionInitializeUsingOffset
WdfRequestMarkCancelableEx の