IWDFDriver::CreateDevice-Methode (wudfddi.h)

2025-02-07

[Warnung: UMDF 2 ist die neueste Version von UMDF und ersetzt UMDF 1. Alle neuen UMDF-Treiber sollten mit UMDF 2 geschrieben werden. Es werden keine neuen Features zu UMDF 1 hinzugefügt, und es gibt eingeschränkte Unterstützung für UMDF 1 für neuere Versionen von Windows 10. Universelle Windows-Treiber müssen UMDF 2 verwenden. Weitere Informationen finden Sie unter Erste Schritte mit UMDF-.]

Die CreateDevice Methode konfiguriert und erstellt ein neues Framework-Geräteobjekt.

Syntax

HRESULT CreateDevice(
  [in]           IWDFDeviceInitialize *pDeviceInit,
  [in, optional] IUnknown             *pCallbackInterface,
  [out]          IWDFDevice           **ppDevice
);

Parameter

[in] pDeviceInit

Ein Zeiger auf die IWDFDeviceInitialize Schnittstelle, die die Konfigurationseigenschaften für das zu erstellende neue Gerät darstellt.

[in, optional] pCallbackInterface

Ein Zeiger auf die IUnknown Schnittstelle, die vom Framework zum Abrufen der Schnittstellen verwendet wird, die der Treiber für das neue Geräteobjekt bereitstellt. Diese Schnittstellen stellen die Rückruffunktionen bereit, die das Framework aufruft, wenn relevante Ereignisse auftreten. Weitere Informationen finden Sie im folgenden Abschnitt "Hinweise".

[out] ppDevice

Ein Zeiger auf einen Puffer, der einen Zeiger auf die IWDFDevice Schnittstelle für das neue Geräteobjekt empfängt.

Rückgabewert

CreateDevice gibt S_OK zurück, wenn der Vorgang erfolgreich ist. Andernfalls gibt diese Methode einen der Fehlercodes zurück, die in Winerror.h definiert sind.

Bemerkungen

Die IUnknown Schnittstelle, die der Treiber für den pCallbackInterface Parameter bereitstellt, kann mehrere Schnittstellen unterstützen. Das Framework ruft die QueryInterface Methode der bereitgestellten IUnknown Schnittstelle mehrmals auf, um die vom Treiber unterstützten Schnittstellen abzurufen. Die QueryInterface- Methode des Treibers kann die folgenden Schnittstellen zurückgeben:

IPnpCallbackHardware2

IPnpCallbackHardwareInterrupt

IPnpCallbackSelfManagedIo

IPnpCallbackHardwareInterrupt

IPnpCallbackSelfManagedIo

IPowerPolicyCallbackWakeFromS0

IPowerPolicyCallbackWakeFromSx-

Wenn sich der Zustand des Geräts ändert, ruft das Framework die Methode auf, die sich auf die Änderung bezieht (z. B. die IPnpCallback::OnD0Entry-Methode), um den Treiber zu benachrichtigen.

Wenn der Aufruf von CreateDevice erfolgreich ist, muss der Treiber schließlich die IWDFDevice::Release-Methode aufrufen. Beachten Sie, dass das Framework über eine eigene Verweisanzahl für das Objekt verfügt.

Weitere Informationen finden Sie unter Hinzufügen eines Geräte-.

Beispiele

Das folgende Codebeispiel zeigt eine Implementierung der OnDeviceAdd--Methode der IDriverEntry--Schnittstelle. Das Framework ruft OnDeviceAdd auf, wenn einem Computer ein Gerät hinzugefügt wird.

HRESULT 
CDriver::OnDeviceAdd(
 IWDFDriver* pDriver,
 IWDFDeviceInitialize* pDeviceInit
    )
{
 IUnknown   *pDeviceCallback = NULL;
 IWDFDevice *pIWDFDevice     = NULL;
 IUnknown   *pIUnkQueue      = NULL;    

    //
    // Create the device callback object.
    //
    HRESULT hr = CDevice::CreateInstance(&pDeviceCallback);

    //
    // Set device properties
    //
    if (S_OK == hr) {
        pDeviceInit->SetLockingConstraint(WdfDeviceLevel);
        // To register as the power-policy owner for 
        // the device stack, call the following:
        // pDeviceInit->SetPowerPolicyOwnership(TRUE);

        // For a filter driver, call the following:
        // pDeviceInit->SetFilter();
    }

    //
    // Request that the framework create a device object.
    // The device callback object is passed to inform the 
    // framework about the PnP callback functions the driver supports.
    //
    if (S_OK == hr) {
        hr = pDriver->CreateDevice(pDeviceInit, 
                                   pDeviceCallback,
                                   &pIWDFDevice);
    }

    //
    // Create the queue callback object.
    //

    if (S_OK == hr) {
        hr = CQueue::CreateInstance(&pIUnkQueue);
    }

    //
    // Configure the default queue. 
    // The queue callback object is passed to inform the 
    // framework about the queue callback functions the driver supports.
    //
    if (S_OK == hr) {
        IWDFIoQueue * pDefaultQueue = NULL;
        hr = pIWDFDevice->CreateIoQueue(
                       pIUnkQueue,
                       TRUE,                  // bDefaultQueue
                       WdfIoQueueDispatchParallel,
                       TRUE,                  // bPowerManaged
                       FALSE, //bAllowZeroLengthRequests
                       &pDefaultQueue);
        SAFE_RELEASE(pDefaultQueue);
    }

    SAFE_RELEASE(pDeviceCallback);
    SAFE_RELEASE(pIWDFDevice);
    SAFE_RELEASE(pIUnkQueue);    

    return hr;
}

Anforderungen

Anforderung	Wert
Ende des Supports	In UMDF 2.0 und höher nicht verfügbar.
Zielplattform-	Desktop
Mindest-UMDF-Version	1.5
Header-	wudfddi.h (include Wudfddi.h)
DLL-	WUDFx.dll