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

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

FilterRestart 関数は、指定されたフィルターモジュールの再起動操作を開始します。

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

構文

FILTER_RESTART FilterRestart;

NDIS_STATUS FilterRestart(
  [in] NDIS_HANDLE FilterModuleContext,
  [in] PNDIS_FILTER_RESTART_PARAMETERS RestartParameters
)
{...}

パラメーター

[in] FilterModuleContext

フィルタードライバーを再起動する必要があるフィルターモジュールのコンテキスト領域へのハンドル。 FilterAttach 関数でこのコンテキスト領域を作成および初期化したフィルタードライバー。

[in] RestartParameters

へのポインター NDIS_FILTER_RESTART_PARAMETERS フィルターモジュールの再起動パラメーターを定義する構造体です。

戻り値

FilterRestart は、次のいずれかの状態値を返します。

リターンコード	説明
NDIS_STATUS_SUCCESS	FilterRestart は、指定されたフィルターモジュールを正常に再起動しました。
NDIS_STATUS_PENDING	フィルタードライバーは、再起動操作が完了した後、 NdisFRestartComplete 関数の呼び出しで非同期的に要求を完了します。
NDIS_STATUS_RESOURCES	リソースが不足しているため、FilterRestart に失敗しました。
NDIS_STATUS_FAILURE	上記の状態値は適用しません。フィルタードライバーは、エラーの理由を指定するパラメーターと共に NdisWriteEventLogEntry 関数を呼び出す必要があります。

注釈

FilterRestart は、フィルタードライバーに必要な関数です。フィルターモジュールが一時停止状態の場合、NDIS は FilterRestart を呼び出すことができます。フィルターモジュールは、FilterRestart の実行の開始時に再起動状態になります。

NDIS が FilterRestart を呼び出すと、フィルタードライバーは次のようになります。

通常の送受信操作を再開するために必要な操作を完了する必要があります。
必要に応じて、構成パラメーターの読み取りまたは書き込みを行います。
必要に応じて、バッファープールを再割り当てします。
必要に応じて、の RestartAttributes メンバーで指定されている再起動属性を変更します。 NDIS_FILTER_RESTART_PARAMETERS 構造体。 RestartAttributes のポインターが NULL の場合、フィルタードライバーは再起動属性の一覧を変更したり追加したりしないでください。 RestartAttributes 内のポインターが NULL 以外の場合は、再起動属性の一覧の最初のNDIS_RESTART_ATTRIBUTES構造体を指します。フィルタードライバーが再起動しない場合は、属性を変更しないでください。
必要に応じて、OID 要求を使用して、基になるドライバーの情報を照会または設定します。フィルタードライバーは、再起動属性の一覧で既に提供されている情報の OID 要求を発行しないでください。
NDIS_STATUS_SUCCESSまたはエラー状態を返します。

フィルタードライバーが再起動属性の一覧を変更する場合、フィルタードライバーは次のようになります。

の Oid メンバーで OID が認識されない場合は、メディア固有の属性を変更しないでください。 NDIS_RESTART_ATTRIBUTES 構造体。
新しいメディア固有の属性を再起動属性の一覧に追加できます。この状況では、フィルタードライバーは、新しいNDIS_RESTART_ATTRIBUTES構造体を割り当てる必要があります。たとえば、 NdisAllocateMemoryWithTagPriority 関数-- とは、新しい属性のメモリ領域を提供します。再起動属性を基になるドライバーに伝達すると、NDIS はフィルタードライバーの属性メモリを解放します。
再起動属性の一覧でメディア固有の属性を変更できます。フィルタードライバーにより多くのメモリ領域が必要な場合は、NdisFreeMemory 関数を使用してNDIS_RESTART_ATTRIBUTES構造体を解放し、変更された情報を格納する新しい構造体を割り当てることができます。再起動属性を基になるドライバーに伝達すると、NDIS はフィルタードライバーの属性メモリを解放します。
NDIS_RESTART_ATTRIBUTES構造体の Oid メンバーが OID_GEN_MINIPORT_RESTART_ATTRIBUTES、次の点を確認します。 NDIS_RESTART_GENERAL_ATTRIBUTES 構造体には、フィルタードライバーに必要な情報が含まれています。 NDIS_RESTART_GENERAL_ATTRIBUTES構造体に必要な情報が含まれていることを確認するには、NDIS_RESTART_GENERAL_ATTRIBUTES構造体の Header メンバーで指定されているNDIS_OBJECT_HEADER構造体の Revision メンバーをチェックする必要があります。
メモフィルタードライバーは、NDIS_RESTART_GENERAL_ATTRIBUTES構造体内の任意のメンバーを変更できます。フィルタードライバーが変更する必要がある一部の属性が、NDIS によって提供された構造体のリビジョンに含まれていない場合、フィルタードライバーは、不足している属性の OID 要求を発行するために、基になるドライバーに依存する必要があります。フィルタードライバーは、OID 要求が完了したときに属性を変更できます。
フィルタードライバーが再起動属性を変更する場合は、 FilterOidRequest 関数を指定する必要があります。フィルタードライバーは、基になるドライバーが再起動属性で受け取る情報が、OID 要求に応答して受け取る情報と一致していることを確認する必要があります。

フィルタードライバーが状態を返すか、 NdisFRestartComplete 関数を呼び出すと、再起動操作が完了します。操作が正常に完了した場合、フィルターモジュールは 実行中 の状態になり、通常の送受信処理が再開されます。再起動操作が失敗した場合、フィルターモジュールは 一時停止 状態に戻ります。

NDIS 呼び出し FilterRestart at IRQL = PASSIVE_LEVEL。

例

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

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

FILTER_RESTART MyRestart;

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

_Use_decl_annotations_
NDIS_STATUS
 MyRestart(
    NDIS_HANDLE  FilterModuleContext,
    PNDIS_FILTER_RESTART_PARAMETERS  FilterRestartParameters
    )
  {...}

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

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

要件

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