WdfChildListAddOrUpdateChildDescriptionAsPresent 関数 (wdfchildlist.h)

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

[KMDF にのみ適用]

WdfChildListAddOrUpdateChildDescriptionAsPresent メソッドは、子のリストに新しい子の説明を追加するか、既存の子の説明を更新します。

構文

NTSTATUS WdfChildListAddOrUpdateChildDescriptionAsPresent(
  [in]           WDFCHILDLIST                                 ChildList,
  [in]           PWDF_CHILD_IDENTIFICATION_DESCRIPTION_HEADER IdentificationDescription,
  [in, optional] PWDF_CHILD_ADDRESS_DESCRIPTION_HEADER        AddressDescription
);

パラメーター

[in] ChildList

フレームワークの子リストオブジェクトへのハンドル。

[in] IdentificationDescription

子識別の説明を識別するWDF_CHILD_IDENTIFICATION_DESCRIPTION_HEADER構造体へのポインター。

[in, optional] AddressDescription

子アドレスの説明を識別するWDF_CHILD_ADDRESS_DESCRIPTION_HEADER構造体へのポインター。アドレスの説明が不要な場合は、このパラメーターに NULL を指定できます。

戻り値

WdfChildListAddOrUpdateChildDescriptionAsPresent は、STATUS_SUCCESS、または操作が成功した場合に、NT_SUCCESS(status) が TRUE に等しい別の NTSTATUS 型の状態値を返します。それ以外の場合、このメソッドは次のいずれかの値を返す可能性があります。

リターンコード	説明
STATUS_INVALID_PARAMETER	入力パラメーターが無効です。
STATUS_INVALID_DEVICE_REQUEST	識別の説明またはアドレスの説明のサイズが正しくありません。
STATUS_OBJECT_NAME_EXISTS	指定された識別記述を持つ子が既に存在します。この場合、フレームワークは、指定されたアドレスの説明を既存の子にコピーします。
STATUS_INSUFFICIENT_RESOURCES	子の説明を割り当てることができる。

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

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

注釈

WdfChildListAddOrUpdateChildDescriptionAsPresent メソッドは、指定された識別の説明に一致する子を指定した子リストを検索します。一致が見つかった場合、フレームワークは子のアドレスの説明 (指定されている場合) を更新し、STATUS_OBJECT_NAME_EXISTSを返します。一致するものが見つからない場合、フレームワークは指定された ID とアドレスの説明を使用して新しい子を作成します。

ドライバーは WdfChildListAddOrUpdateChildDescriptionAsPresent を呼び出して、1 つの子説明を追加または更新できます。フレームワークは、子リストを直ちに更新し、変更が行われたことをプラグアンドプレイ (PnP) マネージャーに通知します。

または、ドライバーは次の操作を行うことができます。

WdfChildListBeginScan を呼び出して、更新用の子リストを準備します。
WdfChildListAddOrUpdateChildDescriptionAsPresent を複数回呼び出して、親デバイスのすべての子の子の説明を追加または更新します。
WdfChildListEndScan を呼び出して、子リストへの変更を処理します。

ドライバーがこの代替プロシージャを使用する場合、フレームワークは、ドライバーが WdfChildListEndScan を呼び出すまで待機してから、子リストを更新し、変更が行われたことを PnP マネージャーに通知します。ドライバーが WdfChildListBeginScan を呼び出すと、フレームワークは、以前に報告されたすべてのデバイスが存在しなくなったとマークします。そのため、ドライバーは、新しく検出された子だけでなく、すべての子に対して WdfChildListAddOrUpdateChildDescriptionAsPresent を呼び出す必要があります。

ドライバーが WdfChildListAddOrUpdateChildDescriptionAsPresent を呼び出した後、ある時点で、フレームワークはドライバーの EvtChildListCreateDevice コールバック関数を呼び出して、ドライバーが WdfDeviceCreate を呼び出してデバイスオブジェクトを作成できるようにします。

子リストの詳細については、「動的列挙」を参照してください。

例

次のコード例は、 kmdf_fx2 サンプルに含まれるコードに基づいています。この例では、デバイスの既定の子リストに子の説明を追加します。ドライバーが以前にデバイスオブジェクトのコンテキスト空間に格納したスイッチ設定を取得し、設定されている各スイッチに対して WdfChildListAddOrUpdateChildDescriptionAsPresent を呼び出します。

PDEVICE_CONTEXT  pDeviceContext;
WDFCHILDLIST  list;
UCHAR  i;
NTSTATUS  status;

pDeviceContext = GetDeviceContext(Device);
list = WdfFdoGetDefaultChildList(Device);

WdfChildListBeginScan(list);
 
for (i = 0; i < RTL_BITS_OF(UCHAR); i++) {
    if (pDeviceContext->CurrentSwitchState & (1<<i)) {
        PDO_IDENTIFICATION_DESCRIPTION description;
        WDF_CHILD_IDENTIFICATION_DESCRIPTION_HEADER_INIT(
                                                 &description.Header,
                                                 sizeof(description)
                                                 );
        description.SwitchNumber = i; 
 
        status = WdfChildListAddOrUpdateChildDescriptionAsPresent(
                                                 list, 
                                                 &description.Header, 
                                                 NULL
                                                 );
        if (!NT_SUCCESS(status) && (status != STATUS_OBJECT_NAME_EXISTS)) {
            break;
        }
    }
}
WdfChildListEndScan(list);

要件

要件	値
対象プラットフォーム	ユニバーサル
最小 KMDF バージョン	1.0
Header	wdfchildlist.h (Wdf.h を含む)
Library	Wdf01000.sys (「Framework ライブラリのバージョン管理」を参照)。
IRQL	<= DISPATCH_LEVEL
DDI コンプライアンス規則	DriverCreate(kmdf)、 KmdfIrql(kmdf)、 KmdfIrql2(kmdf)、KmdfIrqlExplicit(kmdf)