PROTOCOL_CL_REGISTER_SAP_COMPLETE コールバック関数 (ndis.h)
着信呼び出しを受け入れる接続指向 NDIS クライアントには、 NdisClRegisterSap で開始する非同期操作を完了するための ProtocolClRegisterSapComplete 関数が必要です。 それ以外の場合、このようなプロトコル ドライバーの登録された ProtocolClRegisterSapComplete 関数は、単に制御を返すことができます。
構文
PROTOCOL_CL_REGISTER_SAP_COMPLETE ProtocolClRegisterSapComplete;
void ProtocolClRegisterSapComplete(
[in] NDIS_STATUS Status,
[in] NDIS_HANDLE ProtocolSapContext,
[in] PCO_SAP Sap,
[in] NDIS_HANDLE NdisSapHandle
)
{...}
パラメーター
[in] Status
NdisClRegisterSap に対するクライアントの呼び出しの最終的な状態を指定します。これは、次のいずれかになります。
NDIS_STATUS_SUCCESS
SAP は NDIS と呼び出しマネージャーの両方に登録されており、その後、 NdisCmDispatchIncomingCall 特定の SAP に送信された着信呼び出しオファーを受信するたびに、NDIS がクライアントの を呼び出す ProtocolClIncomingCall 関数。
NDIS_STATUS_RESOURCES
NDIS または呼び出しマネージャーは、SAP の登録と保守に必要なリソースを割り当てたり初期化したりできませんでした。
NDIS_STATUS_INVALID_DATA
クライアントは 、検証 のために呼び出しマネージャーの ProtocolCmRegisterSap 関数に転送する無効な仕様を Sap から NDIS に提供しました。
NDIS_STATUS_XXX
呼び出しマネージャーが、特定の SAP と NDIS を登録しようとしてエラーが発生し、この CM によって決定されたエラー状態がクライアントに伝達されました。
[in] ProtocolSapContext
クライアントが NdisClRegisterSap を呼び出したときに最初に NDIS に提供された、クライアントの SAP ごとのコンテキスト領域へのハンドルを指定します。 登録が成功した場合、NDIS はこのコンテキスト ハンドルを保持し、その後、この SAP に関連するクライアントの ProtocolClIncomingCall 関数の呼び出しで使用します。
[in] Sap
開く SAP の仕様を含むクライアント割り当てバッファーへのポインター。 クライアントは、最初にこのポインターを NdisClRegisterSap に渡しました。
[in] NdisSapHandle
Status がNDIS_STATUS_SUCCESSの場合は、この登録済み SAP に対する NDIS 提供の有効なハンドルを指定します。実質的には、クライアントとクライアントが指定した SAP の特定の呼び出しマネージャーとの間で NDIS と確立された関連付けを指定します。 それ以外の場合、このパラメーターは NULL です。 クライアントは、NdisClDeregisterSap への最終的な呼び出しのために、有効なハンドル (できれば ProtocolSapContext 領域) を保存する必要があります。
戻り値
なし
解説
NDIS は ProtocolClRegisterSapComplete を呼び出して、NdisClRegisterSap に対するクライアントの以前の呼び出しが NDIS によって処理されたことを示します。NDIS が呼び出しに失敗しなかった場合は、クライアントが NdisClRegisterSap に渡した NdisAfHandle を共有する呼び出しマネージャーによって行われます。
接続指向 NIC を介して着信呼び出しを受信するには、クライアントの ProtocolCoAfRegisterNotify または ProtocolClOpenAfCompleteEx 関数は、通常、1 つ以上の SAP を呼び出しマネージャーに登録します。
各 SAP を登録するために、クライアントは NdisClRegisterSap を呼び出し、クライアントが着信呼び出しの通知を受信する呼び出しマネージャーを識別する NdisAfHandle を渡し、NdisClRegisterSap へのクライアントの呼び出しが成功した場合、NDIS は登録済み SAP に NdisSapHandle をクライアントに返します。 ProtocolClRegisterSapComplete は、NdisClDeregisterSap を使用して後で SAP を解放できるように、有効な各 NdisSapHandle (通常はクライアントの SAP ProtocolSapContext 領域) を保存する必要があります。
SAP の形式は、呼び出しマネージャーに固有です。 クライアントが登録しようとしている SAP を呼び出しマネージャーが認識しない場合、または指定した SAP が既に使用されている場合、呼び出しマネージャーは SAP 登録に失敗する可能性があります。
ProtocolClRegisterSapComplete では、さらに処理する前に、NDIS_STATUS_SUCCESSの入力状態をチェックする必要があります。 SAP の登録が失敗した場合は、次の手順を実行します。
ProtocolClRegisterSapComplete は、クライアントが割り当てた SAP の SAP ごとのコンテキスト領域とバッファーを解放するか、 NdisClRegisterSap への別の呼び出しで再利用できるように準備することができます。
クライアントは、SAP 登録がまだ保留中の間、つまり ProtocolClRegisterSapComplete 関数が呼び出される前に、SAP で着信呼び出しを受信できます。
例
ProtocolClRegisterSapComplete 関数を定義するには、まず、定義する関数の種類を識別する関数宣言を指定する必要があります。 Windows には、ドライバー用の一連の関数型が用意されています。 関数の種類を使用して関数を宣言すると、ドライバー、静的ドライバー検証ツール (SDV)、およびその他の検証ツールのコード分析でエラーが検出され、Windows オペレーティング システムのドライバーを記述するための要件になります。たとえば、" MyClRegisterSapComplete" という名前の ProtocolClRegisterSapComplete 関数を定義するには、次のコード例に示すように 、PROTOCOL_CL_REGISTER_SAP_COMPLETE 型を使用します。
PROTOCOL_CL_REGISTER_SAP_COMPLETE MyClRegisterSapComplete;
次に、次のように関数を実装します。
_Use_decl_annotations_
VOID
MyClRegisterSapComplete(
NDIS_STATUS Status,
NDIS_HANDLE ProtocolSapContext,
PCO_SAP Sap,
NDIS_HANDLE NdisSapHandle
)
{...}
PROTOCOL_CL_REGISTER_SAP_COMPLETE関数の種類は、Ndis.h ヘッダー ファイルで定義されています。 コード分析ツールの実行時にエラーをより正確に識別するには、 Use_decl_annotations 注釈を関数定義に追加してください。 Use_decl_annotations注釈を使用すると、ヘッダー ファイル内のPROTOCOL_CL_REGISTER_SAP_COMPLETE関数型に適用される注釈が確実に使用されます。 関数宣言の要件の詳細については、「NDIS ドライバーの関数 ロール型を使用して関数を宣言する」を参照してください。
Use_decl_annotationsの詳細については、「関数の動作に注釈を付ける」を参照してください。
要件
| 要件 | 値 |
|---|---|
| サポートされている最小のクライアント | Windows Vista の NDIS 6.0 および NDIS 5.1 ドライバー (「ProtocolClRegisterSapComplete (NDIS 5.1)」を参照) でサポートされています。 Windows XP の NDIS 5.1 ドライバー (「ProtocolClRegisterSapComplete (NDIS 5.1)」を参照) でサポートされています。 |
| 対象プラットフォーム | Windows |
| ヘッダー | ndis.h (Ndis.h を含む) |
| IRQL | <= DISPATCH_LEVEL |