EVT_SPB_TARGET_CONNECT コールバック関数 (spbcx.h)

[アーティクル]
08/07/2023

SPB コントローラードライバーの EvtSpbTargetConnect イベントコールバック関数は、バス上のターゲットデバイスへの接続を開きます。

構文

EVT_SPB_TARGET_CONNECT EvtSpbTargetConnect;

NTSTATUS EvtSpbTargetConnect(
  [in] WDFDEVICE Controller,
  [in] SPBTARGET Target
)
{...}

パラメーター

[in] Controller

SPB コントローラーを表すフレームワークデバイスオブジェクトへの WDFDEVICE ハンドル。

[in] Target

開くターゲットへの SPBTARGET ハンドル。ターゲットは、バスに接続されている周辺機器またはポートです。

戻り値

ドライバーがターゲットへの接続を正常に開いた場合、EvtSpbTargetConnect はSTATUS_SUCCESSを返します。それ以外の場合、関数は適切な NTSTATUS エラーコードを返します。

注釈

SPB コントローラードライバーによるこの関数の実装は省略可能です。

SPB フレームワーク拡張機能 (SpbCx) は、SPB コントローラーの I/O キューを管理します。 SPB コントローラードライバーが EvtSpbTargetConnect コールバック関数を登録する場合、SpbCx は、コントローラーのクライアント (周辺機器ドライバー) がバス上のターゲットデバイスへの接続を開く IRP_MJ_CREATE 要求を送信するときに、この関数を呼び出します。 EvtSpbTargetConnect 関数がエラーコードを返した場合、SpbCx はIRP_MJ_CREATE要求に失敗します。ターゲットへの接続を正常に開いたクライアントは、接続が閉じられるまでターゲットへの排他的アクセス権を持っています。

SpbTargetGetConnectionParameters メソッドを呼び出して、ターゲットデバイスの接続パラメーターを取得します。通常、SPB コントローラードライバーは、ドライバーの EvtSpbTargetConnect 関数からこのメソッドを呼び出します。 SpbTargetGetConnectionParameters は、呼び出し元が指定した SPB_CONNECTION_PARAMETERS 構造体に接続パラメーターを書き込みます。この構造体の ConnectionParameters メンバーは、ターゲットデバイスの接続設定を含むバッファーへのポインターです。ドライバーは、これらの設定を使用して、デバイスと通信するように SPB コントローラーを構成します。詳細については、「デバイスの接続設定を取得する方法」を参照してください。

EvtSpbTargetConnect コールバック関数は、ターゲットへの接続を要求するクライアントスレッドのコンテキストから同期的に呼び出されます。

SpbCx は EvtSpbTargetDisconnect コールバック関数を呼び出して、 EvtSpbTargetConnect コールバックによって以前に開かれたターゲット接続を閉じます。

EvtSpbTargetConnect コールバック関数を登録するには、SpbDeviceInitialize メソッドを呼び出します。

例

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

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

EVT_SPB_TARGET_CONNECT  MyEvtSpbTargetConnect;

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

_Use_decl_annotations_
NTSTATUS
  MyEvtSpbTargetConnect(
    WDFDEVICE Controller,
    SPBTARGET Target
    )
{ ... }

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

要件

要件	値
サポートされている最小のクライアント	Windows 8 以降でサポートされています。
対象プラットフォーム	デスクトップ
Header	spbcx.h
IRQL	PASSIVE_LEVELで呼び出されます。