PROTOCOL_CM_REG_SAP回呼函式（ndis.h）

發行項
02/07/2025

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

Note 您必須使用 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 會傳回其作業的狀態，如下所示：

傳回碼	描述
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指定註冊 SAP。這類動作可能包括，但不限於與交換硬體通訊、與網路控制站通訊，或適用於網路媒體的其他動作。

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

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

如果 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的相關信息，請參閱批注函式行為。

要求

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