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 型の状態値を返します。 それ以外の場合、このメソッドは次のいずれかの値を返す可能性があります。
| リターン コード | 形容 |
|---|---|
|
入力パラメーターが無効です。 |
|
識別の説明またはアドレスの説明のサイズが正しくありません。 |
|
指定された ID の説明を持つ子が既に存在します。 この場合、フレームワークは、指定されたアドレスの説明を既存の子にコピーします。 |
|
子の説明を割り当てることができる。 |
このメソッドは、他の NTSTATUS 値返す場合もあります。
ドライバーが無効なオブジェクト ハンドルを提供すると、システム バグ チェックが発生します。
備考
WdfChildListAddOrUpdateChildDescriptionAsPresent メソッドは、指定された ID の説明に一致する子を指定した子リストを検索します。 一致するものが見つかった場合、フレームワークは子のアドレスの説明 (指定されている場合) を更新し、STATUS_OBJECT_NAME_EXISTSを返します。 一致するものが見つからない場合、フレームワークは指定された ID とアドレスの説明を使用して新しい子を作成します。
ドライバーは、WdfChildListAddOrUpdateChildDescriptionAsPresent を呼び出して、単一の子の説明を追加または更新できます。 フレームワークは、子リストを直ちに更新し、変更が行われていることをプラグ アンド プレイ (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 |
| ヘッダー | wdfchildlist.h (Wdf.h を含む) |
| ライブラリ | Wdf01000.sys (フレームワーク ライブラリのバージョン管理を参照)。 |
| IRQL | <= DISPATCH_LEVEL |
| DDI コンプライアンス規則 を する | DriverCreate(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf) |
関連項目
EvtChildListCreateDevice の
WDF_CHILD_IDENTIFICATION_DESCRIPTION_HEADER
WDF_CHILD_IDENTIFICATION_DESCRIPTION_HEADER_INIT
WdfFdoGetDefaultChildList の