WdfDriverCreate-Funktion (wdfdriver.h)

Artikel
02/29/2024

[Gilt für KMDF und UMDF]

Die WdfDriverCreate-Methode erstellt ein Frameworktreiberobjekt für den aufrufenden Treiber.

Syntax

NTSTATUS WdfDriverCreate(
  [in]            PDRIVER_OBJECT         DriverObject,
  [in]            PCUNICODE_STRING       RegistryPath,
  [in, optional]  PWDF_OBJECT_ATTRIBUTES DriverAttributes,
  [in]            PWDF_DRIVER_CONFIG     DriverConfig,
  [out, optional] WDFDRIVER              *Driver
);

Parameter

[in] DriverObject

Ein Zeiger auf eine DRIVER_OBJECT-Struktur , die ein WDM-Treiberobjekt (Windows Driver Model) darstellt. Der Treiber empfängt diesen Zeiger als Eingabe für seine DriverEntry-Routine .

[in] RegistryPath

Ein Zeiger auf eine UNICODE_STRING-Struktur , die die Registrierungspfadzeichenfolge enthält, die der Treiber als Eingabe für seine DriverEntry-Routine empfangen hat.

[in, optional] DriverAttributes

Ein Zeiger auf eine aufruferseitig zugeordnete WDF_OBJECT_ATTRIBUTES-Struktur . (Das ParentObject-Element der Struktur muss NULL sein.) Dieser Parameter ist optional und kann WDF_NO_OBJECT_ATTRIBUTES werden.

[in] DriverConfig

Ein Zeiger auf eine aufruferseitig zugeordnete WDF_DRIVER_CONFIG-Struktur .

[out, optional] Driver

Ein Zeiger auf einen Speicherort, der ein Handle für das neue Frameworktreiberobjekt empfängt. Dieser Parameter ist optional und kann WDF_NO_HANDLE werden.

Rückgabewert

WdfDriverCreate 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_DRIVER_INTERNAL_ERROR	Der Treiber mit dem Namen WdfDriverErstellen sie mehr als einmal.
STATUS_INVALID_PARAMETER	Ein nicht Plug & Play (PnP)-Treiber hat eine EvtDriverDeviceAdd-Rückruffunktion angegeben.

Weitere Informationen zu Rückgabewerten finden Sie unter Fehler beim Erstellen von Frameworkobjekten.

Diese Methode gibt möglicherweise auch andere NTSTATUS-Werte zurück.

Eine Systemfehlerüberprüfung tritt auf, wenn der DriverObject-, RegistryPath- oder DriverConfig-ParameterNULL ist.

Hinweise

Ein Treiber, der Kernel-Mode Driver Framework verwendet, muss WdfDriverCreate aus seiner DriverEntry-Routine aufrufen, bevor andere Frameworkroutinen aufgerufen werden. Weitere Informationen zu DriverEntry finden Sie unter DriverEntry für Framework-basierte Treiber.

Bevor Ihr Treiber WdfDriverCreate aufruft, muss der Treiber WDF_DRIVER_CONFIG_INIT aufrufen, um seine WDF_DRIVER_CONFIG-Struktur zu initialisieren.

Das Frameworktreiberobjekt ist der oberste Teil der Struktur des Treibers von Frameworkobjekten und verfügt daher nicht über ein übergeordnetes Objekt.

Wenn Ihr Treiber EvtCleanupCallback - oder EvtDestroyCallback-Rückruffunktionen für das Treiberobjekt bereitstellt, beachten Sie, dass das Framework diese Rückruffunktionen unter IRQL = PASSIVE_LEVEL aufruft.

Beispiele

Das folgende Codebeispiel ist eine DriverEntry-Routine , die eine WDF_DRIVER_CONFIG-Struktur initialisiert und dann ein Frameworktreiberobjekt erstellt.

NTSTATUS
DriverEntry(
    IN PDRIVER_OBJECT  DriverObject,
    IN PUNICODE_STRING  RegistryPath
    )
{
    WDF_DRIVER_CONFIG  config;
    NTSTATUS  status = STATUS_SUCCESS;

    WDF_DRIVER_CONFIG_INIT(
                           &config,
                           MyEvtDeviceAdd
                           );
    config.EvtDriverUnload = MyEvtDriverUnload;
    status = WdfDriverCreate(
                             DriverObject,
                             RegistryPath,
                             WDF_NO_OBJECT_ATTRIBUTES,
                              &config,
                             WDF_NO_HANDLE
                             );
    if (!NT_SUCCESS(status)) {
        TraceEvents(
                    TRACE_LEVEL_ERROR,
                    DBG_PNP,
                    "WdfDriverCreate failed with status %!STATUS!",
                    status
                    );
    }
    return status;
}

Anforderungen

Anforderung	Wert
Zielplattform	Universell
KMDF-Mindestversion	1.0
UMDF-Mindestversion	2.0
Kopfzeile	wdfdriver.h (einschließen von Wdf.h)
Bibliothek	Wdf01000.sys (KMDF); WUDFx02000.dll (UMDF)
IRQL	PASSIVE_LEVEL
DDI-Complianceregeln	ChangeQueueState(kmdf), DriverAttributeChanged(kmdf), DriverCreate(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf), MiniportOnlyWdmDevice(kmdf)