Função DiInstallDriverW (newdev.h)

  • Artigo

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 DiInstallDriverW(
  [in, optional]  HWND    hwndParent,
  [in]            LPCWSTR 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.

Cuidado Forçar a instalação do driver pode resultar na substituição de um driver mais compatível ou mais recente por um driver menos compatível ou mais antigo.
 

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 uma reinicialização do sistema é necessária 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
ERROR_ACCESS_DENIED
 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.
ERROR_FILE_NOT_FOUND
 O caminho do arquivo INF especificado não existe.
ERROR_INVALID_FLAGS
 O valor especificado para Flags não é igual a zero ou DIIRFLAG_FORCE_INF.
ERROR_IN_WOW64
 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:

  1. 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.
  2. Enumera dispositivos que estão presentes no sistema.
  3. 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.
  4. 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.
Em geral, um aplicativo de instalação deve definir NeedReboot como NULL para direcionar o DiInstallDriver para solicitar 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 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.
Para instalar um driver selecionado em um dispositivo selecionado, chame DiInstallDevice. Para obter mais informações, consulte SetupAPI Functions that Simplify Driver Installation.

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

Confira também

DiInstallDevice