WdfDeviceCreate-Funktion (wdfdevice.h)

[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 aufweist, wird der Zeiger auf NULL festgelegt.

[in, optional] DeviceAttributes

Ein Zeiger auf eine aufgerufene 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 sein.

[out] Device

Ein Zeiger auf einen Speicherort, der ein Handle zum neuen Framework-Gerätobjekt empfängt.

Rückgabewert

Wenn die WdfDeviceCreate-Methode keine Fehler aufweist, wird STATUS_SUCCESS zurückgegeben. Weitere Rückgabewerte umfassen:

Rückgabecode Beschreibung
STATUS_INVALID_PARAMETER
Ein ungültiger 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 hat jedoch keinen Namen für das Geräteobjekt bereitgestellt.
STATUS_INSUFFICIENT_RESOURCES
Ein Geräteobjekt konnte nicht zugewiesen 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 anderer Rückgabewerte, die WdfDeviceCreate zurückgeben kann, finden Sie unter Framework-Objekterstellungsfehler.

Die Methode kann andere NTSTATUS-Werte zurückgeben.

Bemerkungen

Bevor Sie WdfDeviceCreate aufrufen, muss der Treiber Framework-bereitgestellte Funktionen aufrufen, die die WDFDEVICE_INIT-Struktur initialisieren. Weitere Informationen zum Initialisieren dieser Struktur finden Sie unter WDFDEVICE_INIT. Wenn der Treiber fehler beim Aufrufen der Initialisierungsfunktionen auftritt, darf es nicht WdfDeviceCreate 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ätobjekt, das entweder ein funktionales Geräteobjekt (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:

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 (außer für einige Steuerelementgeräteobjekte), wenn der technologie Plug and Play (PnP)-Manager bestimmt, 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 bei IRQL = PASSIVE_LEVEL aufruft.

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

Beispiele

Im folgenden Codebeispiel wird gezeigt, wie eine EvtDriverDeviceAdd-Rückruffunktion möglicherweise initialisiert und ein Geräteobjekt erstellt.

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

   
Zielplattform Universell
KMDF-Mindestversion 1.0
UMDF-Mindestversion 2.0
Header wdfdevice.h (enthalten 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), CtlDeviceFinishInitInitDeviceAdd(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)

Siehe auch

WDFDEVICE_INIT

WDF_OBJECT_ATTRIBUTES

WDF_OBJECT_ATTRIBUTES_INIT_CONTEXT_TYPE

WDF_PNPPOWER_EVENT_CALLBACKS_INIT

WdfDeviceInitFree

WdfDeviceInitSetIoType

WdfDeviceInitSetPnpPowerEventCallbacks

WdfDeviceMiniportCreate