Auf Englisch lesen

Freigeben über


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 auftritt, 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 für das neue Framework-Geräteobjekt empfängt.

Rückgabewert

Wenn die WdfDeviceCreate Methode keine Fehler auftritt, wird STATUS_SUCCESS zurückgegeben. Weitere Rückgabewerte sind:

Rückgabecode Beschreibung
STATUS_INVALID_PARAMETER Es wird ein ungültiger 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 WdfDeviceInitAssignSDDLString oder WdfDeviceInitSetDeviceClass, aber keinen Namen für das Geräteobjekt bereitgestellt hat.
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 mit anderen Rückgabewerten, die WdfDeviceCreate zurückgeben können, finden Sie unter Framework Object Creation Errors.

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

Bemerkungen

Vor dem Aufrufen WdfDeviceCreatemuss 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 fehler beim Aufrufen der Initialisierungsfunktionen auftritt, darf er nicht WdfDeviceCreateaufrufen. In diesem Fall muss der Treiber möglicherweise WdfDeviceInitFree-aufrufen. Informationen zum Aufrufen WdfDeviceInitFree-finden Sie unter WdfDeviceInitFree.

Ein Aufruf von WdfDeviceCreate erstellt ein Framework-Geräteobjekt, das entweder ein funktionales Geräteobjekt (FDO) oder ein physisches Geräteobjekt (PDO) darstellt. Der Typ des von der Funktion erstellten Geräteobjekts 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 einen FDO.
  • Wenn der Treiber die WDFDEVICE_INIT Struktur von einem EvtChildListCreateDevice Callback oder von einem Aufruf an WdfPdoInitAllocateerhalten hat, erstellt WdfDeviceCreate einen PDO.
Nachdem der Treiber WdfDeviceCreateaufgerufen hat, kann er nicht mehr auf die WDFDEVICE_INIT-Struktur zugreifen.

Miniporttreiber, die das Framework verwenden, müssen WdfDeviceMiniportCreate anstelle von WdfDeviceCreateaufrufen.

Das übergeordnete Element jedes Framework-Geräteobjekts ist das Framework-Treiberobjekt des Treibers. Der Treiber kann dieses übergeordnete Element nicht ändern, und das ParentObject Member der WDF_OBJECT_ATTRIBUTES Struktur muss NULL-sein. Das Framework löscht jedes Framework-Geräteobjekt (mit Ausnahme einiger Steuerelementgeräteobjekte), wenn der Plug and Play (PnP)-Manager 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 bei IRQL = PASSIVE_LEVEL aufruft.

Weitere Informationen zum Erstellen von Geräteobjekten finden Sie unter Creating a Framework Device Object.

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

Siehe auch

WDFDEVICE_INIT

WDF_OBJECT_ATTRIBUTES

WDF_OBJECT_ATTRIBUTES_INIT_CONTEXT_TYPE

WDF_PNPPOWER_EVENT_CALLBACKS_INIT

WdfDeviceInitFree

WdfDeviceInitSetIoType

WdfDeviceInitSetPnpPowerEventCallbacks

WdfDeviceMiniportCreate