PROTOCOL_CM_CLOSE_CALL回呼函式 (ndis.h)

  • 發行項

ProtocolCmCloseCall 函式是終止現有呼叫的必要函式，並釋放呼叫管理員配置給呼叫的任何資源。

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

語法

PROTOCOL_CM_CLOSE_CALL ProtocolCmCloseCall;

NDIS_STATUS ProtocolCmCloseCall(
  [in]           NDIS_HANDLE CallMgrVcContext,
  [in, optional] NDIS_HANDLE CallMgrPartyContext,
  [in, optional] PVOID CloseData,
  [in, optional] UINT Size
)
{...}

參數

[in] CallMgrVcContext

指定呼叫管理員所配置內容區域的句柄，其中呼叫管理員會維護其每個 VC 狀態。 此句柄已從呼叫管理員 ProtocolCmMakeCall 函式 提供給 NDIS。

[in, optional] CallMgrPartyContext

指定呼叫管理員在多點 VC 上維護合作對象相關信息的呼叫管理員配置內容區域的句柄。 如果關閉的呼叫不是多點呼叫，則此句柄為 NULL 。

[in, optional] CloseData

緩衝區的指標，其中包含應該在呼叫終止之前跨連線傳送的連接導向用戶端指定數據。 如果基礎網路媒體不支援在關閉連線時傳輸數據，此參數為 NULL 。

[in, optional] Size

指定 CloseData 為 NULL時緩衝區的長度，以位元組為單位。

傳回值

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

傳回碼 Description
NDIS_STATUS_SUCCESS
 表示呼叫管理員已成功終止通話。
NDIS_STATUS_PENDING
 表示呼叫管理員會完成以異步方式終止呼叫的要求。 當呼叫管理員完成終止連線所需的所有作業時，必須接著呼叫 NdisCmCloseCallComplete ，以向 NDIS 發出已關閉呼叫的訊號。
NDIS_STATUS_INVALID_DATA
 指出已指定 CloseData ，但基礎網路媒體不支援在終止呼叫時同時傳送數據。
NDIS_STATUS_XXX
 表示呼叫管理員無法終止通話。 傳回的實際錯誤可能是從另一個 NDIS 連結庫例程傳播的狀態。

備註

ProtocolCmCloseCall 與網路控制裝置或其他媒體特定動作專案通訊，因為其媒體需要終止本機節點與遠端節點之間的連線。 如果需要呼叫管理員與網路控制裝置通訊， (例如網路交換器) 它應該使用其 ProtocolBindAdapterEx 函式中所建立的網路控制裝置虛擬連線。 獨立呼叫管理員會呼叫 NdisCoSendNetBufferLists 來與這類網路裝置通訊。 具有整合式呼叫管理支援的迷你埠驅動程序永遠不會呼叫 NdisCoSendNetBufferLists。 相反地，它們會直接透過網路傳輸數據。

如果 CloseData 不是 NULL ，而且此呼叫管理員所處理的媒體支援在連線終止時傳送數據，則呼叫管理員應該先將 CloseData 中指定的數據傳送至遠端節點，再完成呼叫終止。 如果不支援與終止連線同時傳送數據，則呼叫管理員應該傳回NDIS_STATUS_INVALID_DATA。

如果 ProtocolCmCloseCall 傳遞明確的 CallMgrPartyContext，則終止的呼叫會是多點 VC，而呼叫管理員必須視其媒體類型執行與網路硬體的任何必要網路通訊，以終止呼叫做為多點呼叫。 呼叫管理員也必須釋放稍早在 ProtocolCmMakeCall 中配置記憶體，以取得 CallMgrPartyContext 所指向的每個合作對象狀態。 無法正確釋放、解除分配或停用這些資源會導致記憶體流失。

呼叫終止網路之後，任何關閉的數據都已傳送，而 CallMgrPartyContext 的任何資源都已釋出，呼叫管理員必須呼叫 NdisCmDeactivateVc。 這會通知 NDIS 和基礎迷你埠驅動程式，如果有的話，預期在指定的 VC 上不會進一步傳輸。

例子

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

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

PROTOCOL_CM_CLOSE_CALL MyCmCloseCall;

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

_Use_decl_annotations_
NDIS_STATUS
 MyCmCloseCall(
    NDIS_HANDLE  CallMgrVcContext,
    NDIS_HANDLE  CallMgrPartyContext,
    PVOID  CloseData,
    UINT  Size
    )
  {...}

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

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

規格需求

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

另請參閱

NdisClMakeCall

NdisCmDeactivateVc

NdisCoSendNetBufferLists

ProtocolCmMakeCall