SerCx2CustomTransmitCreate 関数 (sercx.h)

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

SerCx2CustomTransmitCreate メソッドは、カスタム転送オブジェクトを作成します。このオブジェクトは、シリアルフレームワーク拡張機能 (SerCx2) のバージョン 2 が、カスタムデータ転送メカニズムを使用してシリアルコントローラーに送信データを書き込むのに使用します。

構文

NTSTATUS SerCx2CustomTransmitCreate(
  [in]  WDFDEVICE                      Device,
  [in]  PSERCX2_CUSTOM_TRANSMIT_CONFIG CustomTransmitConfig,
  [in]  PWDF_OBJECT_ATTRIBUTES         Attributes,
  [out] SERCX2CUSTOMTRANSMIT           *CustomTransmit
);

パラメーター

[in] Device

シリアルコントローラーを表すフレームワークデバイスオブジェクトへの WDFDEVICE ハンドル。シリアルコントローラードライバーは、EvtDriverDeviceAdd コールバック関数でこのオブジェクトを作成しました。詳細については、「SerCx2InitializeDevice」を参照してください。

[in] CustomTransmitConfig

SERCX2_CUSTOM_TRANSMIT_CONFIG 構造体へのポインター。このメソッドを呼び出す前に、呼び出し元は SERCX2_CUSTOM_TRANSMIT_CONFIG_INIT 関数を呼び出して構造体を初期化する必要があります。この構造体には、シリアルコントローラードライバーによって実装されるイベントコールバックルーチンのセットへのポインターが含まれています。 SerCx2 はこれらの関数を呼び出して、カスタム送信トランザクションを実行します。

[in] Attributes

新しいカスタム送信オブジェクトに割り当てる属性を記述する WDF_OBJECT_ATTRIBUTES 構造体へのポインター。このメソッドを呼び出す前に、呼び出し元は WDF_OBJECT_ATTRIBUTES_INIT 関数を呼び出して構造体を初期化する必要があります。このパラメーターは省略可能であり、シリアルコントローラードライバーがオブジェクトに属性を割り当てる必要がない場合は、WDF_NO_OBJECT_ATTRIBUTESとして指定できます。詳細については、「解説」を参照してください。

[out] CustomTransmit

このメソッドが新しく作成したカスタム送信オブジェクトに SERCX2CUSTOMTRANSMIT ハンドルを書き込む場所へのポインター。 SerCx2 とシリアルコントローラードライバーは、このオブジェクトを参照する後続の呼び出しでこのハンドルを使用します。

戻り値

このメソッドは、呼び出しが成功した場合にSTATUS_SUCCESSを返します。考えられるエラー戻り値には、次の状態コードが含まれます。

リターンコード	形容
STATUS_INVALID_DEVICE_REQUEST	カスタム送信オブジェクトは、前の SerCx2CustomTransmitCreate 呼び出しから既に存在します。または、前の SerCx2SystemDmaTransmitCreate 呼び出しからシステム DMA 送信オブジェクトが存在する。または、前の SerCx2SystemDmaTransmitCreate 呼び出しからシステム DMA 送信オブジェクトが存在する。または serCx2PioTransmitCreate PIO 送信オブジェクトを作成するためにまだ呼び出されていません。
STATUS_INVALID_PARAMETER	パラメーター値が無効です。
STATUS_INFO_LENGTH_MISMATCH	ConfigSize 値が sizeof(SERCX2_CUSTOM_TRANSMIT_CONFIG) 等しくありません。
STATUS_INSUFFICIENT_RESOURCES	カスタム送信オブジェクトの作成に使用できるリソースが不足しています。

備考

このメソッドは、カスタム送信オブジェクトを作成するシリアルコントローラードライバーによって呼び出されます。 SerCx2 は、このオブジェクトを使用してカスタム送信トランザクションを実行します。これは、カスタムデータ転送メカニズムを使用してシリアルコントローラーに送信データを書き込むトランザクションです。

シリアルコントローラードライバーは、SerCx2CustomTransmitCreateを呼び出す前に、SerCx2PioTransmitCreate メソッドを SerCx2InitializeDevice と正常に呼び出す必要があります。

SerCx2CustomTransmitCreate呼び出す前に、シリアルコントローラードライバーは SERCX2_CUSTOM_TRANSMIT_CONFIG_INIT 関数を呼び出して、CustomTransmitConfigが指す SERCX2_CUSTOM_TRANSMIT_CONFIG 構造体初期化する必要があります。この関数は、構造体の次のメンバーを 0 に設定します。

配置
MinimumTransactionLength
MaximumTransactionLength
MinimumTransferUnit の
排他

必要に応じて、シリアルコントローラードライバーは、初期化関数が返された後、これらのメンバーのいずれかを 0 以外の値に設定できます。ただし、便宜上、SerCx2CustomTransmitCreate これらのメンバーが 0 の場合、次の既定値が使用されます。

Alignment が 0 の場合、SerCx2 はデータアラインメント値を 1 に設定します。つまり、書き込みバッファーはメモリ内の任意のバイト境界から開始できます。
MinimumTransactionLength が 0 の場合、SerCx2 は最小トランザクション長を 1 バイトに設定します。
MaximumTransactionLength が 0 の場合、SerCx2 は最大トランザクション長を ((ULONG)-1 に設定します。
MinimumTransferUnit ゼロの場合、SerCx2 は最小転送単位を 1 バイトに設定します。
排他ゼロ (FALSE) の場合、排他モードは無効になります。

呼び出し元のドライバー排他を TRUEに設定する場合は、minimumTransferUnit、Alignment、および MinimumTransactionLength メンバー 0 を指定する必要があります。詳細については、SERCX2_CUSTOM_TRANSMIT_CONFIGを参照してください。

オプションとして、シリアルコントローラードライバーは、Attributes パラメーターを使用して、カスタム送信オブジェクトのコンテキストを作成し、EvtCleanupCallback へのポインターを提供し、EvtDestroyCallback 関数をして、削除の準備を行うことができます。詳細については、WDF_OBJECT_ATTRIBUTESを参照してください。

属性パラメーターが WDF_OBJECT_ATTRIBUTES 構造体を指している場合、呼び出し元は、WDF_OBJECT_ATTRIBUTES_INIT 初期化関数が ParentObject、ExecutionLevel、およびこの構造体の SynchronizationScope メンバーに書き込む値を上書きしてはなりません。

カスタム送信オブジェクトの作成の詳細については、SERCX2CUSTOMTRANSMITを参照してください。カスタム送信トランザクションの詳細については、「SerCx2 Custom-Transmit Transactions」を参照してください。

必要条件

要件	価値
サポートされる最小クライアント	Windows 8.1以降で使用できます。
ターゲットプラットフォームの	万国
ヘッダー	sercx.h
IRQL	PASSIVE_LEVEL

次の方法で共有

SerCx2CustomTransmitCreate 関数 (sercx.h)

構文

パラメーター

戻り値

備考

必要条件

関連項目

フィードバック

その他のリソース