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

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

ProtocolOidRequestComplete 関数は、NdisOidRequest 関数がNDIS_STATUS_PENDING返したプロトコルドライバーによって開始される OID 要求の処理を完了します。

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

構文

PROTOCOL_OID_REQUEST_COMPLETE ProtocolOidRequestComplete;

void ProtocolOidRequestComplete(
  [in] NDIS_HANDLE ProtocolBindingContext,
  [in] PNDIS_OID_REQUEST OidRequest,
  [in] NDIS_STATUS Status
)
{...}

パラメーター

[in] ProtocolBindingContext

プロトコルドライバーがバインドごとの実行時状態を維持する、プロトコルドライバーによって割り当てられたコンテキスト領域へのハンドル。ドライバーは、 NdisOpenAdapterEx 関数を呼び出したときに、このハンドルを提供しました。

[in] OidRequest

以前に NdisOidRequest 関数に渡されたプロトコルドライバー提供のNDIS_OID_REQUEST構造体へのポインター。

[in] Status

要求の最終的な状態。基になるドライバーまたは NDIS は、この最終的な状態を決定します。このパラメーターは、OidRequest の情報を使用して ProtocolOidRequestComplete が何を行うかを決定 します。

戻り値

なし

解説

ProtocolOidRequestComplete では、 次のように Status の入力値が使用されます。

Status がNDIS_STATUS_SUCCESSの場合、NDIS_OID_REQUEST構造体の BytesRead メンバーまたは BytesWritten メンバーが NDIS または基になるドライバーによって設定され、設定された操作で InformationBuffer のバッファーから NIC に転送されたプロトコルドライバー提供の情報の量、またはクエリ操作に応答して InformationBuffer で返された情報の量を指定します。
プロトコルドライバーがクエリを実行した場合、ProtocolOidRequestComplete は、Oid メンバーの値に応じて、プロトコルドライバーによって決定される任意の方法で InformationBuffer で返されるデータを使用できます。

たとえば、プロトコルドライバーが最初にを開始した場合、クエリOID_GEN_MAXIMUM_SEND_PACKETS、ProtocolOidRequestComplete は ProtocolBindingContext 領域に状態変数を設定して、ドライバーが NdisSendNetBufferLIsts 関数の後続の呼び出し用に設定する未処理の送信数を調整する場合があります。
Status がNDIS_STATUS_INVALID_LENGTHまたはNDIS_STATUS_BUFFER_TOO_SHORTの場合、BytesNeeded メンバーは、要求された操作を実行するために必要な InformationBufferLength メンバーの OID 固有の値を指定します。
このような状況では、 ProtocolOidRequestComplete は要求に十分なバッファー領域を割り当て、必要な InformationBufferLength と同じ Oid を使用して別のNDIS_OID_REQUEST構造体を設定し、 NdisOidRequest 関数の呼び出しを再試行できます。

ProtocolOidRequestComplete は、NdisOidRequest 関数のリファレンスで説明されているように、他の特定のNDIS_STATUS_ XXX 引数の要求も再試行できます。
Status が回復不可能なエラーであるNDIS_STATUS_ XXX 値の場合、ProtocolOidRequestComplete は、NDIS_OID_REQUEST構造体に割り当てられたメモリを解放し、ドライバーがバインドを閉じる必要があるかどうかを判断するか、バインド固有の状態情報を調整して、バインドに対する継続的なネットワーク I/O 操作を処理する必要があります。

グローバルクエリとセットの場合、基になるコネクションレスミニポートドライバーが NdisMOidRequestComplete 関数を呼び出すと、NDIS は ProtocolOidRequestComplete 関数を呼び出します。 NDIS は、入力状態として NdisMOidRequestComplete に渡されるミニポートドライバーによって決定された状態を ProtocolOidRequestComplete に転送します。

バインド固有のクエリの場合、NDIS は ProtocolOidRequestComplete 関数自体を呼び出します。 NDIS ライブラリは、すべてのミニポートドライバーのバインドを維持するため、NDIS は、システムがフィルターライブラリを提供する 1 つとして、その中の種類を報告する基になるドライバーに関するバインディング固有の情報のみを返すことができます。 NDIS は、プロトコルドライバーによって開始されるバインディング固有のクエリのNDIS_STATUS_NOT_SUPPORTEDを他のミニポートドライバーに返します。

システム定義 OID の詳細については、「 NDIS OID」を参照してください。

ProtocolOidRequestComplete は、プロトコルドライバーが状態で NdisOidRequest が返す状態コードを検査する時間が経過する前に呼び出すことができます。

NDIS は、IRQL <= DISPATCH_LEVELで ProtocolOidRequestComplete を呼び出します。

例

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

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

PROTOCOL_OID_REQUEST_COMPLETE MyOidRequestComplete;

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

_Use_decl_annotations_
VOID
 MyOidRequestComplete(
    NDIS_HANDLE  ProtocolBindingContext,
    PNDIS_OID_REQUEST  OidRequest,
    NDIS_STATUS  Status
    )
  {...}

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

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

要件

要件	値
サポートされている最小のクライアント	NDIS 6.0 以降でサポートされています。
対象プラットフォーム	Windows
ヘッダー	ndis.h (Ndis.h を含む)
IRQL	<= DISPATCH_LEVEL