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

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

NDIS は、ミニポートアダプターにバインドするドライバーを要求するプロトコルドライバーの ProtocolBindAdapterEx 関数を呼び出します。

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

構文

PROTOCOL_BIND_ADAPTER_EX ProtocolBindAdapterEx;

NDIS_STATUS ProtocolBindAdapterEx(
  [in] NDIS_HANDLE ProtocolDriverContext,
  [in] NDIS_HANDLE BindContext,
  [in] PNDIS_BIND_PARAMETERS BindParameters
)
{...}

パラメーター

[in] ProtocolDriverContext

ドライバーが状態と構成情報を保持するドライバー割り当てコンテキスト領域へのハンドル。プロトコルドライバーは、このコンテキスト領域をに渡しました。 NdisRegisterProtocolDriver 関数。

[in] BindContext

このバインド操作の NDIS コンテキスト領域を識別するハンドル。

[in] BindParameters

NDIS によって作成されたNDIS_BIND_PARAMETERS 構造体へのポインター。

戻り値

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

リターンコード	説明
NDIS_STATUS_SUCCESS	ProtocolBindAdapterEx は、基になるミニポートアダプターへのバインドを正常に完了しました。
NDIS_STATUS_PENDING	ProtocolBindAdapterEx はバインド操作を完了せず、操作は非同期的に完了します。プロトコルドライバーは、を呼び出す必要があります。操作が完了したら、NdisCompleteBindAdapterEx 関数を使用します。
NDIS_STATUS_RESOURCES	ProtocolBindAdapterEx は、ドライバーがネットワーク I/O 操作を実行するために必要なリソースを割り当てませんでした。
NDIS_STATUS_XXXまたはNTSTATUS_XXX	プロトコルドライバーによるバインドの設定に失敗しました。通常、このようなエラー状態は、NdisXxx 関数またはカーネルモードサポートルーチンから伝達されます。

注釈

ProtocolBindAdapterEx は必須の関数です。 NDIS は ProtocolBindAdapterEx を呼び出して、プロトコルドライバーがバインドできる基になるミニポートアダプターが使用可能になったときに、バインド操作を実行します。

ProtocolBindAdapterEx は、バインディングコンテキスト情報を維持するのに十分なメモリを割り当て、 NdisOpenAdapterEx 関数を呼び出して、基になるミニポートアダプターに自身をバインドします。 ProtocolBindAdapterEx は、NdisOpenAdapterEx の ProtocolBindingContext パラメーターでバインディングコンテキスト情報へのポインターを渡します。 ProtocolBindAdapterEx は、BindParameters パラメーターから AdapterName メンバーの値を NdisOpenAdapterEx の OpenParameters パラメーターの AdapterName メンバーとして渡します。

ドライバーが NdisOpenAdapterEx を呼び出す前に、ドライバーは BindParameters のポインターを NdisOpenConfigurationEx 関数に渡して、ミニポートアダプターに関連付けられている構成パラメーターを読み取ることができます。

ミニポートアダプターを正常に開いた後、ドライバーは NdisOpenAdapterEx の NdisHandle パラメーターから NdisOpenConfigurationEx にハンドルを渡して、プロトコルバインドの構成パラメーターが格納されているレジストリの場所へのハンドルを取得できます。

ProtocolBindAdapterEx は 、NdisOpenAdapterEx に、プロトコルドライバーがサポートできるメディアの種類を一覧表示する中型の値の配列へのポインターを渡します。このリストは、 NDIS_MEDIUM 型のサブセットです。 NDIS は、OpenParameters の構造体の SelectedMediumIndex パラメーターで選択された中の種類を示します。

NdisOpenAdapterEx がエラー状態を返す場合、ProtocolBindAdapterEx はそのエラー状態を返し、プロトコルドライバーが割り当てたバインドごとのリソースを解放し、直ちに制御を返します。

NdisOpenAdapterEx がNDIS_STATUS_SUCCESSを返す場合、ProtocolBindAdapterEx は、プロトコルドライバーがバインディングでネットワーク I/O を実行するために必要な残りのリソースを割り当てることができます。ドライバーは、ドライバーがネットワーク I/O 操作を追跡するために使用するバインディング固有のコンテキスト情報を構成することもできます。

NdisOpenAdapterEx がNDIS_STATUS_PENDINGを返す場合、NDIS はプロトコルドライバーを呼び出します。Open 操作が完了した後の ProtocolOpenAdapterCompleteEx 関数。 ProtocolOpenAdapterCompleteEx は 、バインド操作を完了できます。 ProtocolBindAdapterEx は、バインドコンテキスト領域に BindContext ハンドルを格納できます。 NDIS は、ドライバーの ProtocolOpenAdapterCompleteEx 関数に入力パラメーターとして ProtocolBindingContext を渡します。

