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 等しい別の状態値を返します。 それ以外の場合、このメソッドは次のいずれかの値を返す可能性があります。
| リターン コード | 形容 |
|---|---|
|
入力パラメーターが無効です。 |
|
指定された反復子 WDF_CHILD_LIST_ITERATOR 構造体のサイズが正しくありません |
|
アドレスの説明が指定されましたが、子リストにアドレスの説明が含まれていませんでした。 |
|
フレームワークが子リストの末尾に達しました。 |
|
ドライバーが WdfChildListBeginIteration 呼び出していません。 |
このメソッドは、他の NTSTATUS 値返す場合もあります。
ドライバーが無効なオブジェクト ハンドルを提供すると、システム バグ チェックが発生します。
備考
WdfChildListRetrieveNextDevice 呼び出す前に、ドライバーは WdfChildListBeginIteration 呼び出す必要があります。 ドライバーは、子リストの走査が完了したら、WdfChildListEndIterationを呼び出す必要があります。 その後、フレームワークは、子リストに加えられた変更をプラグ アンド プレイ (PnP) マネージャーに通知します。
ドライバーが WdfChildListRetrieveNextDevice 呼び出すたびに、メソッドは次の検索条件に一致する次の子を取得します。
- 子の型は、ドライバーの WDF_CHILD_LIST_ITERATOR 構造体 WDF_RETRIEVE_CHILD_FLAGS型指定されたフラグに対応している必要があります。
- ドライバーが WDF_CHILD_RETRIEVE_INFO 構造体の EvtChildListIdentificationDescriptionCompare コールバック関数へのポインターを提供する場合、コールバック関数は 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 |
| ヘッダー | wdfchildlist.h (Wdf.h を含む) |
| ライブラリ | Wdf01000.sys (フレームワーク ライブラリのバージョン管理を参照)。 |
| IRQL | <= DISPATCH_LEVEL |
| DDI コンプライアンス規則 を する | DriverCreate(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf) |
関連項目
EvtChildListIdentificationDescriptionCompare の
WDF_CHILD_IDENTIFICATION_DESCRIPTION_HEADER_INIT
WdfChildListEndIteration の
WdfChildListRetrieveNextDevice の