Método IDriverEntry::OnDeviceAdd (wudfddi.h)

Artigo
02/27/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. Drivers universais do Windows devem usar UMDF 2. Para obter mais informações, consulte Introdução com UMDF.]

O método OnDeviceAdd adiciona um novo dispositivo a um sistema.

Sintaxe

HRESULT OnDeviceAdd(
  [in] IWDFDriver           *pWdfDriver,
  [in] IWDFDeviceInitialize *pWdfDeviceInit
);

Parâmetros

[in] pWdfDriver

Um ponteiro para a interface IWDFDriver para o objeto de driver pai ao qual o novo dispositivo pertence.

[in] pWdfDeviceInit

Um ponteiro para a interface IWDFDeviceInitialize que o driver usa para inicializar o dispositivo recém-criado.

Retornar valor

OnDeviceAdd 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. O driver deverá retornar S_OK somente se tiver chamado com êxito o método IWDFDriver::CreateDevice para criar o objeto de dispositivo de estrutura. Se o driver retornar um código de erro, o UMDF desativará toda a pilha do dispositivo, independentemente de o driver ser um driver de filtro ou um driver de função.

Comentários

Um novo objeto de dispositivo é criado para cada dispositivo carregado no processo de host do driver. Quando um novo dispositivo chega ao sistema, a estrutura chama OnDeviceAdd para notificar o driver da chegada e passa as interfaces IWDFDriver e IWDFDeviceInitialize na chamada. O driver pode chamar o método IWDFDeviceInitialize::RetrieveDevicePropertyStore para consultar as informações do dispositivo fornecidas como parte da instalação do dispositivo. O driver deve chamar o método IWDFDriver::CreateDevice para configurar e criar o dispositivo. Se o driver não chamar IWDFDriver::CreateDevice com êxito antes de retornar S_OK, o UMDF determinará que o comportamento do driver está incorreto e encerrará o processo de host.

Qualquer driver cujo método OnDeviceAdd retorna S_OK receberá posteriormente uma chamada para o método IPnpCallbackHardware::OnReleaseHardware quando o UMDF derrubar a pilha do dispositivo.

Não use a interface IWDFDeviceInitialize para a qual o parâmetro pWdfDeviceInit aponta depois que o driver chamar IWDFDriver::CreateDevice.

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