IWDFDriver::CreateDevice-Methode (wudfddi.h)

Artikel
03/01/2024

[Warnung: UMDF 2 ist die neueste Version von UMDF und ersetzt UMDF 1. Alle neuen UMDF-Treiber sollten mit UMDF 2 geschrieben werden. UMDF 1 werden keine neuen Features hinzugefügt, und die Unterstützung für UMDF 1 in neueren Versionen von Windows 10 ist eingeschränkt. 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 neu zu erstellende Gerät darstellt.

[in, optional] pCallbackInterface

Ein Zeiger auf die IUnknown-Schnittstelle , die das Framework verwendet, um die Schnittstellen abzurufen, 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.

Hinweise

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 Schnittstellen abzurufen, die der Treiber unterstützt. Die QueryInterface-Methode des Treibers kann die folgenden Schnittstellen zurückgeben:

IPnpCallbackHardware2

IPnpCallbackHardwareInterrupt

IPnpCallbackSelfManagedIo

IPnpCallbackHardwareInterrupt

IPnpCallbackSelfManagedIo

IPowerPolicyCallbackWakeFromS0

IPowerPolicyCallbackWakeFromSx

Wenn das Gerät den Zustand ä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äts.

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
UMDF-Mindestversion	1.5
Kopfzeile	wudfddi.h (include Wudfddi.h)
DLL	WUDFx.dll