PROTOCOL_BIND_ADAPTER_EX コールバック関数 (ndis.h)
NDIS は、ミニポート アダプターにバインドするドライバーを要求するプロトコル ドライバーの ProtocolBindAdapterEx 関数を呼び出します。
構文
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 は 、次のいずれかの状態値を返します。
| リターン コード | 説明 |
|---|---|
|
ProtocolBindAdapterEx は、基になるミニポート アダプターへのバインドを正常に完了しました。 |
|
ProtocolBindAdapterEx はバインド操作を完了せず、操作は非同期的に完了します。 プロトコル ドライバーは、 を呼び出す必要があります。操作が完了したら、NdisCompleteBindAdapterEx 関数を使用します。 |
|
ProtocolBindAdapterEx は、ドライバーがネットワーク I/O 操作を実行するために必要なリソースを割り当てませんでした。 |
|
プロトコル ドライバーによるバインドの設定に失敗しました。 通常、このようなエラー状態は 、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 |