PROTOCOL_CL_ADD_PARTY_COMPLETE回呼函式 (ndis.h)

發行項
02/29/2024

設定多點連線的 NDIS 用戶端需要 ProtocolClAddPartyComplete 函式。這類客戶端必須具有 ProtocolClAddPartyComplete 函式，才能完成它們以 NdisClAddParty 起始的異步操作。否則，這類通訊協定驅動程式的已註冊 ProtocolClAddPartyComplete 函式可以直接傳回控制權。

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

語法

PROTOCOL_CL_ADD_PARTY_COMPLETE ProtocolClAddPartyComplete;

void ProtocolClAddPartyComplete(
  [in] NDIS_STATUS Status,
  [in] NDIS_HANDLE ProtocolPartyContext,
  [in] NDIS_HANDLE NdisPartyHandle,
  [in] PCO_CALL_PARAMETERS CallParameters
)
{...}

參數

[in] Status

指定用戶端起始的新增合作物件作業的最終狀態，可以是下列其中一項：

NDIS_STATUS_SUCCESS

指定的合作物件已新增至用戶端的作用中多點 VC。

NDIS_STATUS_RESOURCES

NDIS 無法配置足夠的資源來追蹤新合作物件。

NDIS_STATUS_FAILURE

用戶端已將無效 的 NdisVcHandle 傳遞至 NdisClAddParty。

NDIS_STATUS_XXX

呼叫管理員的 ProtocolCmAddParty 函式傳回 CM 決定的值，指出為何無法將合作物件新增至 VC。

[in] ProtocolPartyContext

指定原本傳遞至 NdisClAddParty 的用戶端提供句柄。

[in] NdisPartyHandle

如果 Status 是NDIS_STATUS_SUCCESS，則這個 NDIS 提供的句柄代表呼叫管理員與客戶端有關此合作對象的關聯。否則，嘗試新增合作對象失敗，且客戶端應該將此參數視為無效的句柄。

[in] CallParameters

CO_CALL_PARAMETERS 類型的結構指標，最初是由用戶端為其 NdisClAddParty 呼叫所設定，但後續可由呼叫管理員修改。

傳回值

無

備註

對 ProtocolClAddPartyComplete 的呼叫表示當用戶端呼叫 NdisClAddParty 時起始的異步操作完成。如果輸入狀態設定為 NDIS_STATUS_SUCCESS 以外的任何專案， ProtocolClAddPartyComplete 可以在 ProtocolPartyContext 和 CallParameters 上釋放或重複使用用戶端配置的緩衝區。

如果嘗試新增合作物件成功， ProtocolClAddPartyComplete 應該儲存輸入 NdisPartyHandle ，以便後續在用戶端的 ProtocolPartyContext 區域中呼叫此合作對象的相關 NDIS 連結庫函式。例如，客戶端必須在後續對 NdisClDropParty 的呼叫中傳遞此句柄，除非它代表的遠端物件會先關閉其連線。

在 CallParameters 的結構原本是由用戶端所配置和初始化，而用戶端會將這個指標傳遞至
NdisClAddParty。不過，呼叫管理員可能已經修改用戶端提供的值，以反映 CM 與網路交涉的結果，或在處理用戶端的載入物件要求時，使用訊號對等來反映 CM 交涉的結果。若要判斷呼叫管理員是否進行任何修改， ProtocolClAddPartyComplete 可以檢查此結構的 Flags 成員，以瞭解是否已設定CALL_PARAMETERS_CHANGED。若是如此，除非客戶端發現 CM 的修改無法接受，否則 ProtocolClAddPartyComplete 必須更新用戶端針對此呼叫維護的每個合作對象狀態。特定訊號通訊協議會決定用戶端在此案例中可以執行的動作。通常，如果客戶端發現 CM 修改的呼叫參數無法接受，用戶端會呼叫 NdisClDropParty 。

視呼叫管理員的訊號通訊協定而定， CallParameters 上的流量參數可以與任何特定多點連線上的所有合作物件相同。也就是說，當這類呼叫管理員的用戶端在用戶端最初使用 NdisClMakeCall 設定的多點連線上新增合作物件時，它只能提供每一方的目標地址，並且每次呼叫 NdisClAddParty 時，將流量參數保留為原本設定的多點 VC。

例子

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

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

PROTOCOL_CL_ADD_PARTY_COMPLETE MyClAddPartyComplete;

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

_Use_decl_annotations_
VOID
 MyClAddPartyComplete(
    NDIS_STATUS  Status,
    NDIS_HANDLE  ProtocolPartyContext,
    NDIS_HANDLE  NdisPartyHandle,
    PCO_CALL_PARAMETERS  CallParameters
    )
  {...}

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

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

規格需求

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