WdfChildListAddOrUpdateChildDescriptionAsPresent-Funktion (wdfchildlist.h)

Artikel
08/08/2023

[Gilt nur für KMDF]

Die WdfChildListAddOrUpdateChildDescriptionAsPresent-Methode fügt einer Liste von untergeordneten Elementen 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 beschreibung der untergeordneten Identifizierung identifiziert.

[in, optional] AddressDescription

Ein Zeiger auf eine WDF_CHILD_ADDRESS_DESCRIPTION_HEADER Struktur, die eine untergeordnete Adressbeschreibung identifiziert. Wenn keine Adressbeschreibung erforderlich ist, kann dieser Parameter NULL sein.

Rückgabewert

WdfChildListAddOrUpdateChildDescriptionAsPresent gibt STATUS_SUCCESS oder einen anderen NTSTATUS-typisierten status Wert zurück, für den NT_SUCCESS(status)gleich TRUE ist, 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 Identifikations- oder Adressbeschreibung war falsch.
STATUS_OBJECT_NAME_EXISTS	Ein untergeordnetes Element 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 kann zugeordnet werden.

Diese Methode gibt möglicherweise auch andere NTSTATUS-Werte zurück.

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

Hinweise

Die WdfChildListAddOrUpdateChildDescriptionAsPresent-Methode durchsucht die angegebene untergeordnete Liste nach einem untergeordneten Element, das der angegebenen Identifizierungsbeschreibung 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 mithilfe der angegebenen Identifizierungs- und Adressbeschreibungen ein neues untergeordnetes Element.

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 & 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 dieses alternative Verfahren verwendet, wartet das Framework, bis der Treiber WdfChildListEndScan aufruft , bevor es die untergeordnete Liste aktualisiert und den PnP-Manager darüber informiert, dass Änderungen vorgenommen wurden. Wenn Ihr Treiber WdfChildListBeginScan aufruft, 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 für neu ermittelte untergeordnete Elemente.

Zu einem bestimmten Zeitpunkt, nachdem ein Treiber WdfChildListAddOrUpdateChildDescriptionAsPresent aufgerufen hat, ruft das Framework die EvtChildListCreateDevice-Rückruffunktion des Treibers auf, damit der Treiber durch Aufrufen von WdfDeviceCreate ein Geräteobjekt erstellen kann.

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 standardmäßigen untergeordneten Liste eines Geräts untergeordnete Beschreibungen hinzugefügt. Es ruft 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	Universell
KMDF-Mindestversion	1.0
Kopfzeile	wdfchildlist.h (include Wdf.h)
Bibliothek	Wdf01000.sys (siehe Versionsverwaltung der Frameworkbibliothek).)
IRQL	<= DISPATCH_LEVEL
DDI-Complianceregeln	DriverCreate(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf)