WdfChildListRetrieveNextDevice 関数 (wdfchildlist.h)

[アーティクル]
02/27/2024

[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 に等しい別の状態値を返します。それ以外の場合、このメソッドは次のいずれかの値を返す可能性があります。

リターンコード	説明
STATUS_INVALID_PARAMETER	入力パラメーターが無効です。
STATUS_INFO_LENGTH_MISMATCH	Iterator が指定したWDF_CHILD_LIST_ITERATOR構造体のサイズが正しくありません
STATUS_INVALID_DEVICE_REQUEST	アドレスの説明が指定されましたが、子リストにアドレスの説明が含まれていませんでした。
STATUS_NO_MORE_ENTRIES	フレームワークが子リストの最後に達しました。
STATUS_INVALID_DEVICE_STATE	ドライバーが WdfChildListBeginIteration を呼び出していません。

このメソッドは、他の NTSTATUS 値も返す場合があります。

ドライバーが無効なオブジェクトハンドルを提供すると、システムバグチェックが発生します。

注釈

WdfChildListRetrieveNextDevice を呼び出す前に、ドライバーで WdfChildListBeginIteration を呼び出す必要があります。ドライバーが子リストの走査を完了したら、 WdfChildListEndIteration を呼び出す必要があります。その後、フレームワークは、子リストに加えられた変更をプラグアンドプレイ (PnP) マネージャーに通知します。

ドライバーが WdfChildListRetrieveNextDevice を呼び出すたびに、メソッドは次の検索条件に一致する次の子を取得します。

子の型は、ドライバーの WDF_CHILD_LIST_ITERATOR構造体の WDF_RETRIEVE_CHILD_FLAGS 型指定フラグに対応している必要があります。
ドライバーが EvtChildListIdentificationDescriptionCompare コールバック関数へのポインターを WDF_CHILD_RETRIEVE_INFO 構造体で提供する場合、コールバック関数は TRUE を返す必要があります。

ドライバーが EvtChildListIdentificationDescriptionCompare コールバック関数を提供する場合は、WDF_CHILD_RETRIEVE_INFO構造体に識別の説明も指定する必要があります。フレームワークは、コールバック関数を使用して、渡された識別記述子を子リスト内の子の説明と比較します(WDF_RETRIEVE_CHILD_FLAGS型指定フラグが子が一致候補であることを示している場合)。コールバック関数が TRUE を返した場合、一致は成功します。コールバック関数が FALSE を返す場合、フレームワークは別の候補を探します。

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)