NdisOpenAdapterEx がNDIS_STATUS_PENDINGを返す場合、NDIS は OpenParameters パラメーターで構造体の SelectedMediumIndex メンバーと、NdisOpenAdapterEx が返された後の NdisBindingHandle パラメーターの値を設定します。 NDIS は 、ProtocolOpenAdapterCompleteEx を呼び出す前にこれらの値を設定します。そのため、プロトコルドライバーは、開いているパラメーター構造とプロトコルバインドハンドルを ProtocolBindingContext (または NDIS が ProtocolOpenAdapterCompleteEx を呼び出すまで有効な任意の場所) のコンテキスト領域に格納する必要があります。

プロトコルドライバーは、開いている操作が完了するまで、バインドに OID 要求を行うことはできません。開いている操作が完了した後、バインドは一時停止状態であるため、NDIS がバインドを再起動するまで、プロトコルドライバーは送信要求を行うことができません。

開いている操作が完了すると、 ProtocolBindAdapterEx はNDIS_STATUS_SUCCESSを返してバインド操作を完了できます。 ProtocolBindAdapterEx はNDIS_STATUS_PENDINGを返して、バインディング操作の完了を後で延期できます。 ProtocolBindAdapterEx がNDIS_STATUS_PENDINGを返す場合、ドライバーはを呼び出す必要があります。バインド操作が完了した後の NdisCompleteBindAdapterEx 関数。

プロトコルドライバーは、基になるミニポートアダプターの機能を決定する NDIS_BIND_PARAMETERS 構造体を使用する必要があります。開いている操作が完了した後、基になるメディアに応じて、プロトコルドライバーは NdisOidRequest 関数を呼び出して、追加のミニポートアダプター機能について基になるミニポートドライバー (または NDIS) にクエリを実行できます。 OID 要求の詳細については、「プロトコルドライバー OID 要求」を参照してください。

NDIS はプロトコルドライバーを呼び出すことができますドライバーがを使用してバインドのパケットフィルターを設定した後の ProtocolReceiveNetBufferLists 関数 OID_GEN_CURRENT_PACKET_FILTER Oid。基になるミニポートアダプターが受信パケットにパケットフィルターを使用しない場合は、開いている操作が完了した後に受信インジケーターが有効になります。プロトコルドライバーは、開いている操作が完了した後、 ProtocolStatusEx 関数で状態インジケーターを受け取ることができます。

すべてのプロトコルドライバーは、十分な NET_BUFFER とNET_BUFFER_LIST構造体プールを割り当てる必要があります。ドライバーは、後続の送信操作のためにこれらのプールからネットワークデータ記述子を割り当てます。

ProtocolBindAdapterEx が後続のネットワーク I/O 操作を実行するために必要なリソースを割り当てることができない場合は、既に割り当てられているすべてのリソースを解放し、適切なエラー値を返す必要があります。

NDIS はプロトコルドライバーを呼び出します。基になるミニポートアダプターからのバインド解除をドライバーに要求する ProtocolUnbindAdapterEx 関数。

プロトコルドライバーがミニポートアダプターを正常に開いたが、バインド操作が失敗した場合 (たとえば、OID 要求が失敗した結果)、ドライバーは ProtocolBindAdapterEx または ProtocolUnbindAdapterEx のコンテキスト内からミニポートアダプターを閉じる必要があります。たとえば、ドライバーは ProtocolBindAdapterEx から NdisCloseAdapterEx を呼び出し、ドライバーが ProtocolBindAdapterEx から戻る前に閉じる操作が完了するまで待機します。別の方法として、ドライバーが ProtocolBindAdapterEx からNDIS_STATUS_PENDINGを返した場合、ドライバーは NdisUnbindAdapter 関数を呼び出し、ProtocolUnbindAdapterEx 関数で NdisCloseAdapterEx を呼び出すことができます。

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

例

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

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

PROTOCOL_BIND_ADAPTER_EX MyBindAdapterEx;

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

_Use_decl_annotations_
NDIS_STATUS
 MyBindAdapterEx(
    NDIS_HANDLE  ProtocolDriverContext,
    NDIS_HANDLE  BindContext,
    PNDIS_BIND_PARAMETERS  BindParameters
    )
  {...}

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

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

要件

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