PROTOCOL_BIND_ADAPTER_EX回呼函式 (ndis.h)

發行項
02/26/2024

NDIS 會呼叫通訊協定驅動程式的 ProtocolBindAdapterEx 函式，要求驅動程式系結至迷你埠配接器。

注意您必須使用 PROTOCOL_BIND_ADAPTER_EX 類型來宣告函式。如需詳細資訊，請參閱下列範例一節。

語法

PROTOCOL_BIND_ADAPTER_EX ProtocolBindAdapterEx;

NDIS_STATUS ProtocolBindAdapterEx(
  [in] NDIS_HANDLE ProtocolDriverContext,
  [in] NDIS_HANDLE BindContext,
  [in] PNDIS_BIND_PARAMETERS BindParameters
)
{...}

參數

[in] ProtocolDriverContext

驅動程式所配置內容區域的句柄，其中驅動程式會維護狀態和設定資訊。通訊協定驅動程式將此內容區域傳遞至 NdisRegisterProtocolDriver 函式。

[in] BindContext

識別這個系結作業之 NDIS 內容區域的句柄。

[in] BindParameters

NDIS 所建立 NDIS_BIND_PARAMETERS 結構的指標。

傳回值

ProtocolBindAdapterEx 會傳回下列其中一個狀態值：

傳回碼	Description
NDIS_STATUS_SUCCESS	ProtocolBindAdapterEx 已成功完成基礎迷你埠配接器的系結。
NDIS_STATUS_PENDING	ProtocolBindAdapterEx 未完成系結作業，且作業會以異步方式完成。通訊協定驅動程序必須呼叫作業完成時，NdisCompleteBindAdapterEx 函式。
NDIS_STATUS_RESOURCES	ProtocolBindAdapterEx 無法配置驅動程式執行網路 I/O 作業所需的資源。
NDIS_STATUS_XXX或NTSTATUS_XXX	通訊協定驅動程式嘗試設定系結失敗。通常，這類錯誤狀態會從 NdisXxx 函式或內核模式支援例程傳播。

備註

ProtocolBindAdapterEx 是必要函式。 NDIS 會呼叫 ProtocolBindAdapterEx ，以在通訊協定驅動程式可以系結的基礎迷你埠配接器可供使用時執行系結作業。

ProtocolBindAdapterEx 會配置足夠的記憶體來維護系結內容資訊，並呼叫 NdisOpenAdapterEx 函式，將本身系結至基礎迷你埠配接器。 ProtocolBindAdapterEx 會在 NdisOpenAdapterEx 的 ProtocolBindingContext 參數傳遞系結內容資訊的指標。 ProtocolBindAdapterEx 會從 BindParameters 參數傳遞 AdapterName 成員的值作為 NdisOpenAdapterExOpenParameters 參數的 AdapterName 成員。

在驅動程式呼叫 NdisOpenAdapterEx 之前，驅動程式可以將 BindParameters 的指標傳遞至 NdisOpenConfigurationEx 函式，以讀取與迷你埠配接器相關聯的組態參數。

成功開啟迷你埠配接器之後，驅動程式可以從 NdisOpenAdapterEx 的 NdisHandle 參數將句柄傳遞至 NdisOpenConfigurationEx，以取得儲存通訊協定系結之組態參數的登錄位置句柄。

ProtocolBindAdapterEx 會將 NdisOpenAdapterEx 指標傳遞給中型類型值的陣列，其中列出通訊協定驅動程式可支援的媒體類型。此清單是 NDIS_MEDIUM 類型的子集。 NDIS 表示在 OpenParameters 結構之 SelectedMediumIndex 參數上選取的中型類型。

如果 NdisOpenAdapterEx 傳回錯誤狀態， ProtocolBindAdapterEx 會傳回該錯誤狀態、釋放通訊協定驅動程式配置的任何個別系結資源，並立即傳回控制權。

如果 NdisOpenAdapterEx 傳回 NDIS_STATUS_SUCCESS，ProtocolBindAdapterEx 可以配置通訊協定驅動程式在繫結上執行網路 I/O 所需的剩餘資源。驅動程式也可以設定驅動程式用來追蹤網路 I/O 作業的任何系結特定內容資訊。

如果 NdisOpenAdapterEx 傳回NDIS_STATUS_PENDING，NDIS 會呼叫通訊協定驅動程式的開啟作業完成後的 ProtocolOpenAdapterCompleteEx 函式。 ProtocolOpenAdapterCompleteEx 可以完成系結作業。 ProtocolBindAdapterEx 可以將 BindContext 句柄儲存在系結內容區域中。 NDIS 會將 ProtocolBindingContext 作為輸入參數傳遞至驅動程式的 ProtocolOpenAdapterCompleteEx 函 式。

