EVT_SERCX2_SELECT_NEXT_RECEIVE_TRANSACTION_TYPE コールバック関数 (sercx.h)
EvtSerCx2SelectNextReceiveTransactionType イベント コールバック関数は、シリアル フレームワーク拡張機能 (SerCx2) のバージョン 2 によって呼び出され、次の読み取り操作に使用するデータ転送メカニズムを決定します。
構文
EVT_SERCX2_SELECT_NEXT_RECEIVE_TRANSACTION_TYPE EvtSercx2SelectNextReceiveTransactionType;
SERCX2_TRANSACTION_TYPE EvtSercx2SelectNextReceiveTransactionType(
[in] WDFDEVICE Device,
[in] PMDL Mdl,
[in] ULONG Offset,
[in] ULONG RemainingLength,
[out] SERCX2CUSTOMRECEIVE *CustomReceive,
[out] PULONG NextTransactionLength
)
{...}
パラメーター
[in] Device
シリアル コントローラーを表すフレームワーク デバイス オブジェクトへの WDFDEVICE ハンドル。 シリアル コントローラー ドライバーは、 EvtDriverDeviceAdd コールバック関数でこのオブジェクトを作成しました。 詳細については、「 SerCx2InitializeDevice」を参照してください。
[in] Mdl
次の受信トランザクションの読み取りバッファーによってまたがっているメモリ ページを記述する MDL へのポインター。 DMA 転送の散布/収集リストでは、 Offset パラメーターと Length パラメーターで指定されたこのメモリの領域が使用されます。
[in] Offset
次のデータ転送の開始オフセット。 このパラメーターは、MDL によって記述されたバッファー領域の先頭からのバイト オフセットです。 MDL でバッファー領域の合計 N バイトが指定されている場合、 Offset の使用可能な値は 0 から N から 1 の範囲です。
[in] RemainingLength
現在の読み取り (IRP_MJ_READ) 要求で転送されるデータの合計バイト数。 MDL でバッファー領域の合計 N バイトが指定されている場合、 Length の使用可能な値は 1 から N–Offset の範囲です。
[out] CustomReceive
関数がカスタム受信オブジェクトに SERCX2CUSTOMRECEIVE ハンドルを書き込む場所へのポインター。 関数が SerCx2TransactionTypeCustom を返す場合、関数は 、SerCx2CustomReceiveCreate メソッドの以前の呼び出しでシリアル コントローラー ドライバーが作成したオブジェクト ハンドルを指定する必要があります。 戻り値が SerCx2TransactionTypeCustom でない場合、この出力値は SerCx2 では無視されます。
[out] NextTransactionLength
関数が次の受信トランザクションで転送するバイト数を書き込む場所へのポインター。 戻り値が SerCx2TransactionTypeDefault の場合、この出力値は SerCx2 では無視されます。
戻り値
EvtSerCx2SelectNextReceiveTransactionType 関数は、ドライバーが選択したトランザクションの種類 (プログラムされた I/O (PIO)、システム DMA、またはカスタム データ転送) を使用するか、SerCx2 が次の受信トランザクションに使用するトランザクションの種類を選択するかを示すSERCX2_TRANSACTION_TYPE列挙定数を返します。
注釈
シリアル コントローラー ドライバーでは、オプションとしてこの関数を実装できます。 実装されている場合、ドライバーは、シリアル コントローラーのフレームワーク デバイス オブジェクトの初期化を完了する SerCx2InitializeDevice メソッドの呼び出しにこの関数を登録します。
シリアル コントローラー ドライバーが EvtSerCx2SelectNextReceiveTransactionType 関数を実装していない場合、SerCx2 は常に、次の受信トランザクションに使用するデータ転送メカニズムの種類 (PIO、システム DMA、またはカスタム) を決定します。 SerCx2 は、シリアル コントローラー ドライバーによって提供される I/O 構成情報に基づいて決定します。 システム DMA 受信トランザクションをサポートするドライバーは、この情報を含む SERCX2_SYSTEM_DMA_RECEIVE_CONFIG 構造を提供します。 カスタム受信トランザクションをサポートするドライバーは、この情報を含む SERCX2_CUSTOM_RECEIVE_CONFIG 構造を提供します。
シリアル コントローラー ドライバーが EvtSerCx2SelectNextReceiveTransactionType 関数を実装している場合、SerCx2 はこの関数を呼び出して、次の受信トランザクションに使用するデータ転送メカニズム (PIO、システム DMA、またはカスタム) の種類を決定します。 シリアル コントローラーに、 SERCX2_XXX_RECEIVE_CONFIG 構造体の I/O 構成情報で適切に記述できない特別なハードウェア機能がある場合は、この関数を実装できます。
例
EvtSerCx2CustomReceiveSelectNextTransactionType コールバック関数を定義するには、まず、定義するコールバック関数の種類を識別する関数宣言を指定する必要があります。 Windows には、ドライバーのコールバック関数の種類のセットが用意されています。 コールバック関数の種類を使用して関数を宣言すると、ドライバー、静的ドライバー検証ツール (SDV)、およびその他の検証ツールのコード分析でエラーが検出され、Windows オペレーティング システム用のドライバーを記述するための要件になります。
たとえば、 という名前MyCustomReceiveSelectNextTransactionTypeの EvtSerCx2CustomReceiveSelectNextTransactionType コールバック関数を定義するには、次のコード例に示すように、EVT_SERCX2_CUSTOM_RECEIVE_SELECT_NEXT_TRANSACTION_TYPE関数型を使用します。
EVT_SERCX2_CUSTOM_RECEIVE_SELECT_NEXT_TRANSACTION_TYPE MyCustomReceiveTransactionStart;
次に、コールバック関数を次のように実装します。
_Use_decl_annotations_
SERCX2_TRANSACTION_TYPE
EvtSerCx2SelectNextReceiveTransactionType(
WDFDEVICE Device,
PMDL Mdl,
ULONG Offset,
ULONG RemainingLength,
SERCX2CUSTOMRECEIVE *CustomReceive,
PULONG NextTransactionLength
)
{...}
EVT_SERCX2_CUSTOM_RECEIVE_SELECT_NEXT_TRANSACTION_TYPE関数型は、Sercx.h ヘッダー ファイルで定義されています。 コード分析ツールを実行するときにエラーをより正確に識別するには、 Use_decl_annotations 注釈を関数定義に追加してください。 Use_decl_annotations注釈を使用すると、ヘッダー ファイル内のEVT_SERCX2_CUSTOM_RECEIVE_SELECT_NEXT_TRANSACTION_TYPE関数型に適用される注釈が確実に使用されます。 関数宣言の要件の詳細については、「 KMDF ドライバーの関数ロール型を使用した関数の宣言」を参照してください。 Use_decl_annotationsの詳細については、「関数の動作に注釈を付ける」を参照してください。
要件
| 要件 | 値 |
|---|---|
| サポートされている最小のクライアント | Windows 8.1以降で使用できます。 |
| 対象プラットフォーム | デスクトップ |
| Header | sercx.h |
| IRQL | IRQL <= DISPATCH_LEVELで呼び出されます。 |