PROTOCOL_CO_CREATE_VC回呼函式（ndis.h）

發行項
02/07/2025

ProtocolCoCreateVc 函式是必要函式，可配置呼叫管理員或用戶端啟用和維護虛擬連線所需的資源。

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

語法

PROTOCOL_CO_CREATE_VC ProtocolCoCreateVc;

NDIS_STATUS ProtocolCoCreateVc(
  [in]  NDIS_HANDLE ProtocolAfContext,
  [in]  NDIS_HANDLE NdisVcHandle,
  [out] PNDIS_HANDLE ProtocolVcContext
)
{...}

參數

[in] ProtocolAfContext

指定通訊協定配置的內容區域的句柄，其中呼叫管理員或客戶端會維護其個別開啟狀態。呼叫管理員會從其 ProtocolCmOpenAf 函式中提供此句柄。用戶端從其 ProtocolCoAfRegisterNotify 函式呼叫 NdisClOpenAddressFamilyEx 時，會提供此句柄。

[in] NdisVcHandle

指定 NDIS 所提供的句柄，可唯一識別此虛擬連線。此句柄對通訊協定驅動程式不透明，並保留給 NDIS 連結庫使用。不過，呼叫管理員和客戶端必須儲存此句柄，才能將後續呼叫傳入 NdisCo/Cl/Cm/MCmXxx 涉及此 VC 的函式。

[out] ProtocolVcContext

指定通訊協定提供的內容區域的句柄，其中呼叫管理員或客戶端會維護此虛擬連線的狀態。

傳回值

ProtocolCoCreateVc 傳回其作業的狀態，做為下列其中一個值：

傳回碼	描述
NDIS_STATUS_SUCCESS	表示呼叫管理員或用戶端已成功配置和/或初始化建立和維護虛擬連線所需的任何必要資源。
NDIS_STATUS_RESOURCES	表示呼叫管理員或客戶端無法配置和/或初始化其資源，以建立和維護虛擬連線。
NDIS_STATUS_XXX	表示呼叫管理員或客戶端無法將自己設定為可以建立虛擬連線的狀態。這可能是從另一個 NDIS 連結庫例程傳播的錯誤傳回值。注意呼叫管理員或客戶端無法從其 ProtocolCoCreateVc 函式傳回NDIS_STATUS_PENDING。傳回擱置會轉譯此虛擬連線無法使用，而 NDIS 連結庫會呼叫用戶端或呼叫管理員來刪除它。

言論

每當對應的用戶端或呼叫管理員分別呼叫 NdisCoCreateVc NdisCoCreateVc 時，呼叫管理員或用戶端的 ProtocolCoCreateVc 函式。用戶端會在呼叫 NdisClMakeCall之前，在設定傳出呼叫之前，起始 VC 的建立。呼叫管理員會在通知用戶端 CM 收到來自遠端節點的來電供應專案時，起始建立 VC，該遠端節點已由該用戶端在 CM 呼叫之前向該用戶端註冊的 SAP NdisCmDispatchIncomingCall。

ProtocolCoCreateVc 會執行呼叫管理員或客戶端在即將啟動之 VC 上執行後續作業所需的動態資源和結構的任何必要配置。這類資源包括但不限於記憶體緩衝區、數據結構、事件，以及其他類似的資源。呼叫管理員和客戶端也應該初始化建立呼叫時所需的任何相關每個 VC 結構。

連線導向通訊協定驅動程式必須將 VC 的句柄儲存在 NdisVcHandle中指定的 VC 句柄，以用於此虛擬連線的未來作業。 NdisVcHandle 是 NdisCo NdisCoXxx、NdisCmXxx和/或 NdisCl Xxx 的必要參數，後續會呼叫這類連線導向通訊協定。

當呼叫管理員或用戶端為自己的每個 VC 數據配置記憶體並初始化其狀態時，此數據結構的位址應該在句柄中設定，再將控制權傳回 NDIS。若要這樣做，請取值句柄，並將通訊協定配置數據區域的指標儲存為句柄的值。例如：

*ProtocolVcContext = SomeBuffer;

如果 ProtocolCoCreateVc 無法配置執行後續網路 I/O 作業所需的資源，則應該釋放為此 VC 配置的所有資源，並傳回狀態為 NDIS_STATUS_RESOURCES 的控制。

如果 ProtocolCoCreateVc 已完成其必要作業，並且已讓呼叫管理員或用戶端準備好執行此虛擬連線的呼叫初始化，ProtocolCoCreateVc 應儘快傳回控制權，且狀態為 NDIS_STATUS_SUCCESS。

呼叫 ProtocolCoCreateVc 本質上是同步的。也就是說，ProtocolCoCreateVc無法傳回NDIS_STATUS_PENDING。

呼叫管理員的 ProtocolCoCreateVc 函式傳回控制權之後，呼叫管理員的 ProtocolCmMakeCall 函式將呼叫以建立遠端節點的連線。呼叫管理員不應在 ProtocolCmMakeCall 採取任何動作，因為 VC 可能會因為連線導向 NDIS 另一個元件的錯誤狀況而建立呼叫之前，將會終結 VC。

當用戶端的 ProtocolCoCreateVc 函式傳回控制權之後，用戶端的 ProtocolClIncomingCall 函式會在用戶端先前註冊的 SAP 上聯機的遠端起始要求透過網路收到時收到通知。

範例

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

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

PROTOCOL_CO_CREATE_VC MyCoCreateVc;

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

_Use_decl_annotations_
NDIS_STATUS
 MyCoCreateVc(
    NDIS_HANDLE  ProtocolAfContext,
    NDIS_HANDLE  NdisVcHandle,
    PNDIS_HANDLE  ProtocolVcContext
    )
  {...}

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

如需 Use_decl_annotations的相關信息，請參閱批注函式行為。

要求

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