WdfChildListRetrieveNextDevice 関数 (wdfchildlist.h)
[KMDF にのみ適用]
WdfChildListRetrieveNextDevice メソッドは、指定した子リストを走査し、指定した条件に一致する次の子デバイスを取得します。
構文
NTSTATUS WdfChildListRetrieveNextDevice(
[in] WDFCHILDLIST ChildList,
[in] PWDF_CHILD_LIST_ITERATOR Iterator,
[out] WDFDEVICE *Device,
[in, out] PWDF_CHILD_RETRIEVE_INFO Info
);
パラメーター
[in] ChildList
フレームワークの子リスト オブジェクトへのハンドル。
[in] Iterator
ドライバーが WdfChildListBeginIteration に以前に指定したのと同じ呼び出し元割り当てWDF_CHILD_LIST_ITERATOR構造体へのポインター。
[out] Device
フレームワーク デバイス オブジェクトへのハンドルを受け取る場所へのポインター。 Iterator パラメーターが WdfRetrievePendingChildren フラグを指定している場合、受け取った値は NULL です。
[in, out] Info
呼び出し元によって割り当てられた WDF_CHILD_RETRIEVE_INFO 構造体へのポインター。 このポインターは省略可能であり、 NULL にすることができます。
戻り値
WdfChildListRetrieveNextDevice は、STATUS_SUCCESS、または操作が成功した場合 、NT_SUCCESS(status) が TRUE に等しい別の状態値を返します。 それ以外の場合、このメソッドは次のいずれかの値を返す可能性があります。
| リターン コード | 説明 |
|---|---|
|
入力パラメーターが無効です。 |
|
Iterator が指定したWDF_CHILD_LIST_ITERATOR構造体のサイズが正しくありません |
|
アドレスの説明が指定されましたが、子リストにアドレスの説明が含まれていませんでした。 |
|
フレームワークが子リストの最後に達しました。 |
|
ドライバーが WdfChildListBeginIteration を呼び出していません。 |
このメソッドは、他の NTSTATUS 値も返す場合があります。
ドライバーが無効なオブジェクト ハンドルを提供すると、システム バグ チェックが発生します。
注釈
WdfChildListRetrieveNextDevice を呼び出す前に、ドライバーで WdfChildListBeginIteration を呼び出す必要があります。 ドライバーが子リストの走査を完了したら、 WdfChildListEndIteration を呼び出す必要があります。 その後、フレームワークは、子リストに加えられた変更をプラグ アンド プレイ (PnP) マネージャーに通知します。
ドライバーが WdfChildListRetrieveNextDevice を呼び出すたびに、メソッドは次の検索条件に一致する次の子を取得します。
- 子の型は、ドライバーの WDF_CHILD_LIST_ITERATOR構造体の WDF_RETRIEVE_CHILD_FLAGS 型指定フラグに対応している必要があります。
- ドライバーが EvtChildListIdentificationDescriptionCompare コールバック関数へのポインターを WDF_CHILD_RETRIEVE_INFO 構造体で提供する場合、コールバック関数は TRUE を返す必要があります。
WdfChildListRetrieveNextDevice が一致を検出すると、Info パラメーターが指定するポインターが NULL でない場合は、子の識別の説明とアドレスの説明がドライバーのWDF_CHILD_RETRIEVE_INFO構造体にコピーされます。 (この操作により、ドライバーの入力 ID の説明が上書きされることに注意してください)。メソッドは、 Device パラメーターが識別する場所に、子のデバイス オブジェクトへのハンドルも配置します。
子リストの詳細については、「 動的列挙」を参照してください。
例
次のコード例では、親デバイスのすべての子が取り出されていることをフレームワークに通知します。 この例では、デバイスの既定の子リストを取得し、一覧を説明します。 各子の識別記述子を取得し、各識別記述子を WdfChildListRequestChildEject に渡します。
WDF_CHILD_LIST_ITERATOR iterator;
WDFDEVICE hChild;
NTSTATUS status = STATUS_INVALID_PARAMETER;
WDFCHILDLIST list;
WDF_CHILD_RETRIEVE_INFO childInfo;
PDO_IDENTIFICATION_DESCRIPTION description;
BOOLEAN ret;
list = WdfFdoGetDefaultChildList(Device);
WDF_CHILD_LIST_ITERATOR_INIT(
&iterator,
WdfRetrievePresentChildren
);
WdfChildListBeginIteration(
list,
&iterator
);
for (;;) {
WDF_CHILD_RETRIEVE_INFO_INIT(
&childInfo,
&description.Header
);
WDF_CHILD_IDENTIFICATION_DESCRIPTION_HEADER_INIT(
&description.Header,
sizeof(description)
);
status = WdfChildListRetrieveNextDevice(
list,
&iterator,
&hChild,
&childInfo
);
if (!NT_SUCCESS(status) || status == STATUS_NO_MORE_ENTRIES) {
break;
}
ASSERT(childInfo.Status == WdfChildListRetrieveDeviceSuccess);
ret = WdfChildListRequestChildEject(
list,
&description.Header
);
if(!ret) {
WDFVERIFY(ret);
}
}
WdfChildListEndIteration(
list,
&iterator
);
if (status == STATUS_NO_MORE_ENTRIES) {
status = STATUS_SUCCESS;
}
return status;
要件
| 要件 | 値 |
|---|---|
| 対象プラットフォーム | ユニバーサル |
| 最小 KMDF バージョン | 1.0 |
| Header | wdfchildlist.h (Wdf.h を含む) |
| Library | Wdf01000.sys (「Framework ライブラリのバージョン管理」を参照)。 |
| IRQL | <= DISPATCH_LEVEL |
| DDI コンプライアンス規則 | DriverCreate(kmdf)、 KmdfIrql(kmdf)、 KmdfIrql2(kmdf)、KmdfIrqlExplicit(kmdf) |
こちらもご覧ください
EvtChildListIdentificationDescriptionCompare