如果 NdisOpenAdapterEx 傳回NDIS_STATUS_PENDING，NDIS 會在 OpenParameters 參數設定結構的 SelectedMediumIndex 成員，並在 NdisOpenAdapterEx 傳回之後的 NdisBindingHandle 參數值。 NDIS 會在呼叫 ProtocolOpenAdapterCompleteEx 之前設定這些值。因此，通訊協定驅動程式必須儲存開啟的參數結構，而通訊協定系結句柄必須儲存在 ProtocolBindingContext (的內容區域中，或任何有效的位置，直到 NDIS 呼叫 ProtocolOpenAdapterCompleteEx) 為止。

在開啟作業完成之前，通訊協定驅動程式無法在系結上提出 OID 要求。由於系結在開啟作業完成後處於暫停狀態，因此通訊協定驅動程式在 NDIS 重新啟動系結之前，無法傳送要求。

開啟作業完成之後， ProtocolBindAdapterEx 可以傳回NDIS_STATUS_SUCCESS來完成系結作業。 ProtocolBindAdapterEx 可以傳回NDIS_STATUS_PENDING，將系結作業完成延遲到稍後的時間。如果 ProtocolBindAdapterEx 傳回NDIS_STATUS_PENDING，驅動程式必須呼叫系結作業完成後的 NdisCompleteBindAdapterEx 函式。

通訊協定驅動程式應該使用 NDIS_BIND_PARAMETERS 結構來判斷基礎迷你埠適配卡的功能。開啟作業完成之後，通訊協定驅動程式可以根據基礎媒體呼叫 NdisOidRequest 函式來查詢基礎迷你埠驅動程式 (或 NDIS) 有關其他迷你埠適配卡功能。如需 OID 要求的詳細資訊，請參閱通訊協定驅動程式 OID 要求。

NDIS 可以呼叫通訊協定驅動程式的在驅動程式設定與系結的封包篩選器之後的 ProtocolReceiveNetBufferLists 函式 OID_GEN_CURRENT_PACKET_FILTER 老。如果基礎迷你埠配接器未針對傳入封包使用封包篩選器，則開啟作業完成後會啟用接收指示。通訊協定驅動程式可以在開啟作業完成後收到 ProtocolStatusEx 函式的狀態指示。

每個通訊協定驅動程式都應該配置足夠的 NET_BUFFER 和 NET_BUFFER_LIST 結構集區。驅動程式會從這些集區配置網路數據描述元，以供後續傳送作業使用。

如果 ProtocolBindAdapterEx 無法配置它執行後續網路 I/O 作業所需的資源，它應該釋放它已配置的所有資源，並傳回適當的錯誤值。

NDIS 會呼叫通訊協定驅動程式的 ProtocolUnbindAdapterEx 函式，要求驅動程序從基礎迷你埠配接器解除系結。

例如，如果通訊協定驅動程式成功開啟迷你埠配接器，但系結作業失敗 (例如，因為 OID 要求失敗) ，驅動程式必須從 ProtocolBindAdapterEx 或 ProtocolUnbindAdapterEx 的內容中關閉迷你埠配接器。例如，驅動程式會從 ProtocolBindAdapterEx 呼叫 NdisCloseAdapterEx，並等候關閉作業在驅動程式從 ProtocolBindAdapterEx 傳回之前完成。或者，如果驅動程式從 ProtocolBindAdapterEx 傳回NDIS_STATUS_PENDING，驅動程式就可以呼叫 NdisUnbindAdapter 函式，並在 ProtocolUnbindAdapterEx 函式中呼叫 NdisCloseAdapterEx。

NDIS 會在 IRQL = PASSIVE_LEVEL呼叫 ProtocolBindAdapterEx 。

例子

若要定義 ProtocolBindAdapterEx 函式，您必須先提供函式宣告來識別您要定義的函式類型。 Windows 提供一組驅動程式的函式類型。使用函式類型宣告函式有助於驅動程式的程式代碼分析、靜態驅動程式驗證程式 (SDV) ，以及其他驗證工具尋找錯誤，而且是撰寫 Windows 作業系統驅動程式的需求。

例如，若要定義名為「 MyBindAdapterEx」的 ProtocolBindAdapterEx 函 式，請使用 PROTOCOL_BIND_ADAPTER_EX 類型，如下列程式代碼範例所示：

PROTOCOL_BIND_ADAPTER_EX MyBindAdapterEx;

然後，實作您的函式，如下所示：

_Use_decl_annotations_
NDIS_STATUS
 MyBindAdapterEx(
    NDIS_HANDLE  ProtocolDriverContext,
    NDIS_HANDLE  BindContext,
    PNDIS_BIND_PARAMETERS  BindParameters
    )
  {...}

PROTOCOL_BIND_ADAPTER_EX函式類型定義於 Ndis.h 頭檔中。若要在執行程式代碼分析工具時更精確地識別錯誤，請務必將 Use_decl_annotations 批註新增至函式定義。 Use_decl_annotations批註可確保使用頭檔中套用至PROTOCOL_BIND_ADAPTER_EX函式類型的註釋。如需函數宣告需求的詳細資訊，請參閱使用 NDIS 驅動程式的函式角色類型來宣告函式。

如需 Use_decl_annotations的詳細資訊，請參閱標註函式行為。