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

Artigo
03/01/2024

[Aviso: UMDF 2 é a versão mais recente do UMDF e substitui UMDF 1. Todos os novos drivers UMDF devem ser gravados usando UMDF 2. Nenhum novo recurso está sendo adicionado ao UMDF 1 e há suporte limitado para UMDF 1 em versões mais recentes do Windows 10. Os drivers universais do Windows devem usar o UMDF 2. Para obter mais informações, consulte Introdução com UMDF.]

O método CreateDevice configura e cria um novo objeto de dispositivo de estrutura.

Sintaxe

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

Parâmetros

[in] pDeviceInit

Um ponteiro para a interface IWDFDeviceInitialize que representa as propriedades de configuração do novo dispositivo a ser criado.

[in, optional] pCallbackInterface

Um ponteiro para a interface IUnknown que a estrutura usa para obter as interfaces que o driver fornece para o novo objeto de dispositivo. Essas interfaces fornecem as funções de retorno de chamada que a estrutura chama quando ocorrem eventos relevantes. Para obter mais informações, consulte a seção Comentários a seguir.

[out] ppDevice

Um ponteiro para um buffer que recebe um ponteiro para a interface IWDFDevice para o novo objeto de dispositivo.

Retornar valor

CreateDevice retornará S_OK se a operação for bem-sucedida. Caso contrário, esse método retornará um dos códigos de erro definidos em Winerror.h.

Comentários

A interface IUnknown que o driver fornece para o parâmetro pCallbackInterface pode dar suporte a várias interfaces. A estrutura chama o método QueryInterface da interface IUnknown fornecida várias vezes para recuperar as interfaces compatíveis com o driver. O método QueryInterface do driver pode retornar as seguintes interfaces:

IPnpCallbackHardware2

IPnpCallbackHardwareInterrupt

IPnpCallbackSelfManagedIo

IPnpCallbackHardwareInterrupt

IPnpCallbackSelfManagedIo

IPowerPolicyCallbackWakeFromS0

IPowerPolicyCallbackWakeFromSx

Quando o dispositivo altera o estado, a estrutura chama o método relacionado à alteração (como o método IPnpCallback::OnD0Entry ) para notificar o driver.

Se a chamada para CreateDevice for bem-sucedida, o driver deverá eventualmente chamar o método IWDFDevice::Release . Observe que a estrutura tem sua própria contagem de referência no objeto .

Para obter mais informações, consulte Adicionando um dispositivo.

Exemplos

O exemplo de código a seguir mostra uma implementação do método OnDeviceAdd da interface IDriverEntry . A estrutura chama OnDeviceAdd quando um dispositivo é adicionado a um computador.

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	Valor
Fim do suporte	Indisponível no UMDF 2.0 e posterior.
Plataforma de Destino	Área de Trabalho
Versão mínima do UMDF	1.5
Cabeçalho	wudfddi.h (inclua Wudfddi.h)
DLL	WUDFx.dll