PROTOCOL_CO_CREATE_VC コールバック関数 (ndis.h)

[アーティクル]
08/07/2023

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 ライブラリ用に予約されています。ただし、呼び出しマネージャーとクライアントは、この VC に関連する NdisCo/Cl/Cm/MCmXxx 関数への後続の呼び出しを渡すために、このハンドルを保存する必要があります。

[out] ProtocolVcContext

呼び出しマネージャーまたはクライアントがこの仮想接続に関する状態を維持する、プロトコル指定のコンテキスト領域へのハンドルを指定します。

戻り値

ProtocolCoCreateVc は、操作の状態を次のいずれかの値として返します。

リターンコード	説明
NDIS_STATUS_SUCCESS	呼び出しマネージャーまたはクライアントが、仮想接続の確立と保守に必要なリソースを正常に割り当てたり初期化したりしたことを示します。
NDIS_STATUS_RESOURCES	呼び出しマネージャーまたはクライアントが、仮想接続を確立および維持するためにリソースを割り当てたり初期化したりできなかったことを示します。
NDIS_STATUS_XXX	呼び出しマネージャーまたはクライアントが、仮想接続を確立できる状態に設定できなかったことを示します。これは、別の NDIS ライブラリルーチンから伝達されたエラー戻り値である可能性があります。メモ呼び出しマネージャーまたはクライアントは、 ProtocolCoCreateVc 関数からNDIS_STATUS_PENDINGを返すことができません。保留中を返すと、この仮想接続は使用できなくなり、NDIS ライブラリはクライアントまたは呼び出しマネージャーを呼び出して削除します。

注釈

呼び出しマネージャーまたはクライアントの ProtocolCoCreateVc 関数は、対応するクライアントまたは呼び出しマネージャーが NdisCoCreateVc を呼び出すたびに呼び出されます。クライアントは、 NdisClMakeCall を呼び出す前に、発信呼び出しを設定するプロセスで VC の作成を開始します。呼び出しマネージャーは、CM が CM 呼び出しの前にそのクライアントによって既に登録されている SAP に送信されたリモートノードから着信呼び出しオファーを受信したことをクライアントに通知するプロセスで VC の作成を開始します NdisCmDispatchIncomingCall。

ProtocolCoCreateVc は、呼び出しマネージャーまたはクライアントがアクティブ化される VC に対して後続の操作を実行するために必要な動的リソースと構造体の必要な割り当てを実行します。このようなリソースには、メモリバッファー、データ構造、イベント、およびその他の同様のリソースが含まれますが、これらに限定されません。また、呼び出しマネージャーとクライアントは、呼び出しの確立時に必要となる関連する VC ごとの構造体も初期化する必要があります。

接続指向プロトコルドライバーは、この仮想接続に対する将来の操作で使用される VC ごとの状態領域に、 NdisVcHandle で指定された VC のハンドルを格納する必要があります。 NdisVcHandle は、このような接続指向プロトコルが後で呼び出す NdisCoXxx、NdisCmXxx、NdisClXxx の必須パラメーターです。

呼び出しマネージャーまたはクライアントが独自の VC ごとのデータのメモリを割り当て、その状態を初期化した場合、コントロールを NDIS に返す前に、このデータ構造のアドレスをハンドルに設定する必要があります。これを行うには、ハンドルを逆参照し、プロトコルによって割り当てられたデータ領域へのポインターをハンドルの値として格納します。例:

*ProtocolVcContext = SomeBuffer;

ProtocolCoCreateVc が後続のネットワーク I/O 操作を実行するために必要なリソースを割り当てることができない場合は、この VC に割り当てられたすべてのリソースを解放し、状態が NDIS_STATUS_RESOURCES の制御を返す必要があります。

ProtocolCoCreateVc が必要な操作を完了し、呼び出しマネージャーまたはクライアントがこの仮想接続の呼び出しの初期化を実行する準備ができた場合、ProtocolCoCreateVc は、NDIS_STATUS_SUCCESSの状態でできるだけ早く制御を返す必要があります。

ProtocolCoCreateVc の呼び出しは本質的に同期的です。つまり、ProtocolCoCreateVc はNDIS_STATUS_PENDINGを返すことができません。

呼び出しマネージャーの ProtocolCoCreateVc 関数が制御を返すと、呼び出しマネージャーの ProtocolCmMakeCall 関数が呼び出され、リモートノードへの接続が確立されます。接続指向 NDIS の別のコンポーネントでエラー状態が発生したため、呼び出しが確立される前に VC が破棄される可能性があるため、呼び出しマネージャーは ProtocolCmMakeCall で実際に呼び出しを確立するアクションを実行しないでください。

クライアントの ProtocolCoCreateVc 関数が制御を返すと、クライアントによって以前に登録された SAP に接続するためのリモート開始要求がネットワーク経由で送信されると、クライアントの ProtocolClIncomingCall 関数に通知されます。

例

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)」を参照) でサポートされています。
対象プラットフォーム	Windows
ヘッダー	ndis.h (Ndis.h を含む)
IRQL	<= DISPATCH_LEVEL