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 vom Aufrufer zugewiesene 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 eine Position, die ein Handle auf das neue Framework-Geräteobjekt empfängt.

Rückgabewert

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

|Code zurückgeben|Beschreibung| |--- |--- | |STATUS_INVALID_PARAMETER|Es wird ein ungültiges Device- oder DeviceInit-Handle 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 angegeben.| |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 beim Erstellen 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 beim Aufrufen der Initialisierungsfunktionen Fehler beim Treiber auftreten, darf WdfDeviceCreate nicht aufgerufen werden. 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 Framework-Gerä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 von einem Aufruf von WdfPdoInitAllocate erhalten hat, erstellt WdfDeviceCreate eine PDO.

Miniporttreiber, 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 Frameworkgeräteobjekt (mit Ausnahme einiger Steuerelementgeräteobjekte), wenn der PnP-Manager (Plug & Play) 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

Weitere Informationen

WDFDEVICE_INIT

WDF_OBJECT_ATTRIBUTES

WDF_OBJECT_ATTRIBUTES_INIT_CONTEXT_TYPE

WDF_PNPPOWER_EVENT_CALLBACKS_INIT

WdfDeviceInitFree

WdfDeviceInitSetIoType

WdfDeviceInitSetPnpPowerEventCallbacks

WdfDeviceMiniportCreate