Método IWDFDriver::CreateDevice (wudfddi.h)

Artículo
08/08/2023

[Advertencia: UMDF 2 es la versión más reciente de UMDF y sustituye a UMDF 1. Todos los controladores UMDF nuevos deben escribirse con UMDF 2. No se agregan nuevas características a UMDF 1 y hay compatibilidad limitada con UMDF 1 en versiones más recientes de Windows 10. Los controladores universales de Windows deben usar UMDF 2. Para obtener más información, consulta Introducción con UMDF.

El método CreateDevice configura y crea un nuevo objeto de dispositivo de marco.

Sintaxis

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

Parámetros

[in] pDeviceInit

Puntero a la interfaz IWDFDeviceInitialize que representa las propiedades de configuración del nuevo dispositivo que se va a crear.

[in, optional] pCallbackInterface

Puntero a la interfaz IUnknown que usa el marco para obtener las interfaces que proporciona el controlador para el nuevo objeto de dispositivo. Estas interfaces proporcionan las funciones de devolución de llamada a las que llama el marco cuando se producen eventos pertinentes. Para obtener más información, vea la sección Comentarios que se muestra más adelante.

[out] ppDevice

Puntero a un búfer que recibe un puntero a la interfaz IWDFDevice del nuevo objeto de dispositivo.

Valor devuelto

CreateDevice devuelve S_OK si la operación se realiza correctamente. De lo contrario, este método devuelve uno de los códigos de error definidos en Winerror.h.

Comentarios

La interfaz IUnknown que el controlador proporciona para el parámetro pCallbackInterface puede admitir varias interfaces. El marco llama al método QueryInterface de la interfaz IUnknown proporcionada varias veces para recuperar las interfaces que admite el controlador. El método QueryInterface del controlador puede devolver las interfaces siguientes:

IPnpCallbackHardware2

IPnpCallbackHardwareInterrupt

IPnpCallbackSelfManagedIo

IPnpCallbackHardwareInterrupt

IPnpCallbackSelfManagedIo

IPowerPolicyCallbackWakeFromS0

IPowerPolicyCallbackWakeFromSx

Cuando el dispositivo cambia de estado, el marco llama al método relacionado con el cambio (como el método IPnpCallback::OnD0Entry ) para notificar al controlador.

Si la llamada a CreateDevice se realiza correctamente, el controlador debe llamar finalmente al método IWDFDevice::Release . Tenga en cuenta que el marco de trabajo tiene su propio recuento de referencias en el objeto .

Para obtener más información, vea Agregar un dispositivo.

Ejemplos

En el ejemplo de código siguiente se muestra una implementación del método OnDeviceAdd de la interfaz IDriverEntry . El marco llama a OnDeviceAdd cuando se agrega un dispositivo a un equipo.

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

Requisitos

Requisito	Value
Finalización del soporte técnico	No disponible en UMDF 2.0 y versiones posteriores.
Plataforma de destino	Escritorio
Versión mínima de UMDF	1.5
Encabezado	wudfddi.h (incluya Wudfddi.h)
Archivo DLL	WUDFx.dll