Função DiInstallDriverA (newdev.h)
A função
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 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, 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 no momento 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, DiInstallDriver instalará o driver especificado em um dispositivo correspondente se o driver é ou não uma melhor correspondência 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), 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
[out, optional] NeedReboot
Um ponteiro para um valor do tipo BOOL que diInstallDriver conjuntos 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, 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, 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, DiInstallDriver exibirá uma caixa de diálogo de reinicialização do sistema. Para obter mais informações sobre esse parâmetro, consulte a seguinte seção Comentários.
Valor de retorno
DiInstallDriver retornará verdadeiro se a função tiver pré-instalado com êxito o pacote de driver especificado no repositório de driver . DiInstallDriver também retornará VERDADEIRO 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 podem 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 de 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. |
Observações
DiInstallDriver executa as seguintes operações:
-
Pré-instala a do pacote de driver de
nodo repositório de driver de . Se houver uma instância do mesmo pacote de driver já pré-instalado no repositório de driver, DiInstallDriver primeiro removerá essa instância e 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, 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 momento no dispositivo.
- Se Flags for igual a DIIRFLAG_FORCE_INF, instalará o driver em um dispositivo, independentemente de o pacote de driver de for a melhor correspondência para o dispositivo do que o driver instalado no momento 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 a chamada final para o DiInstallDriver retorna.
- 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 Flags membro da estrutura SP_DEVINSTALL_PARAMS para um dispositivo.
Nota
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 do pré-processador UNICODE. A combinação do uso do alias neutro de codificação com código que não é neutro em codificação pode levar a incompatibilidades que resultam em erros de compilação ou de runtime. Para obter mais informações, consulte Conventions for Function Prototypes.
Requisitos
| Requisito | Valor |
|---|---|
| de cliente com suporte mínimo | Disponível no Windows Vista e versões posteriores do Windows. |
| da Plataforma de Destino |
Área de trabalho |
| cabeçalho | newdev.h (inclua Newdev.h) |
| biblioteca | Newdev.lib |