WdfChildListAddOrUpdateChildDescriptionAsPresent 関数 (wdfchildlist.h)
[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 型の状態値を返します。 それ以外の場合、このメソッドは次のいずれかの値を返す可能性があります。
リターン コード | 説明 |
---|---|
|
入力パラメーターが無効です。 |
|
識別の説明またはアドレスの説明のサイズが正しくありません。 |
|
指定された識別記述を持つ子が既に存在します。 この場合、フレームワークは、指定されたアドレスの説明を既存の子にコピーします。 |
|
子の説明を割り当てることができる。 |
このメソッドは、他の NTSTATUS 値も返す場合があります。
ドライバーが無効なオブジェクト ハンドルを提供すると、システム バグ チェックが発生します。
注釈
WdfChildListAddOrUpdateChildDescriptionAsPresent メソッドは、指定された識別の説明に一致する子を指定した子リストを検索します。 一致が見つかった場合、フレームワークは子のアドレスの説明 (指定されている場合) を更新し、STATUS_OBJECT_NAME_EXISTSを返します。 一致するものが見つからない場合、フレームワークは指定された ID とアドレスの説明を使用して新しい子を作成します。
ドライバーは WdfChildListAddOrUpdateChildDescriptionAsPresent を呼び出して、1 つの子説明を追加または更新できます。 フレームワークは、子リストを直ちに更新し、変更が行われたことをプラグ アンド プレイ (PnP) マネージャーに通知します。
または、ドライバーは次の操作を行うことができます。
- WdfChildListBeginScan を呼び出して、更新用の子リストを準備します。
- WdfChildListAddOrUpdateChildDescriptionAsPresent を複数回呼び出して、親デバイスのすべての子の子の説明を追加または更新します。
- WdfChildListEndScan を呼び出して、子リストへの変更を処理します。
ドライバーが 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) |
こちらもご覧ください
WDF_CHILD_IDENTIFICATION_DESCRIPTION_HEADER