WdfDeviceCreate-Funktion (wdfdevice.h)

Artikel
08/08/2023

[Gilt für KMDF und UMDF]

Die WdfDeviceCreate-Methode erstellt ein Framework-Geräteobjekt.

Syntax

NTSTATUS WdfDeviceCreate(
  [in, out]      PWDFDEVICE_INIT        *DeviceInit,
  [in, optional] PWDF_OBJECT_ATTRIBUTES DeviceAttributes,
  [out]          WDFDEVICE              *Device
);

Parameter

[in, out] DeviceInit

Die Adresse eines Zeigers auf eine WDFDEVICE_INIT-Struktur . Wenn WdfDeviceCreate keine Fehler auftritt, wird der Zeiger auf NULL festgelegt.

[in, optional] DeviceAttributes

Ein Zeiger auf eine vom Aufrufer zugeordnete WDF_OBJECT_ATTRIBUTES-Struktur , die Attribute für das neue Objekt enthält. (Das ParentObject-Element der Struktur muss NULL sein.) Dieser Parameter ist optional und kann WDF_NO_OBJECT_ATTRIBUTES werden.

[out] Device

Ein Zeiger auf einen Speicherort, der ein Handle für das neue Frameworkgeräteobjekt empfängt.

Rückgabewert

Wenn bei der WdfDeviceCreate-Methode keine Fehler auftreten, wird STATUS_SUCCESS zurückgegeben. Weitere Rückgabewerte sind:

Rückgabecode	Beschreibung
STATUS_INVALID_PARAMETER	Ein ungültiges Device - oder DeviceInit-Handle wird bereitgestellt.
STATUS_INVALID_DEVICE_STATE	Der Treiber hat bereits ein Geräteobjekt für das Gerät erstellt.
STATUS_INVALID_SECURITY_DESCR	der Treiber mit dem Namen WdfDeviceInitAssignSDDLString oder WdfDeviceInitSetDeviceClass , aber keinen Namen für das Geräteobjekt bereitgestellt hat.
STATUS_INSUFFICIENT_RESOURCES	Ein Geräteobjekt konnte nicht zugeordnet werden.
STATUS_OBJECT_NAME_COLLISION	Der Gerätename, der durch einen Aufruf von WdfDeviceInitAssignName angegeben wurde, ist bereits vorhanden. Der Treiber kann WdfDeviceInitAssignName erneut aufrufen, um einen neuen Namen zuzuweisen.

Eine Liste mit anderen Rückgabewerten, die WdfDeviceCreate zurückgeben kann, finden Sie unter Fehler bei der Erstellung von Frameworkobjekten.

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

Hinweise

Vor dem Aufrufen von WdfDeviceCreate muss der Treiber vom Framework bereitgestellte Funktionen aufrufen, die die WDFDEVICE_INIT-Struktur initialisieren. Weitere Informationen zum Initialisieren dieser Struktur finden Sie unter WDFDEVICE_INIT. Wenn der Treiber beim Aufrufen der Initialisierungsfunktionen Fehler auftritt, darf er WdfDeviceCreate nicht aufrufen. In diesem Fall muss der Treiber möglicherweise WdfDeviceInitFree aufrufen. Informationen zum Aufrufen von WdfDeviceInitFree finden Sie unter WdfDeviceInitFree.

Ein Aufruf von WdfDeviceCreate erstellt ein Frameworkgeräteobjekt, das entweder ein funktionales Geräteobjekt (Functional Device Object, FDO) oder ein physisches Geräteobjekt (PDO) darstellt. Der Typ des Geräteobjekts, das die Funktion erstellt, hängt davon ab, wie der Treiber die WDFDEVICE_INIT-Struktur abgerufen hat:

Wenn der Treiber die WDFDEVICE_INIT-Struktur von einem EvtDriverDeviceAdd-Rückruf empfangen hat, erstellt WdfDeviceCreate eine FDO.
Wenn der Treiber die WDFDEVICE_INIT-Struktur von einem EvtChildListCreateDevice-Rückruf oder einem Aufruf von WdfPdoInitAllocate empfangen hat, erstellt WdfDeviceCreate ein PDO.

Nachdem der Treiber WdfDeviceCreate aufgerufen hat, kann er nicht mehr auf die WDFDEVICE_INIT-Struktur zugreifen.

