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

[アーティクル]
02/26/2024

ProtocolCmRegisterSap 関数は、接続指向クライアントの代わりに呼び出しマネージャーが SAP (サービスアクセスポイント) を登録するように要求するために NDIS によって呼び出される必須の関数です。

メモPROTOCOL_CM_REG_SAP型を使用して関数を宣言する必要があります。詳細については、次の例に関するセクションを参照してください。

構文

PROTOCOL_CM_REG_SAP ProtocolCmRegSap;

NDIS_STATUS ProtocolCmRegSap(
  [in]  NDIS_HANDLE CallMgrAfContext,
  [in]  PCO_SAP Sap,
  [in]  NDIS_HANDLE NdisSapHandle,
  [out] PNDIS_HANDLE CallMgrSapContext
)
{...}

パラメーター

[in] CallMgrAfContext

呼び出しマネージャーがオープンごとの AF 状態を維持する、呼び出しマネージャーによって割り当てられたコンテキスト領域へのハンドルを指定します。呼び出しマネージャーは、 ProtocolCmOpenAf 関数から NDIS にこのハンドルを提供しました。

[in] Sap

接続指向クライアントが登録している特定の SAP を含むメディア固有のCO_SAP構造体へのポインター。

[in] NdisSapHandle

NDIS によって提供される、この SAP を一意に識別するハンドルを指定します。このハンドルは呼び出しマネージャーに対して不透明であり、NDIS ライブラリ用に予約されています。

[out] CallMgrSapContext

戻り時に、呼び出しマネージャーがこの SAP に関する状態を維持する、呼び出しマネージャーが指定したコンテキスト領域へのハンドルを指定します。

戻り値

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

リターンコード	説明
NDIS_STATUS_SUCCESS	呼び出しマネージャーが SAP の登録と保守に必要なリソースを正常に割り当てたり初期化したりしたことを示します。さらに、呼び出しマネージャーがサポートするネットワークメディアによって必要に応じて SAP が正常に登録されたことも示します。
NDIS_STATUS_PENDING	呼び出しマネージャーがこの要求の処理を非同期的に完了することを示します。呼び出しマネージャーはを呼び出す必要があります登録が完了したことを NDIS に通知するために、すべての処理が完了した場合の NdisCmRegisterSapComplete。
NDIS_STATUS_RESOURCES	呼び出しマネージャーが、接続指向クライアントの代わりに SAP を登録するために必要なリソースを割り当てたり初期化したりできなかったことを示します。
NDIS_STATUS_INVALID_DATA	Sap で指定された仕様が無効であるか、サポートできないことを示します。
NDIS_STATUS_XXX	接続指向クライアントの SAP を登録しようとしたときに、呼び出しマネージャーでエラーが発生したことを示します。戻りコードはエラーに適しており、別の NDIS ライブラリ関数から伝達されるリターンコードである可能性があります。

注釈

ProtocolCmMakeCall は、必要に応じて、ネットワーク制御デバイスまたはその他のメディア固有のエージェントと通信して、 Sap で指定された SAP を接続指向クライアントのネットワークに登録します。このようなアクションには、スイッチングハードウェアとの通信、ネットワーク制御ステーションとの通信、またはネットワークメディアに適したその他のアクションが含まれますが、これらに限定されません。

ネットワーク制御エージェント (つまり、ネットワークスイッチ) と通信するために呼び出しマネージャーが必要な場合は、 ProtocolBindAdapterEx 関数で確立したネットワーク制御エージェントへの仮想接続を使用する必要があります。スタンドアロン呼び出しマネージャーは、 NdisCoSendNetBufferLists を呼び出すことによって、基になるミニポートドライバーを介して通信します。統合された呼び出し管理サポートを備えたミニポートドライバーは 、NdisCoSendNetBufferLists を呼び出しません。代わりに、ネットワーク経由でデータを直接送信します。

さらに、 ProtocolCmRegisterSap は、接続指向クライアントに代わって SAP に関する状態情報を維持するために呼び出しマネージャーが必要とする動的リソースと構造体の必要な割り当てを実行する必要があります。このようなリソースには、メモリバッファー、データ構造、イベント、およびその他の同様のリソースが含まれますが、これらに限定されません。呼び出しマネージャーは、NDIS に制御を返す前に、割り当てるリソースも初期化する必要があります。呼び出しマネージャーは、将来使用するために、 NDISSapHandle で提供される SAP を識別する NDIS 提供のハンドルをコンテキスト領域に格納する必要があります。

ProtocolCmRegisterSap がNDIS_STATUS_SUCCESSを返す場合は、SAP ごとの状態領域を割り当てた後、制御を NDIS に返す前に CallMgrSapContext でこの状態領域のアドレスを設定する必要があります。これを行うには、 CallMgrSapContext を逆参照し、データ領域へのポインターをハンドルの値として格納します。例:

*CallMgrSapContext = SomeBuffer ;

別の接続指向クライアントによって既に登録されている特定の SAP の場合、呼び出しマネージャーは要求を失敗させ、NDIS_STATUS_INVALID_DATAを返す必要があります。

呼び出しマネージャーは、接続指向のクライアントに代わって SAP を登録した後、を呼び出すことによって、その SAP に送信された着信呼び出しオファーをクライアントに通知します NdisCmDispatchIncomingCall。

例

ProtocolCmRegisterSap 関数を定義するには、まず、定義する関数の型を識別する関数宣言を指定する必要があります。 Windows には、ドライバーの関数型のセットが用意されています。関数の種類を使用して関数を宣言すると、ドライバーのコード分析、静的ドライバー検証ツール (SDV)、およびその他の検証ツールでエラーが検出され、Windows オペレーティングシステム用のドライバーを記述するための要件になります。

たとえば、" MyCmRegisterSap" という名前の ProtocolCmRegisterSap 関数を定義するには、次のコード例に示すように 、PROTOCOL_CM_REG_SAP 型を使用します。

PROTOCOL_CM_REG_SAP MyCmRegisterSap;

次に、次のように関数を実装します。

_Use_decl_annotations_
NDIS_STATUS
 MyCmRegisterSap(
    NDIS_HANDLE  CallMgrAfContext,
    PCO_SAP  Sap,
    NDIS_HANDLE  NdisSapHandle,
    PNDIS_HANDLE  CallMgrSapContext
    )
  {...}

PROTOCOL_CM_REG_SAP関数の種類は、Ndis.h ヘッダーファイルで定義されています。コード分析ツールを実行するときにエラーをより正確に識別するには、 Use_decl_annotations 注釈を関数定義に追加してください。 Use_decl_annotations注釈を使用すると、ヘッダーファイル内のPROTOCOL_CM_REG_SAP関数型に適用される注釈が確実に使用されます。関数宣言の要件の詳細については、「NDIS ドライバーの関数ロール型を使用して関数を宣言する」を参照してください。

Use_decl_annotationsの詳細については、「関数の動作に注釈を付ける」を参照してください。

要件

要件	値
サポートされている最小のクライアント	Windows Vista の NDIS 6.0 および NDIS 5.1 ドライバー (「ProtocolCmRegisterSap (NDIS 5.1)」を参照) でサポートされています。 Windows XP の NDIS 5.1 ドライバー (「ProtocolCmRegisterSap (NDIS 5.1)」を参照) でサポートされています。
対象プラットフォーム	Windows
ヘッダー	ndis.h (Ndis.h を含む)
IRQL	<= DISPATCH_LEVEL