EVT_SPB_TARGET_CONNECT回呼函式 (spbcx.h)

發行項
03/01/2024

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的詳細資訊，請參閱標註函式行為。