WdfCollectionAdd-Funktion (wdfcollection.h)

Artikel
02/07/2025

[Gilt für KMDF und UMDF]

Die WdfCollectionAdd--Methode fügt einer Objektauflistung ein angegebenes Frameworkobjekt hinzu.

Syntax

NTSTATUS WdfCollectionAdd(
  [in] WDFCOLLECTION Collection,
  [in] WDFOBJECT     Object
);

Parameter

[in] Collection

Ein Handle zu einem Auflistungsobjekt.

[in] Object

Ein Handle zum Frameworkobjekt, das der Auflistung hinzugefügt wird.

Rückgabewert

WdfCollectionAdd gibt STATUS_SUCCESS zurück, wenn der Vorgang erfolgreich ist. Andernfalls gibt diese Methode möglicherweise einen der folgenden Werte zurück:

Rückgabecode	Beschreibung
STATUS_UNSUCCESSFUL	Das angegebene Objekt konnte der angegebenen Auflistung nicht hinzugefügt werden.

Diese Methode kann auch andere NTSTATUS-Wertezurückgeben.

Wenn der Treiber ein ungültiges Objekthandle bereitstellt, tritt eine Fehlerüberprüfung auf.

Bemerkungen

Die WdfCollectionAdd- -Methode fügt das angegebene Objekt an das Ende der Gruppe von Objekten an, die die Auflistung enthält. Wenn WdfCollectionAdd einer Auflistung ein Objekt hinzufügt, erhöht es die Referenzanzahl des Objekts. Ihr Treiber kann WdfCollectionRemove- oder WdfCollectionRemoveItem- aufrufen, um das Objekt zu entfernen und die Referenzanzahl zu erhöhen.

Weitere Informationen zu Objektsammlungen finden Sie unter Framework-Objektsammlungen.

Beispiele

Im folgenden Codebeispiel wird ein Auflistungsobjekt erstellt und dann der Auflistung eine Reihe von vom Treiber erstellten Anforderungsobjekten hinzugefügt.

WDF_OBJECT_ATTRIBUTES  attributes;
NTSTATUS  status;
WDFCOLLECTION  hCollection = NULL;
WDFREQUEST  subRequest = NULL;

WDF_OBJECT_ATTRIBUTES_INIT(&attributes);
attributes.ParentObject = Request;
status = WdfCollectionCreate(
                             &attributes,
                             &hCollection
                             );
if (!NT_SUCCESS(status)) {
    goto Exit;
}

for (i = 0; i < numSubRequests; i++) {
    WDF_OBJECT_ATTRIBUTES_INIT(&attributes);
    WDF_OBJECT_ATTRIBUTES_SET_CONTEXT_TYPE(
                                           &attributes,
                                           SUB_REQUEST_CONTEXT
                                           );
    status = WdfRequestCreate(
                              &attributes,
                              WdfUsbTargetDeviceGetIoTarget(deviceContext->WdfUsbTargetDevice),
                              &subRequest
                              );
    if (!NT_SUCCESS(status)) {
        goto Exit;
    }
    status = WdfCollectionAdd(
                              hCollection,
                              subRequest
                              );
    if (!NT_SUCCESS(status)) {
        WdfObjectDelete(subRequest);
        goto Exit;
    }
}

Anforderungen

Anforderung	Wert
Zielplattform-	Universal
Minimale KMDF-Version	1.0
Mindest-UMDF-Version	2.0
Header-	wdfcollection.h (include Wdf.h)
Library	Wdf01000.sys (KMDF); WUDFx02000.dll (UMDF)
IRQL-	<= DISPATCH_LEVEL
DDI-Complianceregeln	DriverCreate(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf)

Siehe auch

WdfCollectionCreate

WdfCollectionRemove-

WdfCollectionRemoveItem-

Freigeben über