Funzione WdfCollectionAdd (wdfcollection.h)

Articolo
07/02/2025

[Si applica a KMDF e UMDF]

Il metodo WdfCollectionAdd aggiunge un oggetto framework specificato a un insieme di oggetti.

Sintassi

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

Parametri

[in] Collection

Handle di un insieme.

[in] Object

Handle per l'oggetto framework che verrà aggiunto all'insieme.

Valore restituito

WdfCollectionAdd restituisce STATUS_SUCCESS se l'operazione ha esito positivo. In caso contrario, questo metodo potrebbe restituire uno dei valori seguenti:

Codice restituito	Descrizione
STATUS_UNSUCCESSFUL	Impossibile aggiungere l'oggetto specificato all'insieme specificato.

Questo metodo può anche restituire altri valori NTSTATUS .

Se il driver fornisce un handle di oggetto non valido, si verifica un controllo di bug.

Osservazioni

Il metodo WdfCollectionAdd accoda l'oggetto specificato alla fine del set di oggetti contenuti nell'insieme. Quando WdfCollectionAdd aggiunge un oggetto a una raccolta, incrementa il conteggio dei riferimenti dell'oggetto. Il driver può chiamare WdfCollectionRemove o WdfCollectionRemoveItem per rimuovere l'oggetto e decrementare il numero di riferimenti.

Per altre informazioni sugli insiemi di oggetti, vedere Framework Object Collections.

Esempi

Nell'esempio di codice seguente viene creato un oggetto raccolta e quindi viene aggiunto un set di oggetti richiesta creati dal driver all'insieme.

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

Fabbisogno

Requisito	Valore
piattaforma di destinazione	Universale
versione minima di KMDF	1.0
versione minima di UMDF	2.0
intestazione	wdfcollection.h (include Wdf.h)
libreria	Wdf01000.sys (KMDF); WUDFx02000.dll (UMDF)
IRQL	<= DISPATCH_LEVEL
regole di conformità DDI	DriverCreate(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf)

Vedere anche

WdfCollectionCreare

WdfCollectionRemove

WdfCollectionRemoveItem

Condividi tramite