Share via

FILTER_SYNCHRONOUS_OID_REQUEST関数 (ndis.h)

  • [アーティクル]

NDIS は、フィルター ドライバーの FilterSynchronousOidRequest 関数を呼び出して、基になるミニポート ドライバーに要求が渡される前に、同期 OID 要求をプレビューします。

この関数は、NDIS 6.81 以降でサポートされています。

構文

NDIS_STATUS FILTER_SYNCHRONOUS_OID_REQUEST(
            NDIS_HANDLE      FilterModuleContext,
  [in, out] NDIS_OID_REQUEST *OidRequest,
  [out]     PVOID            *CallContext
);

パラメーター

FilterModuleContext

この要求のターゲットであるフィルター モジュールのコンテキスト領域へのハンドル。 フィルター ドライバーは、 FilterAttach 関数でこのコンテキスト領域を作成および初期化しました。

[in, out] OidRequest

要求された操作を指定する NDIS_OID_REQUEST 構造体へのポインター。

[out] CallContext

フィルター ドライバーが FilterSynchronousOidRequest ハンドラーと FilterSynchronousOidRequestComplete ハンドラーの間で状態を共有するための PVOID サイズのストレージ スロット。 NDIS では、これが最初に 0 の値を指している必要があります。 詳細については、次の「解説」を参照してください。

戻り値

この関数は、次のいずれかの適切なNDIS_STATUS コードを返します。

リターン コード 説明
NDIS_STATUS_SUCCESS OID 要求がミニポート ドライバーに伝達され続けることを許可します。 フィルター ドライバーは、認識できない種類の OID に対してこの状態コードを返す必要があります。
NDIS_STATUS_ALREADY_COMPLETE OID 要求の伝達を停止し、代わりに状態NDIS_STATUS_SUCCESSで呼び出し元に返します。
  • NDIS_STATUS_BUFFER_TOO_SHORT
  • NDIS_STATUS_INVALID_LENGTH
  • NDIS_STATUS_INVALID_DATA
 FilterDirectOidRequest と同じです。
NDIS_STATUS_RESOURCES FilterDirectOidRequest と同じですが、同期 OID 要求を迅速に完了する必要があるため、フィルター ドライバーは通常、リソースの割り当てを回避する必要があります。
NDIS_STATUS_NOT_SUPPORTED フィルター ドライバーは、OID が認識されないという理由だけで、このコードを返す必要があります。 フィルター ドライバーは、フィルターが操作を認識するが、何らかの理由で実行できない場合にのみ、これを返すことができます。

注釈

FilterSynchronousOidRequest は省略可能な関数です。 フィルター ドライバーがミニポート ドライバーに送信された同期 OID 要求を監視または変更する必要がない場合、フィルター ドライバーは NdisFRegisterFilterDriver を呼び出すときに、この関数のエントリ ポイントを NULL に設定する必要があります。

NDIS は、フィルター ドライバーの FilterSynchronousOidRequest 関数を呼び出して、基になるドライバーによって生成された同期 OID 要求を処理します。 フィルター ドライバーは、 NDIS_OID_REQUEST 構造の一部のフィールドを次のように読み取ったり変更したりできます。

フィールド アクセスのフィルター処理
ヘッダー 読み取り専用
RequestType 読み取り/書き込み
PortNumber 読み取り/書き込み
タイムアウト アクセスしない
RequestId アクセスしない
RequestHandle 読み取り/書き込み
DATA 読み取り/書き込み
NdisReserved アクセスしない
ミニポート予約済み アクセスしない
ソース予約済み アクセスしない
SupportedRevision 読み取り/書き込み
予約済み 1、予約済み 2 アクセスしない
SwitchId 読み取り/書き込み
VPortId 読み取り/書き込み
Flags 読み取り/書き込み

フィルター ドライバーは、 NDIS_OID_REQUEST 構造体の変更に加えて、 FilterSynchronousOidRequest からのリターン コードを使用して要求を制御できます。

  • NDIS_STATUS_SUCCESS: OID は引き続きミニポート ドライバーに伝達されます。
  • NDIS_STATUS_ALREADY_COMPLETE: OID は、最初にミニポート ドライバーに伝達することなく、上にあるドライバーにすぐに完了します。 OID 要求は、NDIS_STATUS_SUCCESSを使用して、上にあるドライバーに対して完了します。
  • その他の状態コード: OID はすぐに上にあるドライバーに戻り、最初にミニポート ドライバーに伝達されません。 OID 要求は、フィルター ドライバーによって返される状態コードを使用して、上にあるドライバーに対して完了します。

フィルター ドライバーで FilterSynchronousOidRequestComplete ハンドラーも登録されている場合、 FILTERSynchronousOidRequestComplete ハンドラーは、 FilterSynchronousOidRequest ハンドラーがNDIS_STATUS_SUCCESSを返した場合にのみ呼び出されることを保証します。

FilterSynchronousOidRequest ハンドラーは、PVOID サイズの値を *CallContext に書き込むことができます。OID 要求が完了すると、フィルター ドライバーの FilterSynchronousOidRequestComplete ハンドラーに同じ値が返されます。 フィルター ドライバーは、これを使用して、2 つのハンドラー間で状態を保持できます。 FilterSynchronousOidRequestComplete ハンドラーは FilterSynchronousOidRequest ハンドラーがNDIS_STATUS_SUCCESSを返した場合にのみ呼び出されるため、他のコードを返すときに *CallContext に値を書き込む理由はありません。 同様に、フィルター ドライバーが FilterSynchronousOidRequestComplete ハンドラーを提供しない場合、*CallContext に値を書き込む理由はありません。

フィルター ドライバーは、 FilterSynchronousOidRequest ハンドラーからNDIS_STATUS_PENDINGを返してはなりません。 同期 OID 要求をペンまたは取り消すことはできません。

フィルター ドライバーは、ブロック、待機、またはスリープ状態にすることなく、 FilterSynchronousOidRequest ハンドラーからすばやく戻ることが期待されます。 同期 OID 要求は待機時間の短い操作にのみ使用され、フィルター ドライバーは数ミリ秒以内に続行または完了するように努める必要があります。 NDIS は、互いに、他の OID 要求に対して、または FilterPause に対して同期 OID 要求をシリアル化しません。 フィルター ドライバーは、必要な同期を実装する必要があります。

NDIS は FilterDetach に対して同期 OID 要求をシリアル化します。NDIS では、 FilterDetach が呼び出されると、同期 OID 要求がアクティブになることは保証されません。

フィルター ドライバーは、同期 OID 要求 で NdisAllocateCloneOidRequest または NdisCancelOidRequest を呼び出してはなりません。 フィルター ドライバーは、 FilterSynchronousOidRequest ハンドラーを介して受信した OID 要求で NdisFSynchronousOidRequest を 呼び出してはなりません。

フィルター ドライバーが FilterSynchronousOidRequest ハンドラーで IRQL を発生させる場合は、 FilterSynchronousOidRequest ハンドラーから戻る前に IRQL を初期レベルに復元する必要があります。

要件

要件 値
サポートされている最小のクライアント Windows 10 バージョン 1709
対象プラットフォーム Windows
ヘッダー ndis.h (Ndis.h を含む)
IRQL <= DISPATCH_LEVEL

こちらもご覧ください

FilterSynchronousOidRequestComplete

NdisFSynchronousOidRequest

NDIS 6.80 の同期 OID 要求インターフェイス