Metodo IWDFDriver::CreateDevice (wudfddi.h)

Articolo
08/08/2023

[Avviso: UMDF 2 è la versione più recente di UMDF e sostituisce UMDF 1. Tutti i nuovi driver UMDF devono essere scritti usando UMDF 2. Non vengono aggiunte nuove funzionalità a UMDF 1 ed è disponibile un supporto limitato per UMDF 1 nelle versioni più recenti di Windows 10. I driver di Windows universali devono usare UMDF 2. Per altre info, vedi Introduzione con UMDF.]

Il metodo CreateDevice configura e crea un nuovo oggetto dispositivo framework.

Sintassi

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

Parametri

[in] pDeviceInit

Puntatore all'interfaccia IWDFDeviceInitialize che rappresenta le proprietà di configurazione per il nuovo dispositivo da creare.

[in, optional] pCallbackInterface

Puntatore all'interfaccia IUnknown usata dal framework per ottenere le interfacce fornite dal driver per il nuovo oggetto dispositivo. Queste interfacce forniscono le funzioni di callback chiamate dal framework quando si verificano eventi pertinenti. Per ulteriori informazioni, vedere la sezione Osservazioni successiva.

[out] ppDevice

Puntatore a un buffer che riceve un puntatore all'interfaccia IWDFDevice per il nuovo oggetto dispositivo.

Valore restituito

CreateDevice restituisce S_OK se l'operazione ha esito positivo. In caso contrario, questo metodo restituisce uno dei codici di errore definiti in Winerror.h.

Commenti

L'interfaccia IUnknown fornita dal driver per il parametro pCallbackInterface può supportare diverse interfacce. Il framework chiama il metodo QueryInterface dell'interfaccia IUnknown fornita più volte per recuperare le interfacce supportate dal driver. Il metodo QueryInterface del driver può restituire le interfacce seguenti:

IPnpCallbackHardware2

IPnpCallbackHardwareInterrupt

IPnpCallbackSelfManagedIo

IPnpCallbackHardwareInterrupt

IPnpCallbackSelfManagedIo

IPowerPolicyCallbackWakeFromS0

IPowerPolicyCallbackWakeFromSx

Quando lo stato del dispositivo cambia, il framework chiama il metodo correlato alla modifica (ad esempio il metodo IPnpCallback::OnD0Entry ) per notificare al driver.

Se la chiamata a CreateDevice ha esito positivo, il driver deve infine chiamare il metodo IWDFDevice::Release . Si noti che il framework ha un proprio conteggio dei riferimenti sull'oggetto .

Per altre informazioni, vedere Aggiunta di un dispositivo.

Esempio

L'esempio di codice seguente mostra un'implementazione del metodo OnDeviceAdd dell'interfaccia IDriverEntry . Il framework chiama OnDeviceAdd quando un dispositivo viene aggiunto a un computer.

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;
}

Requisiti

Requisito	Valore
Fine del supporto	Non disponibile in UMDF 2.0 e versioni successive.
Piattaforma di destinazione	Desktop
Versione UMDF minima	1.5
Intestazione	wudfddi.h (include Wudfddi.h)
DLL	WUDFx.dll