PROTOCOL_CL_REGISTER_SAP_COMPLETE回呼函式 (ndis.h)

發行項
02/26/2024

接受連入呼叫的連接導向 NDIS 用戶端必須具有 ProtocolClRegisterSapComplete 函式，才能完成以 NdisClRegisterSap 起始的異步操作。否則，這類通訊協定驅動程式的已註冊 ProtocolClRegisterSapComplete 函式可以直接傳回控制權。

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

語法

PROTOCOL_CL_REGISTER_SAP_COMPLETE ProtocolClRegisterSapComplete;

void ProtocolClRegisterSapComplete(
  [in] NDIS_STATUS Status,
  [in] NDIS_HANDLE ProtocolSapContext,
  [in] PCO_SAP Sap,
  [in] NDIS_HANDLE NdisSapHandle
)
{...}

參數

[in] Status

指定用戶端呼叫 NdisClRegisterSap 的最終狀態，可以是下列其中一項：

NDIS_STATUS_SUCCESS

SAP 已向 NDIS 和呼叫管理員註冊，後續會呼叫每當收到導向至指定 SAP 的來電供應專案時，NdisCmDispatchIncomingCall，因而導致 NDIS 呼叫用戶端的 ProtocolClIncomingCall 函式。

NDIS_STATUS_RESOURCES

NDIS 或呼叫管理員無法配置和/或初始化必要的資源來註冊和維護 SAP。

NDIS_STATUS_INVALID_DATA

用戶端在 Sap 提供給 NDIS 時提供無效的規格，而該規格會轉送至呼叫管理員的 ProtocolCmRegisterSap 函式以進行驗證。

NDIS_STATUS_XXX

呼叫管理員嘗試註冊指定的 SAP 和 NDIS 時發生錯誤，會將此 CM 判斷失敗狀態傳播至用戶端。

[in] ProtocolSapContext

指定用戶端每個 SAP 內容區域的句柄，用戶端最初在呼叫 NdisClRegisterSap 時提供給 NDIS。如果註冊成功，NDIS 會保留此內容句柄，並在後續呼叫與此 SAP 相關的用戶端 ProtocolClIncomingCall 函式時使用它。

[in] Sap

用戶端配置的緩衝區指標，其中包含要開啟之 SAP 的規格。用戶端最初將此指標傳遞至 NdisClRegisterSap。

[in] NdisSapHandle

如果 Status 是NDIS_STATUS_SUCCESS，請為此已註冊的 SAP 指定 NDIS 提供的有效句柄，有效地與用戶端與用戶端指定 SAP 的特定呼叫管理員之間建立的 NDIS 關聯。否則，此參數為 NULL。客戶端必須儲存有效的句柄，最好是在其 ProtocolSapContext 區域中，才能最終呼叫 NdisClDeregisterSap。

傳回值

無

備註

NDIS 會呼叫 ProtocolClRegisterSapComplete，指出用戶端先前對 NdisClRegisterSap 的呼叫已由 NDIS 處理，如果 NDIS 未失敗呼叫，用戶端會與其共用其傳遞給 NdisClRegisterSap 的 NdisAfHandle 呼叫。

若要透過連線導向的 NIC 接收來電，用戶端的 ProtocolCoAfRegisterNotify 或 ProtocolClOpenAfCompleteEx 函式通常會向呼叫管理員註冊一或多個 SA。

若要註冊每個 SAP，用戶端會呼叫 NdisClRegisterSap、傳入 NdisAfHandle ，以識別用戶端想要接收來電通知的呼叫管理員，而 NDIS 會將 NdisSapHandle 傳回用戶端，如果用戶端呼叫 NdisClRegisterSap 成功，則會將 NdisSapHandle 傳回至已註冊的 SAP。 ProtocolClRegisterSapComplete 必須儲存每個有效的 NdisSapHandle，通常是在用戶端的每個 SAP ProtocolSapContext 區域中，以便稍後使用 NdisClDeregisterSap 釋放 SAP。

SAP 的格式專屬於呼叫管理員。如果呼叫管理員無法辨識客戶端嘗試註冊的 SAP，或指定的 SAP 已在使用中，呼叫管理員可能會使 SAP 註冊失敗。 ProtocolClRegisterSapComplete 應該先檢查輸入狀態是否有NDIS_STATUS_SUCCESS，然後再進一步處理。如果嘗試註冊 SAP 失敗，
ProtocolClRegisterSapComplete 可以在 Sap 上釋放用戶端所配置的個別 SAP 內容區域和緩衝區，或準備在 NdisClRegisterSap 的另一個呼叫中重複使用它們。

即使 SAP 註冊仍在擱置中，用戶端仍然可以在 SAP 上接收連入呼叫，也就是說，在呼叫其 ProtocolClRegisterSapComplete 函式之前。

例子

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

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

PROTOCOL_CL_REGISTER_SAP_COMPLETE MyClRegisterSapComplete;

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

_Use_decl_annotations_
VOID
 MyClRegisterSapComplete(
    NDIS_STATUS  Status,
    NDIS_HANDLE  ProtocolSapContext,
    PCO_SAP  Sap,
    NDIS_HANDLE  NdisSapHandle
    )
  {...}

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

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

規格需求

需求	值
最低支援的用戶端	支援 NDIS 6.0 和 NDIS 5.1 驅動程式 (請參閱 Windows Vista 中的 ProtocolClRegisterSapComplete (NDIS 5.1) ) 。支援 NDIS 5.1 驅動程式 (請參閱 Windows XP 中的 ProtocolClRegisterSapComplete (NDIS 5.1) ) 。
目標平台	Windows
標頭	ndis.h (包含 Ndis.h)
IRQL	<= DISPATCH_LEVEL