Miniport-Treiber, die das Framework verwenden, müssen WdfDeviceMiniportCreate anstelle von WdfDeviceCreate aufrufen.

Das übergeordnete Element jedes Framework-Geräteobjekts ist das Frameworktreiberobjekt des Treibers. Der Treiber kann dieses übergeordnete Element nicht ändern, und das ParentObject-Element der WDF_OBJECT_ATTRIBUTES-Struktur muss NULL sein. Das Framework löscht jedes Framework-Geräteobjekt (mit Ausnahme einiger Steuerelementgeräteobjekte), wenn der Plug & Play-Manager (PnP) feststellt, dass das Gerät entfernt wurde.

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

Weitere Informationen zum Erstellen von Geräteobjekten finden Sie unter Erstellen eines Framework-Geräteobjekts.

Beispiele

Das folgende Codebeispiel zeigt, wie eine EvtDriverDeviceAdd-Rückruffunktion ein Geräteobjekt initialisieren und erstellen kann.

NTSTATUS
MyEvtDeviceAdd(
    IN WDFDRIVER  Driver,
    IN PWDFDEVICE_INIT  DeviceInit
    )
{
    WDF_PNPPOWER_EVENT_CALLBACKS  pnpPowerCallbacks;
    WDF_OBJECT_ATTRIBUTES  attributes;
    NTSTATUS  status;
    WDFDEVICE  device;
 
    //
    // Initialize the WDF_PNPPOWER_EVENT_CALLBACKS structure.
    //
    WDF_PNPPOWER_EVENT_CALLBACKS_INIT(&pnpPowerCallbacks);
    pnpPowerCallbacks.EvtDevicePrepareHardware = MyEvtDevicePrepareHardware;
    pnpPowerCallbacks.EvtDeviceD0Entry = MyEvtDeviceD0Entry;
    pnpPowerCallbacks.EvtDeviceD0Exit  = MyEvtDeviceD0Exit;
    WdfDeviceInitSetPnpPowerEventCallbacks(
                                           DeviceInit,
                                           &pnpPowerCallbacks
                                           );
    //
    // This driver uses buffered I/O.
    //
    WdfDeviceInitSetIoType(
                           DeviceInit,
                           WdfDeviceIoBuffered
                           );
 
    //
    // Specify the device object's context space by
    // using a driver-defined DEVICE_CONTEXT structure.
 //
    WDF_OBJECT_ATTRIBUTES_INIT_CONTEXT_TYPE(
                                            &attributes,
                                            DEVICE_CONTEXT
                                            );
 //
    // Create the device object.
    //
    status = WdfDeviceCreate(
                             &DeviceInit,
                             &attributes,
                             &device
                             );
    if (!NT_SUCCESS(status)) {
        return status;
    }
    return STATUS_SUCCESS;
}

Anforderungen

Anforderung	Wert
Zielplattform	Universell
KMDF-Mindestversion	1.0
UMDF-Mindestversion	2.0
Kopfzeile	wdfdevice.h (einschließen von Wdf.h)
Bibliothek	Wdf01000.sys (KMDF); WUDFx02000.dll (UMDF)
IRQL	PASSIVE_LEVEL
DDI-Complianceregeln	AccessHardwareKey(kmdf), AddPdoToStaticChildList(kmdf), ChangeQueueState(kmdf), ChildDeviceInitAPI(kmdf), ChildListConfiguration(kmdf), ControlDeviceDeleted(kmdf), ControlDeviceInitAllocate(kmdf), ControlDeviceInitAPI(kmdf), CtlDeviceFinishInitDeviceAdd(kmdf), CtlDeviceFinishInitDrEntry(kmdf), DeviceCreateFail(kmdf), DeviceInitAllocate(kmdf), DeviceInitAPI(kmdf), DriverCreate(kmdf), InitFreeDeviceCreate(kmdf), InitFreeDeviceCreateType2(kmdf), InitFreeDeviceCreateType4(kmdf), InitFreeNull(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf), PdoDeviceInitAPI(kmdf), PdoInitFreeDeviceCreate(kmdf), PdoInitFreeDeviceCreateType2(kmdf), PdoInitFreeDeviceCreateType4(kmdf)