IoReportResourceForDetection 関数 (ntddk.h)
IoReportResourceForDetection ルーチンは、レガシ デバイスの構成レジストリ内のハードウェア リソースを要求します。
構文
NTSTATUS IoReportResourceForDetection(
[in] PDRIVER_OBJECT DriverObject,
[in, optional] PCM_RESOURCE_LIST DriverList,
[in, optional] ULONG DriverListSize,
[in, optional] PDEVICE_OBJECT DeviceObject,
[in, optional] PCM_RESOURCE_LIST DeviceList,
[in, optional] ULONG DeviceListSize,
[out] PBOOLEAN ConflictDetected
);
パラメーター
[in] DriverObject
ドライバーの DriverEntry ルーチンに入力されたドライバー オブジェクトへのポインター。
[in, optional] DriverList
ドライバーがすべてのデバイスに対して同じリソースを要求する場合は、必要に応じて、ドライバーのリソース 一覧を含む呼び出し元が指定したバッファーを指します。 呼び出し元が DeviceList を指定した場合、このパラメーターは無視されます。
[in, optional] DriverListSize
省略可能な DriverList のサイズをバイト単位で指定します。 DriverList が NULL の場合、このパラメーターは 0 である必要があります。
[in, optional] DeviceObject
必要に応じて、ドライバーがリソースを要求しようとしているデバイスを表すデバイス オブジェクトを指します。
[in, optional] DeviceList
必要に応じて、デバイスのリソース リストを含む呼び出し元が指定したバッファーを指します。 ドライバーがすべてのデバイスに対して同じリソースを要求する場合、呼び出し元は代わりに DriverList を指定できます。
[in, optional] DeviceListSize
省略可能な DeviceList のサイズをバイト単位で指定します。 DeviceList が NULL の場合、このパラメーターは 0 である必要があります。
[out] ConflictDetected
リソースが使用できない場合、戻り値として TRUE に設定されている呼び出し元が指定したブール値へのポインター。
戻り値
IoReportResourceForDetection は 、リソースが要求された場合にSTATUS_SUCCESSを返します。 考えられるエラーの戻り値は次のとおりです。
| リターン コード | 説明 |
|---|---|
| STATUS_CONFLICTING_ADDRESSES | リソースは既に使用されているか、PnP 列挙可能なデバイスに必要であるため、要求できませんでした。 |
| STATUS_UNSUCCESSFUL | DeviceList または DriverList が無効です。 |
注釈
このルーチンは、プラグ アンド プレイ (PnP) で列挙できない以前のハードウェアを検出するドライバー用です。
ドライバーが PnP ハードウェアのみをサポートしている場合、検出は行われないため、 IoReportResourceForDetection は呼び出されません。 PnP システムは、各 PnP デバイスを列挙し、デバイスにリソースを割り当て、それらのリソースを IRP_MN_START_DEVICE 要求でデバイスのドライバーに渡します。
ただし、PnP ドライバーがレガシ ハードウェアをサポートしている場合は、デバイスの検出を試みる前に 、IoReportResourceForDetection を呼び出してハードウェア リソースを要求する必要があります。
このルーチンの呼び出し元は、ページ メモリから割り当てられ、未変換の リソースで構成 される DeviceList または DriverList のCM_RESOURCE_LISTを指定します。 呼び出し元は、メモリの解放を担当します。
複数のレガシ カードを同時に制御できるドライバーは、各デバイスのデバイス オブジェクトに対して各デバイスのリソースを要求する必要があります (DeviceObject、DeviceList、および DeviceListSize パラメーターを使用)。 このようなドライバーは、ドライバー オブジェクトに対してこれらのリソースを要求してはなりません。
CM_RESOURCE_LISTには、2 つの可変サイズの配列が含まれています。 各配列の既定のサイズは 1 です。 いずれかの配列に複数の要素がある場合、呼び出し元は追加の要素を格納するためにメモリを動的に割り当てる必要があります。 配列 に 追加の部分リソース記述子を含めることができる CM_RESOURCE_LIST の最後の完全なリソース記述子を除き、リスト内の各CM_FULL_RESOURCE_DESCRIPTORに含めることができる CM_PARTIAL_RESOURCE_DESCRIPTORは 1 つだけです。
IoReportResourceForDetection は、PnP マネージャーの助けを借りて、要求されているリソースが既に要求されているリソースと競合するかどうかを決定します。
競合が検出された場合、このルーチンは ConflictDetected の BOOLEAN を TRUE に設定し、STATUS_CONFLICTING_ADDRESSESを返します。
競合が検出されない場合、このルーチンはリソースを要求し、 ConflictDetected の BOOLEAN を FALSE に設定し、STATUS_SUCCESSを返します。
このルーチンが成功し、ドライバーがレガシ デバイスを検出した場合、ドライバーは IoReportDetectedDevice を呼び出して PnP マネージャーにデバイスを報告します。 この呼び出しでは、ドライバーは ResourceAssigned を TRUE に設定して、PnP マネージャーがリソースの要求を再試行しないようにします。
ドライバーが、このルーチンの呼び出しによって要求されたリソースを必要としなくなると、ドライバーは、このルーチンを再び呼び出し、 DriverList または DeviceList の Count を 0 にします。
ドライバーが複数のデバイスに対してデバイス固有のリソースを要求する場合、ドライバーは、このようなデバイスごとにこのルーチンを呼び出す必要があります。
ドライバーは、特定のデバイスに対してこのルーチンを複数回呼び出すことができます。 1 つのリソース セットが失敗した場合、ドライバーは、リソースの異なるセットを持つ同じデバイスに対してルーチンを再度呼び出すことができます。 一連のリソースが成功した場合、ドライバーは新しいリストを使用してこのルーチンを再度呼び出すことができます。新しいリストは、前のリストを置き換えます。
IoReportResourceForDetection の呼び出し元は、システム スレッドのコンテキストで IRQL = PASSIVE_LEVELで実行されている必要があります。
要件
| 要件 | 値 |
|---|---|
| 対象プラットフォーム | ユニバーサル |
| Header | ntddk.h (Ntddk.h を含む) |
| Library | NtosKrnl.lib |
| [DLL] | NtosKrnl.exe |
| IRQL | PASSIVE_LEVEL (「解説」セクションを参照) |