WdfChildListAddOrUpdateChildDescriptionAsPresent-Funktion (wdfchildlist.h)

Artikel
02/07/2025

[Gilt nur für KMDF]

Die WdfChildListAddOrUpdateChildDescriptionAsPresent-Methode fügt einer Liste der untergeordneten Elemente eine neue untergeordnete Beschreibung hinzu oder aktualisiert eine vorhandene untergeordnete Beschreibung.

Syntax

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

Parameter

[in] ChildList

Ein Handle für ein untergeordnetes Listenobjekt des Frameworks.

[in] IdentificationDescription

Ein Zeiger auf eine WDF_CHILD_IDENTIFICATION_DESCRIPTION_HEADER Struktur, die eine untergeordnete Identifikationsbeschreibungidentifiziert.

[in, optional] AddressDescription

Ein Zeiger auf eine WDF_CHILD_ADDRESS_DESCRIPTION_HEADER Struktur, die eine untergeordnete Adressbeschreibungidentifiziert. Wenn keine Adressbeschreibung erforderlich ist, kann dieser Parameter NULL-werden.

Rückgabewert

WdfChildListAddOrUpdateChildDescriptionAsPresent gibt STATUS_SUCCESS oder einen anderen NTSTATUS-Typ-Statuswert zurück, für den NT_SUCCESS(status)TRUE-entspricht, wenn der Vorgang erfolgreich ist. Andernfalls gibt diese Methode möglicherweise einen der folgenden Werte zurück:

Rückgabecode	Beschreibung
STATUS_INVALID_PARAMETER	Ein Eingabeparameter war ungültig.
STATUS_INVALID_DEVICE_REQUEST	Die Größe der Identifikationsbeschreibung oder Adressbeschreibung war falsch.
STATUS_OBJECT_NAME_EXISTS	Ein Kind mit der angegebenen Identifikationsbeschreibung ist bereits vorhanden. In diesem Fall kopiert das Framework die angegebene Adressbeschreibung in das vorhandene untergeordnete Element.
STATUS_INSUFFICIENT_RESOURCES	Eine untergeordnete Beschreibung könnte zugewiesen werden.

Diese Methode kann auch andere NTSTATUS-Wertezurückgeben.

Eine Systemfehlerüberprüfung tritt auf, wenn der Treiber ein ungültiges Objekthandle bereitstellt.

Bemerkungen

Die WdfChildListAddOrUpdateChildDescriptionAsPresent Methode durchsucht die angegebene untergeordnete Liste nach einem untergeordneten Element, das der angegebenen Identifikationsbeschreibung entspricht. Wenn eine Übereinstimmung gefunden wird, aktualisiert das Framework die Adressbeschreibung des untergeordneten Elements, sofern angegeben, und gibt STATUS_OBJECT_NAME_EXISTS zurück. Wenn keine Übereinstimmung gefunden wird, erstellt das Framework ein neues untergeordnetes Element mithilfe der angegebenen Identifikations- und Adressbeschreibungen.

Ein Treiber kann WdfChildListAddOrUpdateChildDescriptionAsPresent- aufrufen, um eine einzelne untergeordnete Beschreibung hinzuzufügen oder zu aktualisieren. Das Framework aktualisiert sofort die untergeordnete Liste und informiert den Plug and Play -Manager (PnP), dass Änderungen vorgenommen wurden.

Alternativ kann der Treiber die folgenden Aktionen ausführen:

Rufen Sie WdfChildListBeginScan- auf, um die untergeordnete Liste für die Aktualisierung vorzubereiten.
Rufen Sie WdfChildListAddOrUpdateChildDescriptionAsPresent mehrmals auf, um die untergeordneten Beschreibungen für alle untergeordneten Elemente des übergeordneten Geräts hinzuzufügen oder zu aktualisieren.
Rufen Sie WdfChildListEndScan- auf, um Änderungen an der untergeordneten Liste zu verarbeiten.

Wenn der Treiber diese alternative Prozedur verwendet, wartet das Framework, bis der Treiber WdfChildListEndScan- aufruft, bevor er die untergeordnete Liste aktualisiert und den PnP-Manager darüber informiert, dass Änderungen vorgenommen wurden. Wenn Ihr Treiber WdfChildListBeginScanaufruft, markiert das Framework alle zuvor gemeldeten Geräte als nicht mehr vorhanden. Daher muss der Treiber WdfChildListAddOrUpdateChildDescriptionAsPresent für alle untergeordneten Elemente aufrufen, nicht nur neu entdeckte Untergeordnete.

Wenn ein Treiber WdfChildListAddOrUpdateChildDescriptionAsPresent-aufruft, ruft das Framework die EvtChildListCreateDevice Rückruffunktion auf, damit der Treiber ein Geräteobjekt erstellen kann, indem WdfDeviceCreateaufgerufen wird.

Weitere Informationen zu untergeordneten Listen finden Sie unter dynamische Enumeration.

Beispiele

Das folgende Codebeispiel basiert auf Code, den das kmdf_fx2 Beispiel enthält. Im Beispiel werden der Standardliste untergeordneter Elemente eines Geräts untergeordnete Beschreibungen hinzugefügt. Er ruft die Switcheinstellungen ab, die der Treiber zuvor im Kontextbereich eines Geräteobjekts gespeichert hat, und ruft dann WdfChildListAddOrUpdateChildDescriptionAsPresent für jeden festgelegten Switch auf.

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);

Anforderungen

Anforderung	Wert
Zielplattform-	Universal
Minimale KMDF-Version	1.0
Header-	wdfchildlist.h (include Wdf.h)
Library	Wdf01000.sys (siehe Framework-Bibliotheksversionsverwaltung.)
IRQL-	<= DISPATCH_LEVEL
DDI-Complianceregeln	DriverCreate(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf)