Funzione WdfDpcCreate (wdfdpc.h)

Articolo
02/29/2024

[Si applica solo a KMDF]

Il metodo WdfDpcCreate crea un oggetto DPC framework e registra una funzione di callback EvtDpcFunc .

Sintassi

NTSTATUS WdfDpcCreate(
  [in]  PWDF_DPC_CONFIG        Config,
  [in]  PWDF_OBJECT_ATTRIBUTES Attributes,
  [out] WDFDPC                 *Dpc
);

Parametri

[in] Config

Puntatore a una struttura WDF_DPC_CONFIG allocata dal chiamante.

[in] Attributes

Puntatore a una struttura di WDF_OBJECT_ATTRIBUTES allocata dal chiamante che specifica gli attributi per il nuovo oggetto DPC.

[out] Dpc

Puntatore a una posizione che riceve un handle per il nuovo oggetto DPC del framework.

Valore restituito

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

Codice restituito	Descrizione
STATUS_INVALID_PARAMETER	È stato specificato un parametro non valido.
STATUS_INSUFFICIENT_RESOURCES	Impossibile allocare un oggetto DPC.
STATUS_WDF_PARENT_NOT_SPECIFIED	Un oggetto padre non è stato specificato nella struttura WDF_OBJECT_ATTRIBUTES .
STATUS_INVALID_DEVICE_REQUEST	Il membro ParentObject della struttura WDF_OBJECT_ATTRIBUTES non fa riferimento a un oggetto dispositivo framework o a un oggetto la cui catena di genitori porta a un oggetto dispositivo framework.
STATUS_WDF_INCOMPATIBLE_EXECUTION_LEVEL	Il membro AutomaticSerialization della struttura WDF_DPC_CONFIG è impostato su TRUE, ma il livello di esecuzione dell'oggetto padre è impostato su WdfExecutionLevelPassive.

Per un elenco di altri valori restituiti che il metodo WdfDpcCreate potrebbe restituire, vedere Errori di creazione dell'oggetto Framework.

Questo metodo potrebbe restituire anche altri valori NTSTATUS.

Commenti

Un driver chiama in genere WdfDpcCreate dall'interno della sua funzione evtDriverDeviceAdd callback.

Quando un driver crea un oggetto DPC, deve specificare un oggetto padre nel membro ParentObject della struttura WDF_OBJECT_ATTRIBUTES . L'oggetto padre può essere un oggetto dispositivo framework o qualsiasi oggetto la cui catena di genitori porta a un oggetto dispositivo framework. Il framework eliminerà l'oggetto DPC quando elimina l'oggetto device.

La chiamata a WdfDpcCreate crea un oggetto DPC framework e registra una funzione di callback EvtDpcFunc . Per pianificare l'esecuzione della funzione callback, il driver deve chiamare WdfDpcEnqueue.

Se il driver fornisce funzioni di callback EvtCleanupCallback o EvtDestroyCallback per l'oggetto timer del framework, si noti che il framework chiama queste funzioni di callback in IRQL = PASSIVE_LEVEL.

Per altre informazioni sull'uso di oggetti DPC, vedere Manutenzione di un interruzione.

Esempio

Nell'esempio di codice seguente viene inizializzata una struttura WDF_DPC_CONFIG_INIT e quindi viene creato un oggetto DPC.

WDF_DPC_CONFIG dpcConfig;
WDF_OBJECT_ATTRIBUTES dpcAttributes;
NTSTATUS status;

WDF_DPC_CONFIG_INIT(
                    &dpcConfig,
                    MyEvtDpcFunc
                    );
dpcConfig.AutomaticSerialization = TRUE;
WDF_OBJECT_ATTRIBUTES_INIT(&dpcAttributes);
dpcAttributes.ParentObject = pDevExt->WdfDevice;
status = WdfDpcCreate(
                      &dpcConfig,
                      &dpcAttributes,
                      &pDevExt->CompleteWriteDpc
                      );
if (!NT_SUCCESS(status)) {
    return status;
}

Requisiti

Requisito	Valore
Piattaforma di destinazione	Universale
Versione KMDF minima	1.0
Intestazione	wdfdpc.h (includere Wdf.h)
Libreria	Wdf01000.sys (vedere Framework Library Versioning).
IRQL	<=DISPATCH_LEVEL
Regole di conformità DDI	DriverCreate(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf)