PROTOCOL_CL_MAKE_CALL_COMPLETE回呼函式 (ndis.h)

發行項
04/30/2024

ProtocolClMakeCallComplete 函式是由進行傳出呼叫的連接導向 NDIS 用戶端使用。這類客戶端必須具有 ProtocolClMakeCallComplete 函式，才能完成它們以 NdisClMakeCall 起始的異步操作。否則，這類通訊協定驅動程式的已註冊 ProtocolClMakeCallComplete 函式可以直接傳回控制權。

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

語法

PROTOCOL_CL_MAKE_CALL_COMPLETE ProtocolClMakeCallComplete;

void ProtocolClMakeCallComplete(
  [in]           NDIS_STATUS Status,
  [in]           NDIS_HANDLE ProtocolVcContext,
  [in, optional] NDIS_HANDLE NdisPartyHandle,
  [in]           PCO_CALL_PARAMETERS CallParameters
)
{...}

參數

[in] Status

指定用戶端對 NdisClMakeCall 之原始呼叫的最終狀態，可以是下列其中一項：

NDIS_STATUS_SUCCESS

用戶端嘗試設定虛擬連線成功。因此，用戶端可以使用 NdisCoCreateVc 所傳回的 NdisVcHandle，繼續在作用中 VC 上進行傳輸，用戶端已將其每個 VC 內容區域儲存在 ProtocolVcContext 。

NDIS_STATUS_RESOURCES

NDIS、呼叫管理員或基礎驅動程式無法配置足夠的資源來設定連線。

NDIS_STATUS_XXX

呼叫管理員或基礎迷你埠驅動程式無法建立作用中的連線，而 NDIS 會將此驅動程式判斷的失敗狀態傳播至用戶端。

[in] ProtocolVcContext

指定用戶端每個 VC 內容區域的句柄，用戶端最初在呼叫 NdisCoCreateVc 時提供給 NDIS ，以設定其傳出呼叫的 VC。

[in, optional] NdisPartyHandle

如果 Status 是NDIS_STATUS_SUCCESS且用戶端透過將明確的 ProtocolPartyContext 句柄傳遞至 NdisClMakeCall 來建立多點 VC，則這是有效的 NdisPartyHandle 。否則，此參數為 NULL。

ProtocolClMakeCallComplete 必須儲存任何有效的 輸入 NdisPartyHandle，通常是在用戶端的每一方內容區域中。如果 (或) 客戶端對參照此合作物件的 NdisClDropParty 或 NdisCloseCall 進行後續呼叫，用戶端就必須使用此句柄。

[in] CallParameters

緩衝CO_CALL_PARAMETERS結構的指標。用戶端已配置此緩衝區，並使用用戶端決定的數據初始化此結構，再將此指標傳遞至 NdisClMakeCall。處理用戶端的要求時，呼叫管理員可以修改此數據，以反映其與網路或訊號對等的交涉結果。

傳回值

無

備註

對 ProtocolClMakeCallComplete 的呼叫表示呼叫管理員已完成處理用戶端的要求，以建立與 NdisClMakeCall 的虛擬連線。

如果客戶端嘗試建立傳出呼叫失敗， (輸入狀態除外， NDIS_STATUS_SUCCESS) ，ProtocolClMakeCallComplete 應該執行下列動作：

釋放或準備重複使用 ProtocolPartyContext 區域，如果有的話，以及用戶端配置的 CallParameters 緩衝區。
使用對 NdisCoDeleteVc 的呼叫來終止用戶端建立的 VC，並釋放或準備重複使用用戶端配置的 ProtocolVcContext 區域。

否則， ProtocolClMakeCallComplete 應該執行下列動作：

檢查 CallParameters 中結構的 Flags 成員，以查看是否已設定CALL_PARAMETERS_CHANGED，這表示呼叫管理員修改了用戶端提供的呼叫參數。
如果是，請檢查 CallParameters 上的數據，以判斷是否可接受此連線。
例如，如果這是多點 VC，用戶端可能會保留作用中 VC 的緩衝呼叫參數、如果這是多點 VC，則儲存 NdisPartyHandle ，而且如果客戶端發現指定的呼叫參數滿意，則通常讓用戶端準備好進行後續傳輸和其他使用中 VC 的作業。
如果沒有，訊號通訊協議會判斷用戶端是否可以嘗試與呼叫管理員重新交涉可接受的呼叫參數。
例如，特定呼叫管理員可能會允許其用戶端在這些情況下呼叫 NdisClModifyCallQoS 一或多次。
如果無法接受 CM 修改的呼叫參數，而且無法進一步重新交涉， ProtocolClMakeCallComplete 必須使用 NdisCloseCall 終止呼叫。
在此情況下， ProtocolClMakeCallComplete不應該嘗試在 從 NdisCloseCall 傳回時釋放任何用戶端配置的資源，但只能傳回控制權。相反地，客戶端應該釋出它所配置的資源 (，或準備它們以在其 ProtocolCloseCallComplete 函式中重複使用) 。

例子

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

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

PROTOCOL_CL_MAKE_CALL_COMPLETE MyClMakeCallComplete;

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

_Use_decl_annotations_
VOID
 MyClMakeCallComplete(
    NDIS_STATUS  Status,
    NDIS_HANDLE  ProtocolVcContext,
    NDIS_HANDLE  NdisPartyHandle,
    PCO_CALL_PARAMETERS  CallParameters
    )
  {...}

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

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

規格需求

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