PROTOCOL_CO_CREATE_VC回呼函式 (ndis.h)

發行項
02/26/2024

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

注意您必須使用 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 會以下列其中一個值傳回其作業的狀態 (s) ：

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

備註

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

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

聯機導向通訊協定驅動程式必須儲存 NDIsVcHandle 中指定的 VC 句柄，其每個 VC 狀態區域，以供此虛擬連線的未來作業使用。 NdisVcHandle 是 NdisCoXxx、NdisCm Xxx 和/或 NdisClXxx 的必要參數，這類連接導向通訊協定後續會呼叫。

當呼叫管理員或用戶端已為自己的每個 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 的另一個元件發生錯誤狀況。

用戶端的 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的詳細資訊，請參閱標註函式行為。

規格需求

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