PROTOCOL_CL_OPEN_AF_COMPLETE_EX回呼函式 (ndis.h)

發行項
02/26/2024

ProtocolClOpenAfCompleteEx 函式會完成當 CoNDIS 用戶端呼叫 NdisClOpenAddressFamilyEx 函式時所啟動的位址系列 (AF) 。

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

語法

PROTOCOL_CL_OPEN_AF_COMPLETE_EX ProtocolClOpenAfCompleteEx;

void ProtocolClOpenAfCompleteEx(
  [in] NDIS_HANDLE ProtocolAfContext,
  [in] NDIS_HANDLE NdisAfHandle,
  [in] NDIS_STATUS Status
)
{...}

參數

[in] ProtocolAfContext

用戶端針對位址 AF 的內容區域提供句柄。用戶端已配置此內容區域，並將此句柄傳遞至其對的呼叫中的 NDIS NdisClOpenAddressFamilyEx 函式。

[in] NdisAfHandle

如果狀態 NDIS_STATUS_SUCCESS，則為 AF 提供的 NDIS 句柄。否則，此參數為 NULL。此句柄代表用戶端與系結至 CoNDIS 迷你埠配接器之呼叫管理員之間建立的 NDIS 關聯。如果句柄不是 NULL，客戶端必須儲存句柄，以供 後續呼叫 NdisClXxx 和 NdisCoXxx 函式使用。

[in] Status

用戶端對 NdisClOpenAddressFamilyEx 呼叫的最終狀態，可以是下列任一項：

NDIS_STATUS_SUCCESS

AF 已開啟，因此用戶端可以在 ProtocolAfContext 初始化其狀態，並在後續對 NdisClXxx 和 NdisCoXxx 函式的呼叫中使用來自 NdisAfHandle 的傳回句柄，例如 NdisCoOidRequest。

NDIS_STATUS_RESOURCES

要求的作業失敗，因為 NDIS 或呼叫管理員無法配置足夠的記憶體，或初始化其中一個用來追蹤 ProtocolAfContext 所指定 AF 的 AF 狀態。

NDIS_STATUS_FAILURE

NDIS 失敗呼叫，可能是下列其中一個原因：

指定的 AF 不符合針對呼叫端所系結之基礎迷你埠驅動程式所註冊的任何 AF。
呼叫端的配接器系結正在關閉。
註冊指定 AF 的呼叫管理員正在關閉其系結至基礎迷你埠配接器。

傳回值

無

備註

CoNDIS 用戶端需要 ProtocolClOpenAfCompleteEx 函式。 CoNDIS 用戶端必須提供 ProtocolClOpenAfCompleteEx ，才能完成客戶端藉由呼叫來起始的異步操作 NdisClOpenAddressFamilyEx 函式。

NDIS 會呼叫 ProtocolClOpenAfCompleteEx ，指出已發生下列部分或所有專案：

如果用戶端的所有參數傳遞至 NdisClOpenAddressFamilyEx 函式的 ProtocolCoAfRegisterNotify 函式是有效的，NDIS 稱為呼叫管理員的 ProtocolCmOpenAf 函式，該函式只會向 NDIS 註冊指定的 AF。
呼叫管理員已檢查用戶端的 ProtocolCoAfRegisterNotify 函式在 AddressFamily 參數傳遞至 NdisClOpenAddressFamilyEx 的規格，並傳回此呼叫管理員是否對 NDIS 有效。

如果客戶端嘗試開啟 AF 失敗，NDIS 會在呼叫 ProtocolClOpenAfCompleteEx 之前清除其已儲存的狀態。在此情況下， ProtocolClOpenAfCompleteEx 可以釋放用戶端為其呼叫 NdisClOpenAddressFamilyEx 所配置的資源，或準備重複使用它們。

否則， ProtocolClOpenAfCompleteEx 應該設定用戶端在新開啟 AF 上後續作業所需的任何客戶端決定狀態。特別是，客戶端必須從 NdisAfHandle 參數儲存句柄，通常是在用戶端的 ProtocolAfContext 內容區域中。

如果用戶端接受傳入呼叫，它可能會配置每個服務存取點 (SAP) 狀態區域，並呼叫 NdisClRegisterSap 函式。如果客戶端進行傳出呼叫，它可能會配置每個虛擬連線 (VC) 狀態區域，並使用 NdisCoCreateVc 函式建立 VC，以準備來自其中一個用戶端的傳入要求，以對遠端節點進行傳出呼叫。

NDIS 會在 IRQL = PASSIVE_LEVEL呼叫 ProtocolClOpenAfCompleteEx 。

例子

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

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

PROTOCOL_CL_OPEN_AF_COMPLETE_EX MyClOpenAfCompleteEx;

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

_Use_decl_annotations_
VOID
 MyClOpenAfCompleteEx(
    NDIS_HANDLE  ProtocolAfContext,
    NDIS_HANDLE  NdisAfHandle,
    NDIS_STATUS  Status
    )
  {...}

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

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