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

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

NDIS は、フィルタードライバーの FilterAttach 関数を呼び出して、フィルターモジュールのデータ構造を割り当てて初期化します。

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

構文

FILTER_ATTACH FilterAttach;

NDIS_STATUS FilterAttach(
  [in] NDIS_HANDLE NdisFilterHandle,
  [in] NDIS_HANDLE FilterDriverContext,
  [in] PNDIS_FILTER_ATTACH_PARAMETERS AttachParameters
)
{...}

パラメーター

[in] NdisFilterHandle

フィルターモジュールを識別する NDIS ハンドル。フィルタードライバーは、このハンドルを保存する必要があります。ハンドルは、 NdisFXxx 関数の後続の呼び出しで必要です。

[in] FilterDriverContext

ドライバーがに渡したハンドルドライバーコンテキスト領域を識別する NdisFRegisterFilterDriver 関数。

[in] AttachParameters

へのポインター NDIS_FILTER_ATTACH_PARAMETERS フィルターモジュールの初期化パラメーターを定義する構造体です。

戻り値

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

リターンコード	説明
NDIS_STATUS_SUCCESS	FilterAttach は、このフィルターモジュールのデータ構造を正常に割り当て、初期化しました。
NDIS_STATUS_RESOURCES	リソースが不足しているため、FilterAttach が失敗しました。
NDIS_STATUS_FAILURE	FilterAttach は、上記の値が適用されない場合にNDIS_STATUS_FAILUREを返します。フィルタードライバーは、エラーの理由を指定するパラメーターと共に NdisWriteEventLogEntry 関数を呼び出す必要があります。

注釈

FilterAttach は必須の関数です。 NDIS は、指定したフィルターモジュールがデタッチされた状態のときに、フィルタードライバーの FilterAttach 関数を呼び出します。 NDIS は、FilterSetOptions 関数の呼び出しが返された後、いつでも FilterAttach を呼び出すことができます。

FilterAttach での実行の開始時に、フィルターモジュールはアタッチ状態になります。

フィルタードライバーは、不要な OID クエリを発行しないようにする必要があります。代わりに、の情報を使用します。 NDIS_FILTER_ATTACH_PARAMETERS(使用可能な場合)、基になるドライバーに関する情報を取得します。

フィルタードライバーは、NDIS が FilterAttach を呼び出すときに、次の操作を実行します。

フィルターモジュールのコンテキスト領域を作成し、バッファープールとその他のリソースを割り当てます。
NdisFSetAttributes 関数を、NDIS が FilterAttach に渡した NdisFilterHandle と共に呼び出します。 NdisFSetAttributes の FilterModuleContext パラメーターは、このフィルターモジュールのフィルタードライバーのコンテキスト領域を指定します。 NDIS は、フィルタードライバーの FilterXxx 関数にこのコンテキスト領域を渡します。
必要に応じて、レジストリから構成パラメーターを読み取ります。
上記の操作が正常に完了した場合、フィルターモジュールは 一時停止 状態になります。
上記の操作が失敗した場合、フィルタードライバーは FilterAttach 関数で割り当てたリソースを解放し、フィルターモジュールを デタッチ済み 状態に戻す必要があります。
NDIS_STATUS_SUCCESSまたは適切なエラーコードを返します。

フィルタードライバーは、送信要求を行ったり、受信したデータを示したり、OID 要求を行ったり、 アタッチ 状態から状態を示したりしないでください。

NDIS は、フィルタードライバーの FilterDetach 関数を呼び出して、フィルターモジュールに関連付けられているすべてのリソースを解放し、フィルターモジュールを デタッチ状態 に戻します。

NDIS は、IRQL = PASSIVE_LEVELで FilterAttach を 呼び出します。

例

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

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

FILTER_ATTACH MyAttach;

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

_Use_decl_annotations_
NDIS_STATUS
 MyAttach(
    NDIS_HANDLE  NdisFilterHandle,
    NDIS_HANDLE  FilterDriverContext,
    PNDIS_FILTER_ATTACH_PARAMETERS  AttachParameters
    )
  {...}

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

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

要件

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