PROTOCOL_UNBIND_ADAPTER_EX回呼函式 (ndis.h)

發行項
03/01/2024

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

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

語法

PROTOCOL_UNBIND_ADAPTER_EX ProtocolUnbindAdapterEx;

NDIS_STATUS ProtocolUnbindAdapterEx(
  [in] NDIS_HANDLE UnbindContext,
  [in] NDIS_HANDLE ProtocolBindingContext
)
{...}

參數

[in] UnbindContext

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

[in] ProtocolBindingContext

通訊協定驅動程式所配置之內容區域的句柄。通訊協定驅動程式會在此內容區域中維護每個系結內容資訊。驅動程式在驅動程式呼叫 NdisOpenAdapterEx 函式時，提供此句柄給 NDIS。

傳回值

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

傳回碼	Description
NDIS_STATUS_SUCCESS	ProtocolUnbindAdapterEx 已成功從基礎迷你埠配接器取消系結。
NDIS_STATUS_PENDING	ProtocolUnbindAdapterEx 未完成解除系結作業，且作業會以異步方式完成。通訊協定驅動程序必須呼叫解除系結作業完成後的 NdisCompleteUnbindAdapterEx 函式。

備註

ProtocolUnbindAdapterEx 是必要函式。做為 ProtocolBindAdapterEx 函式的倒數，NDIS 會呼叫 ProtocolUnbindAdapterEx 來釋放驅動程式為系結專用的網路 I/O 作業配置的資源。通訊協定驅動程式無法失敗解除系結的作業。

在呼叫 ProtocolUnbindAdapterEx 之前，NDIS 會暫停通訊協議系結。若要暫停系結，NDIS 會呼叫 ProtocolNetPnPEvent 函式，並指定 NetEventPause 事件。

ProtocolUnbindAdapterEx 必須呼叫 NdisCloseAdapterEx 函式，以關閉與基礎迷你埠配接器的系結。如果 NdisCloseAdapterEx 傳回NDIS_STATUS_SUCCESS，則關閉作業已完成。如果 NdisCloseAdapterEx 傳回NDIS_STATUS_PENDING，NDIS 會呼叫通訊協定驅動程式的完成關閉作業之後的 ProtocolCloseAdapterCompleteEx 函式。

在呼叫 NdisCloseAdapterEx 之前，通訊協定驅動程式應該清除系結的多播位址清單和封包篩選器。通訊協定驅動程式會將系結多播位址清單設定為 NULL，並將封包篩選設定為零。如需詳細資訊，請參閱 OID_802_3_MULTICAST_LIST 和 OID_GEN_CURRENT_PACKET_FILTER。

如果已指定喚醒模式，通訊協定驅動程式應該使用 OID_PNP_REMOVE_WAKE_UP_PATTERN OID 移除它，並使用 OID_GEN_RECEIVE_SCALE_PARAMETERS OID 清除接收端調整參數。 NDIS 6.20 和更新版本的通訊協定驅動程式應該移除具有 OID_PM_REMOVE_WOL_PATTERN OID 的喚醒網路模式，並移除與 OID_PM_REMOVE_PROTOCOL_OFFLOAD OID 一起卸除的低電源通訊協定。

ProtocolUnbindAdapterEx 在 ProtocolBindingContext 上不得釋放記憶體，直到關閉作業完成為止。 NDIS 會將 ProtocolBindingContext 的句柄傳遞至 ProtocolCloseAdapterCompleteEx。

如果通訊協議驅動程式已完成解除系結作業， ProtocolUnbindAdapterEx 可以傳回NDIS_STATUS_SUCCESS。如果 NdisCloseAdapterEx 傳回 NDIS_STATUS_PENDING，ProtocolUnbindAdapterEx 必須先等候 NDIS 呼叫 ProtocolCloseAdapterCompleteEx ，才能傳回NDIS_STATUS_SUCCESS。

ProtocolUnbindAdapterEx 可以傳回NDIS_STATUS_PENDING，以將解除系結作業完成延遲到稍後的時間。如果 ProtocolUnbindAdapterEx 傳回NDIS_STATUS_PENDING，驅動程式最終必須呼叫 NdisCompleteUnbindAdapterEx 函式以完成解除系結作業。如果傳回的 NdisCloseAdapterEx 函式NDIS_STATUS_PENDING，驅動程式可以在 ProtocolCloseAdapterCompleteEx 中完成解除系結作業。 ProtocolUnbindAdapterEx 可以在 ProtocolBindingContext 的內容區域中將句柄儲存在 ProtocolBindingContext，然後再呼叫 NdisCloseAdapterEx。如果 ProtocolUnbindAdapterEx 儲存了句柄， ProtocolCloseAdapterCompleteEx 可以將句柄傳遞至 NdisCompleteUnbindAdapterEx 來完成解除系結作業。

一旦 ProtocolUnbindAdapterEx 呼叫 NdisCloseAdapterEx，從 NdisOpenAdapterEx 函式取得的句柄就會變成無效。 ProtocolUnbindAdapterEx 無法使用此句柄對 NdisXxx 函式進行任何後續呼叫。驅動程式可以從基礎迷你埠配接器取得接收和狀態指示，直到關閉作業完成為止。

NDIS 會在 IRQL = PASSIVE_LEVEL呼叫 ProtocolUnbindAdapterEx 。

更新電源管理和 RSS 設定

NDIS 6.0 和 6.1 通訊協定驅動程式應該在適用的情況下執行下列作業：

從具有的迷你埠適配卡移除 LAN (WOL) 模式的電源管理喚醒 OID_PNP_REMOVE_WAKE_UP_PATTERN 老。
使用清除接收端調整參數 OID_GEN_RECEIVE_SCALE_PARAMETERS 老。

NDIS 6.20 和更新版本的通訊協定驅動程式應該執行下列作業：

使用 OID_PM_REMOVE_WOL_PATTERN OID，從迷你埠適配卡中移除電源管理 WOL 模式。
使用從迷你埠配接器移除電源管理通訊協定卸除 OID_PM_REMOVE_PROTOCOL_OFFLOAD 老。

例子

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

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

PROTOCOL_UNBIND_ADAPTER_EX MyUnbindAdapterEx;

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

_Use_decl_annotations_
NDIS_STATUS
 MyUnbindAdapterEx(
    NDIS_HANDLE  UnbindContext,
    NDIS_HANDLE  ProtocolBindingContext
    )
  {...}

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

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