Função DiInstallDevice (newdev.h)
A função DiInstallDevice instala um driver especificado que é pré-instalado no repositório de driver em um dispositivo especificado que está presente no sistema.
Sintaxe
BOOL DiInstallDevice(
[in, optional] HWND hwndParent,
[in] HDEVINFO DeviceInfoSet,
[in] PSP_DEVINFO_DATA DeviceInfoData,
[in, optional] PSP_DRVINFO_DATA DriverInfoData,
[in] DWORD Flags,
[out, optional] PBOOL NeedReboot
);
Parâmetros
[in, optional] hwndParent
Um identificador para a janela de nível superior que DiInstallDevice usa para exibir qualquer componente de interface do usuário associado à instalação do dispositivo. Esse parâmetro é opcional e pode ser definido como NULL.
[in] DeviceInfoSet
Um identificador para um conjunto de informações do dispositivo que contém um elemento de informações do dispositivo que representa o dispositivo especificado.
[in] DeviceInfoData
Um ponteiro para uma estrutura SP_DEVINFO_DATA que representa o dispositivo especificado no conjunto de informações do dispositivo especificado.
[in, optional] DriverInfoData
Um ponteiro para uma estrutura SP_DRVINFO_DATA que especifica o driver a ser instalado no dispositivo especificado. Esse parâmetro é opcional e pode ser definido como NULL. Se esse parâmetro for NULL, DiInstallDevice pesquisará os drivers pré-instalados no repositório de driver para o driver que é a melhor correspondência com o dispositivo especificado e, se for encontrado, instalará o driver no dispositivo especificado.
[in] Flags
Um valor do tipo DWORD que especifica zero ou o seguinte sinalizador:
DIIDFLAG_SHOWSEARCHUI
Se o chamador não especificar um driver (DriverInfoData está definido como NULL) e DiInstallDevice não localizará um driver pré-instalado que corresponda ao dispositivo especificado. Em vez disso, DiInstallDevice exibe o assistente de Novo Hardware Encontrado para o dispositivo.
DIIDFLAG_NOFINISHINSTALLUI
DiInstallDevice não inicia as páginas do assistente de instalação final nem as ações de conclusão da instalação. O chamador de DiInstallDevice deve iniciar essas operações. O chamador só deve especificar esse sinalizador se o chamador exigir que as páginas do assistente de instalação final sejam invocadas no contexto de um componente de interface do usuário fornecido pelo chamador.
DIIDFLAG_INSTALLNULLDRIVER
DiInstallDevice tenta instalar um driver nulo no dispositivo especificado. Se esse sinalizador estiver definido, DiInstallDevice não usará o parâmetro DriverInfoData . DiInstallDevice remove todas as configurações do dispositivo e, se o dispositivo não puder ser executado no modo bruto, a função definirá o status do dispositivo como CM_PROB_FAILED_INSTALL. Se DiInstallDevice não puder instalar um driver nulo, o estado resultante do dispositivo será o mesmo que se o dispositivo estivesse conectado pela primeira vez ao computador e o Windows não localizasse um driver para o dispositivo.
DIIDFLAG_INSTALLCOPYINFDRIVERS
Qualquer arquivo INF adicional especificado por meio de uma diretiva CopyINF será instalado em qualquer dispositivo ao qual seja aplicável. Qualquer falha na instalação de um INF adicional não fará com que a instalação do INF primário falhe.
[out, optional] NeedReboot
Um ponteiro para um valor do tipo BOOL que DiInstallDevice define para indicar se uma reinicialização do sistema é necessária para concluir a instalação. Esse parâmetro é opcional e pode ser definido como NULL. Se esse parâmetro for fornecido e uma reinicialização do sistema for necessária para concluir a instalação, DiInstallDevice definirá o valor como TRUE. Nesse caso, o chamador é responsável por reiniciar o sistema. Se esse parâmetro for fornecido e uma reinicialização do sistema não for necessária, DiInstallDevice definirá esse parâmetro como FALSE. Se esse parâmetro for NULL e uma reinicialização do sistema for necessária para concluir a instalação, DiInstallDevice exibirá uma caixa de diálogo de reinicialização do sistema.
Retornar valor
DiInstallDevice retornará TRUE se a função tiver instalado com êxito o driver especificado no dispositivo especificado. Caso contrário, DiInstallDevice retornará FALSE e o erro registrado poderá ser recuperado fazendo uma chamada para GetLastError. Alguns dos valores de erro mais comuns que GetLastError pode retornar são os seguintes:
| Código de retorno | Descrição |
|---|---|
|
O chamador não tem privilégios de Administrador. Por padrão, o Windows Vista e o Windows Server 2008 exigem que um processo de chamada tenha privilégios de Administrador para instalar um driver em um dispositivo. |
|
O valor especificado para Sinalizadores não é zero ou um OR bit a bit dos sinalizadores válidos. |
|
O aplicativo de chamada é um aplicativo de 32 bits que está tentando executar em um ambiente de 64 bits, o que não é permitido. Para obter mais informações, consulte Instalando dispositivos em sistemas de 64 bits. |
Comentários
Chame DiInstallDevice somente se for necessário instalar um driver específico em um dispositivo específico. Caso contrário, use UpdateDriverForPlugAndPlayDevices ou DiInstallDriver para instalar um driver para um dispositivo. Para obter mais informações sobre quais dessas funções chamar para instalar um driver em um dispositivo, consulte SetupAPI Functions that Simplify Driver Installation.
Antes de chamar DiInstallDevice, o chamador deve obter uma estrutura SP_DEVINFO_DATA para especificar o dispositivo e, opcionalmente, uma estrutura SP_DRVINFO_DATA para especificar um driver para o dispositivo.
Para criar um conjunto de informações do dispositivo que contém o dispositivo especificado e obter uma estrutura SP_DEVINFO_DATA para o dispositivo, siga um destes procedimentos:
-
Chame SetupDiGetClassDevs para recuperar um conjunto de informações do dispositivo que contém o dispositivo e, em seguida, chame SetupDiEnumDeviceInfo para enumerar os dispositivos no conjunto de informações do dispositivo. Em cada chamada, SetupDiEnumDeviceInfo retorna uma estrutura SP_DEVINFO_DATA que representa o dispositivo enumerado no conjunto de informações do dispositivo. Para obter informações específicas sobre o dispositivo enumerado, chame SetupDiGetDeviceProperty e forneça a estrutura SP_DEVINFO_DATA retornada por SetupDiEnumDeviceInfo.
- OU –
- Chame SetupDiOpenDeviceInfo para adicionar um dispositivo com uma ID de instância de dispositivo conhecida ao conjunto de informações do dispositivo. SetupDiOpenDeviceInfo retorna uma estrutura SP_DEVINFO_DATA que representa o dispositivo no conjunto de informações do dispositivo.
Em geral, um aplicativo de instalação deve definir NeedReboot como NULL. Isso garante que DiInstallDevice solicite que o usuário reinicie o sistema se for necessária uma reinicialização para concluir a instalação. Um aplicativo deve fornecer um ponteiro NeedReboot somente nos seguintes casos:
- O aplicativo deve chamar DiInstallDevice várias vezes para concluir uma instalação. Nesse caso, o aplicativo deve registrar se um valor TRUENeedReboot é retornado por qualquer uma das chamadas para DiInstallDevice e, nesse caso, solicitar que o usuário reinicie o sistema após o retorno da chamada final para DiInstallDevice .
- O aplicativo deve executar as operações necessárias, além de chamar DiInstallDevice, antes que uma reinicialização do sistema ocorra. Se uma reinicialização do sistema for necessária, o aplicativo deverá concluir as operações necessárias e solicitar que o usuário reinicie o sistema.
- O aplicativo é um instalador de classe, nesse caso, o instalador de classe deve definir o sinalizador DI_NEEDREBOOT no membro Flags da estrutura SP_DEVINSTALL_PARAMS para um dispositivo.
Requisitos
| Requisito | Valor |
|---|---|
| Cliente mínimo com suporte | Disponível no Windows Vista e versões posteriores do Windows. |
| Plataforma de Destino | Área de Trabalho |
| Cabeçalho | newdev.h (inclua Newdev.h) |
| Biblioteca | Newdev.lib |
| DLL | Newdev.dll |