Função DiInstallDriverA (newdev.h)
A função DiInstallDriver pré-instala um driver no repositório de driver e instala o driver em dispositivos presentes no sistema ao qual o driver dá suporte.
Sintaxe
BOOL DiInstallDriverA(
[in, optional] HWND hwndParent,
[in] LPCSTR InfPath,
[in] DWORD Flags,
[out, optional] PBOOL NeedReboot
);
Parâmetros
[in, optional] hwndParent
Um identificador para a janela de nível superior que o DiInstallDriver 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] InfPath
Um ponteiro para uma cadeia de caracteres terminada em NULL que fornece o caminho totalmente qualificado do arquivo INF para o pacote de driver.
[in] Flags
Um valor do tipo DWORD que especifica zero ou uma combinação de um ou mais sinalizadores, conforme descrito aqui (Sinalizadores normalmente é definido como zero).
Se Flags for zero, o DiInstallDriver só instalará o driver especificado em um dispositivo se o driver for uma correspondência melhor para um dispositivo do que o driver instalado atualmente em um dispositivo. Para obter informações sobre como o Windows seleciona um driver para um dispositivo, consulte Como o Windows seleciona drivers.
Se Flags incluir DIIRFLAG_FORCE_INF, o DiInstallDriver instalará o driver especificado em um dispositivo correspondente se o driver for ou não uma correspondência melhor para o dispositivo do que o driver instalado no momento no dispositivo. Se DIIRFLAG_INSTALL_AS_SET também for especificado, DIIRFLAG_FORCE_INF será ignorado.
Se Flags incluir DIIRFLAG_INSTALL_AS_SET (com suporte no Windows 10 versão 1709 e posterior), o InfPath deverá especificar um diretório em vez de um caminho totalmente qualificado para um arquivo INF e o DiInstallDriver instalará todos os arquivos INF nesse diretório com comportamento especial. Todos os pacotes de driver serão preparados para o Driver Store , mas ainda não serão disponibilizados para serem instalados em dispositivos. No próximo desligamento do sistema, esses pacotes de driver serão disponibilizados para serem instalados em dispositivos daqui para frente e serão instalados em qualquer dispositivo que eles sejam a melhor correspondência para que os dispositivos estejam prontos na próxima inicialização do sistema.
[out, optional] NeedReboot
Um ponteiro para um valor do tipo BOOL que DiInstallDriver define para indicar se um sistema é reiniciado é necessário para concluir a instalação. Esse parâmetro é opcional e pode ser NULL. Se o parâmetro for fornecido e uma reinicialização do sistema for necessária para concluir a instalação, o DiInstallDriver definirá o valor como TRUE. Nesse caso, o chamador deve solicitar que o usuário reinicie o sistema. Se esse parâmetro for fornecido e uma reinicialização do sistema não for necessária para concluir a instalação, o DiInstallDriver definirá o valor como FALSE. Se o parâmetro for NULL e uma reinicialização do sistema for necessária para concluir a instalação, o DiInstallDriver exibirá uma caixa de diálogo de reinicialização do sistema. Para obter mais informações sobre esse parâmetro, consulte a seção Comentários a seguir.
Retornar valor
DiInstallDriver retornará TRUE se a função tiver pré-instalado com êxito o pacote de driver especificado no repositório de driver. O DiInstallDriver também retornará TRUE se a função tiver instalado com êxito o driver em um ou mais dispositivos no sistema. Se o pacote de driver não for instalado com êxito no repositório de driver, DiInstallDriver 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 exige que o chamador tenha privilégios de Administrador para pré-instalar um pacote de driver no repositório de driver. |
|
O caminho do arquivo INF especificado não existe. |
|
O valor especificado para Flags não é igual a zero ou DIIRFLAG_FORCE_INF. |
|
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
O DiInstallDriver executa as seguintes operações:
- Pré-instala o pacote de driver no repositório de driver. Se houver uma instância do mesmo pacote de driver já pré-instalada no repositório de driver, o DiInstallDriver primeiro removerá essa instância e, em seguida, adicionará a nova instância do pacote de driver ao repositório de driver.
- Enumera dispositivos que estão presentes no sistema.
- Se Flags for igual a zero, o instalará o driver em um dispositivo somente se o driver especificado for uma correspondência melhor para o dispositivo do que o driver instalado no dispositivo no momento.
- Se Flags for igual a DIIRFLAG_FORCE_INF, o instalará o driver em um dispositivo, independentemente de o pacote de driver ser a melhor correspondência com o dispositivo do que o driver instalado atualmente no dispositivo.
- O aplicativo deve chamar DiInstallDriver 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 DiInstallDriver e, nesse caso, solicitar que o usuário reinicie o sistema após o retorno da chamada final para DiInstallDriver .
- O aplicativo deve executar as operações necessárias, além de chamar DiInstallDriver, 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.
Observação
O cabeçalho newdev.h define DiInstallDriver como um alias que seleciona automaticamente a versão ANSI ou Unicode dessa função com base na definição da constante de pré-processador UNICODE. Misturar o uso do alias neutro de codificação com código que não seja neutro em codificação pode levar a incompatibilidades que resultam em erros de compilação ou de runtime. Para obter mais informações, consulte Convenções para protótipos de função.
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 |