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

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

NDIS は、ドライバーの XxxSetOptions 関数を呼び出して、ドライバーがオプションのサービスを登録できるようにします。この関数は、ミニポートドライバーの 場合は MiniportSetOptions 、プロトコルドライバーの 場合は ProtocolSetOptions 、フィルタードライバー の場合は FilterSetOptions として定義されます。

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

構文

SET_OPTIONS SetOptions;

NDIS_STATUS SetOptions(
  [in] NDIS_HANDLE NdisDriverHandle,
  [in] NDIS_HANDLE DriverContext
)
{...}

パラメーター

[in] NdisDriverHandle

ドライバーを識別するハンドル。 NDIS は、ドライバー登録関数 (ミニポートドライバーの場合は NdisMRegisterMiniportDriver 、プロトコルドライバーの場合は NdisRegisterProtocolDriver 、フィルタードライバーの場合は NdisFRegisterFilterDriver ) からこのハンドルをドライバーに返します。

[in] DriverContext

ドライバーコンテキスト領域を識別する NdisRegisterXxxDriver にドライバーが渡されたハンドル。Xxx はドライバーの種類 (ミニポート、プロトコル、またはフィルター) です。

戻り値

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

リターンコード	説明
NDIS_STATUS_SUCCESS	XxxSetOptions は、ドライバーのオプションのサービスとリソースを正常に登録しました。
NDIS_STATUS_RESOURCES	XxxSetOptions は、ドライバーに必要なリソースを割り当てませんでした。
NDIS_STATUS_XXXまたはNTSTATUS_XXX	ドライバーがオプションを登録しようとしましたが失敗しました。通常、このようなエラー状態は NdisXxx 関数またはカーネルモードサポートルーチンから伝達されます。

注釈

XxxSetOptions は省略可能な関数です。 NDIS は、に対するドライバーの呼び出しのコンテキスト内で XxxSetOptions を呼び出します。 NdisRegisterXxxDriver 関数。Xxx はドライバーの種類 (ミニポート、プロトコル、またはフィルター) です。

XxxSetOptions は 省略可能なサービスを登録し、他のドライバーリソースを割り当てることができます。省略可能な ミニポートXxx、 ProtocolXxx、または FilterXxx 関数を登録するには、ドライバーは NdisSetOptionalHandlers 関数を呼び出します。ドライバーは、NdisSetOptionalHandlers の NdisHandle パラメーターで NdisDriverHandle パラメーターからハンドルを渡し、OptionalHandlers パラメーターで特性構造を渡します。

ミニポートドライバーは、次の特性構造で定義されているオプションのサービスに適用できます。

NDIS_MINIPORT_CO_CHARACTERISTICS

NDIS_MINIPORT_PNP_CHARACTERISTICS

NDIS_CO_CALL_MANAGER_OPTIONAL_HANDLERS

NDIS_PROVIDER_CHIMNEY_OFFLOAD_GENERIC_CHARACTERISTICS ( NDIS 6.0 TCP チムニーオフロードドキュメントを参照)

NDIS_PROVIDER_CHIMNEY_OFFLOAD_TCP_CHARACTERISTICS ( NDIS 6.0 TCP チムニーオフロードドキュメントを参照)

プロトコルドライバーは、次の特性構造で定義されているオプションのサービスに適用できます。

NDIS_PROTOCOL_CO_CHARACTERISTICS

NDIS_CO_CLIENT_OPTIONAL_HANDLERS

NDIS_CO_CALL_MANAGER_OPTIONAL_HANDLERS

現在の Windows バージョンには、オプションのフィルタードライバーサービスはありません。

NDIS は、XxxSetOptions が返された後、いつでもドライバーの他のミニポートXxx、ProtocolXxx、または FilterXxx 関数を呼び出すことができます。ドライバーは、初期化関数で呼び出されるように準備する必要があります。(ミニポートドライバーの場合は MiniportInitializeEx 、プロトコルドライバーの場合は ProtocolBindAdapterEx 、フィルタードライバーの場合は FilterAttach )。

ミニポートドライバーの場合、NDIS が MiniportInitializeEx を呼び出す前に、ミニポートアダプターは停止状態になります。プロトコルドライバーの場合、NDIS が ProtocolBindAdapterEx を呼び出す前に、プロトコルバインドは Unbound 状態になります。フィルタードライバーの場合、フィルターモジュールは、NDIS が FilterAttach を呼び出す前にデタッチされた状態になります。

リソースまたはサービスの割り当てが失敗した場合、 XxxSetOptions は、NDIS_STATUS_SUCCESS以外の状態のコントロールを返す前に、成功したすべての割り当てを元に戻す必要があります。

ミニポートドライバーとフィルタードライバーの XxxDriverUnload は、XxxSetOptions で実行されたすべての操作を元に戻す必要があります

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

例

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

Ndis.h ヘッダーファイルでは、SET_OPTIONSコールバック関数は次のようにさらに定義されます。

typedef SET_OPTIONS (*SET_OPTIONS_HANDLER);
typedef SET_OPTIONS (MINIPORT_SET_OPTIONS);
typedef SET_OPTIONS (PROTOCOL_SET_OPTIONS);
typedef SET_OPTIONS (FILTER_SET_OPTIONS);

これにより、すべての NDIS ドライバーは、同じ構文で XxxSetOptions コールバック関数を実装できます。ミニポートドライバーは MINIPORT_SET_OPTIONS の種類を使用し、プロトコルドライバーは PROTOCOL_SET_OPTIONS の種類を使用し、フィルタードライバーは FILTER_SET_OPTIONS の種類を使用します。

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

MINIPORT_SET_OPTIONS MySetOptions;

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

_Use_decl_annotations_
NDIS_STATUS
 MySetOptions(
    NDIS_HANDLE  NdisDriverHandle,
    NDIS_HANDLE  DriverContext
    )
  {...}

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

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

要件

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