Funzione WdfCollectionAdd (wdfcollection.h)

Articolo
02/26/2024

[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 per un oggetto raccolta.

[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 potrebbe anche restituire altri valori NTSTATUS.

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

Commenti

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

Per altre informazioni sulle raccolte di oggetti, vedere Framework Object Collections.

Esempio

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

Requisiti

Requisito	Valore
Piattaforma di destinazione	Universale
Versione KMDF minima	1.0
Versione UMDF minima	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)

Vedi anche

WdfCollectionCreate

WdfCollectionRemove

WdfCollectionRemoveItem

Condividi tramite