PROTOCOL_CM_REG_SAP回呼函式 (ndis.h)

發行項
02/26/2024

ProtocolCmRegisterSap 函式是 NDIS 呼叫的必要函式，要求呼叫管理員代表連線導向客戶端註冊 SAP (服務存取點) 。

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

語法

PROTOCOL_CM_REG_SAP ProtocolCmRegSap;

NDIS_STATUS ProtocolCmRegSap(
  [in]  NDIS_HANDLE CallMgrAfContext,
  [in]  PCO_SAP Sap,
  [in]  NDIS_HANDLE NdisSapHandle,
  [out] PNDIS_HANDLE CallMgrSapContext
)
{...}

參數

[in] CallMgrAfContext

指定呼叫管理員所配置內容區域的句柄，而呼叫管理員會維護其個別開啟的 AF 狀態。呼叫管理員從其 ProtocolCmOpenAf 函式提供此句柄給 NDIS。

[in] Sap

媒體特定CO_SAP結構的指標，其中包含連接導向用戶端所註冊的特定SAP。

[in] NdisSapHandle

指定 NDIS 所提供的句柄，可唯一識別此 SAP。此句柄對呼叫管理員不透明，並保留給 NDIS 連結庫使用。

[out] CallMgrSapContext

傳回時，指定呼叫管理員提供之內容區域的句柄，而呼叫管理員會維護此 SAP 的狀態。

傳回值

ProtocolCmRegisterSap 會傳回其作業的狀態 (s) ，如下所示：

傳回碼	Description
NDIS_STATUS_SUCCESS	表示呼叫管理員已成功配置和/或初始化任何必要的資源，以註冊和維護 SAP。此外，它也會指出呼叫管理員所支援的網路媒體已成功註冊 SAP。
NDIS_STATUS_PENDING	表示呼叫管理員會以異步方式完成此要求的處理。通話管理員必須呼叫當所有處理都已完成時，NdisCmRegisterSapComplete 會向 NDIS 發出註冊完成的訊號。
NDIS_STATUS_RESOURCES	表示呼叫管理員無法配置和/或初始化其代表連線導向客戶端註冊 SAP 所需的資源。
NDIS_STATUS_INVALID_DATA	表示 Sap 提供的規格無效或無法支援。
NDIS_STATUS_XXX	表示呼叫管理員嘗試註冊連線導向用戶端的 SAP 時發生錯誤。傳回碼適用於錯誤，而且可能是從另一個 NDIS 連結庫函式傳播的傳回碼。

備註

ProtocolCmMakeCall 會視需要與網路控制裝置或其他媒體特定代理程序通訊，以在網路上為聯機導向客戶端註冊 SAP。這類動作可能包括，但不限於與切換硬體通訊、與網路控制站通訊，或適用於網路媒體的其他動作。

如果需要呼叫管理員與網路控制代理程式通訊， (換句話說，網路交換器) 它應該使用它在其 ProtocolBindAdapterEx 函式中建立的網路控制代理程式的虛擬連線。獨立呼叫管理員會透過基礎迷你埠驅動程序來通訊，方法是呼叫 NdisCoSendNetBufferLists。具有整合式呼叫管理支援的迷你埠驅動程序永遠不會呼叫 NdisCoSendNetBufferLists。相反地，它們會直接透過網路傳輸數據。

此外， ProtocolCmRegisterSap 應該執行任何必要的動態資源和結構配置，呼叫管理員必須代表連線導向客戶端維護 SAP 的狀態資訊。這類資源包括但不限於記憶體緩衝區、數據結構、事件和其他類似的資源。呼叫管理員也必須初始化它配置的任何資源，再將控制權傳回 NDIS。呼叫管理員必須儲存 NDIS 提供的句柄，以識別 在 NdisSapHandle 提供的 SAP，以供日後使用。

如果 ProtocolCmRegisterSap 會傳回NDIS_STATUS_SUCCESS，則應該在配置每個 SAP 狀態區域之後，在 CallMgrSapContext 中設定此狀態區域的位址，再將控制權傳回 NDIS。若要這樣做，請取值 CallMgrSapContext ，並將數據區域的指標儲存為句柄的值。例如：

*CallMgrSapContext = SomeBuffer ;

如果已由另一個連線導向客戶端註冊的指定 SAP，呼叫管理員必須失敗要求，並傳回NDIS_STATUS_INVALID_DATA。

呼叫管理員代表連線導向客戶端註冊 SAP 之後，它會透過呼叫通知傳入呼叫供應專案的客戶端導向至該 SAP NdisCmDispatchIncomingCall。

例子

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

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

PROTOCOL_CM_REG_SAP MyCmRegisterSap;

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

_Use_decl_annotations_
NDIS_STATUS
 MyCmRegisterSap(
    NDIS_HANDLE  CallMgrAfContext,
    PCO_SAP  Sap,
    NDIS_HANDLE  NdisSapHandle,
    PNDIS_HANDLE  CallMgrSapContext
    )
  {...}

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

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

規格需求

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