WdfCollectionAdd-Funktion (wdfcollection.h)

Artikel
02/29/2024

[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 für ein Auflistungsobjekt.

[in] Object

Ein Handle für das 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-Werte zurückgeben.

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

Hinweise

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, wird die Verweisanzahl des Objekts erhöht. Ihr Treiber kann WdfCollectionRemove oder WdfCollectionRemoveItem aufrufen, um das Objekt zu entfernen und seine Verweisanzahl zu verringern.

Weitere Informationen zu Objektsammlungen finden Sie unter Framework-Objektsammlungen.

Beispiele

Im folgenden Codebeispiel wird ein Auflistungsobjekt erstellt und dann eine Reihe von vom Treiber erstellten Anforderungsobjekten zur Auflistung 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	Universell
KMDF-Mindestversion	1.0
UMDF-Mindestversion	2.0
Kopfzeile	wdfcollection.h (einschließen von Wdf.h)
Bibliothek	Wdf01000.sys (KMDF); WUDFx02000.dll (UMDF)
IRQL	<= DISPATCH_LEVEL
DDI-Complianceregeln	DriverCreate(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf)

Weitere Informationen

WdfCollectionCreate

WdfCollectionRemove

WdfCollectionRemoveItem

Freigeben über