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

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

構文

EVT_SERCX2_CUSTOM_TRANSMIT_TRANSACTION_START EvtSercx2CustomTransmitTransactionStart;

void EvtSercx2CustomTransmitTransactionStart(
  [in] SERCX2CUSTOMTRANSMITTRANSACTION CustomTransmitTransaction,
  [in] WDFREQUEST Request,
  [in] PMDL Mdl,
  [in] ULONG Offset,
  [in] ULONG Length
)
{...}

パラメーター

[in] CustomTransmitTransaction

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

[in] Request

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

[in] Mdl

カスタム送信トランザクションの書き込みバッファーによってスパンされるメモリ ページを記述する MDL へのポインター。 DMA 転送の散布図/収集リストでは、Offset および Length パラメーターで指定されたこのメモリの領域が使用されます。 MDL チェーンの詳細については、「MDLの使用」を参照してください。

[in] Offset

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

[in] Length

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

戻り値

何一つ

備考

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

SerCx2 が evtSerCx2CustomTransmitTransactionStart 関数 呼び出した後、シリアル コントローラー ドライバーは、書き込み要求のバッファーからシリアル コントローラー ハードウェアの送信 FIFO にデータを移動するカスタム データ転送メカニズムをプログラミングしてトランザクションを開始します。 要求をすぐに完了できる場合を除き、EvtSerCx2CustomTransmitTransactionStart 関数が返される前に、ドライバーは、WdfRequestMarkCancelableEx などのメソッドを呼び出して、要求をキャンセル可能としてマークする必要があります。

トランザクションが完了し、ドライバーが保留中の書き込み要求を完了した後、SerCx2 は、EvtSerCx2CustomTransmitTransactionCleanup イベント コールバック関数を呼び出します (ドライバーがこの関数を実装している場合)。

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

シリアル コントローラー ドライバーは、送信 FIFO の最後のバイトがシリアル接続周辺機器に送信された後にのみ、保留中の書き込み要求を完了する必要があります。 送信 FIFO に書き込まれたデータが大幅な遅延なしで送信されることは保証されず、このような保証が存在することを前提とするシリアル コントローラー ドライバーは、周辺機器ドライバーの信頼性の問題を引き起こす可能性があります。

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

Mdl、Offset、および Length パラメーターの詳細については、「EvtSerCx2CustomTransmitTransactionInitializeの解説」を参照してください。

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

詳細については、「SerCx2 Custom-Transmit Transactions」を参照してください。

例

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

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

EVT_SERCX2_CUSTOM_TRANSMIT_TRANSACTION_START  MyCustomTransmitTransactionStart;

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

_Use_decl_annotations_
VOID
  MyCustomTransmitTransactionStart(
    SERCX2CUSTOMTRANSMITTRANSACTION  CustomTransmitTransaction,
    WDFREQUEST  Request,
    PMDL  Mdl,
    ULONG  Offset,
    ULONG  Length
    )
  {...}

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

必要条件

関連項目

EvtSerCx2CustomTransmitTransactionCleanup を する

EvtSerCx2CustomTransmitTransactionInitialize の

IRP_MJ_WRITE

MDL を する

SERCX2CUSTOMTRANSMITTRANSACTION

SERIAL_TIMEOUTS

SerCx2CustomTransmitTransactionCreate の

WdfDmaTransactionInitializeUsingOffset

WdfRequestMarkCancelableEx の