Compartilhar via

Função UpdateDriverForPlugAndPlayDevicesA (newdev.h)

  • Artigo

Considerando um arquivo INF e uma ID de hardware, a função UpdateDriverForPlugAndPlayDevices instala drivers atualizados para dispositivos que correspondem à ID de hardware.

Sintaxe

BOOL UpdateDriverForPlugAndPlayDevicesA(
  [in, optional]  HWND   hwndParent,
  [in]            LPCSTR HardwareId,
  [in]            LPCSTR FullInfPath,
  [in]            DWORD  InstallFlags,
  [out, optional] PBOOL  bRebootRequired
);

Parâmetros

[in, optional] hwndParent

Um identificador para a janela de nível superior a ser usada para qualquer interface do usuário relacionada à instalação de dispositivos.

[in] HardwareId

Um ponteiro para uma cadeia de caracteres terminada em NULL que fornece o identificador de hardware para corresponder aos dispositivos existentes no computador. O comprimento máximo de um identificador de hardware terminado em NULL é MAX_DEVICE_ID_LEN. Para obter mais informações sobre identificadores de hardware, consulte Cadeias de caracteres de identificação de dispositivo.

[in] FullInfPath

Um ponteiro para uma cadeia de caracteres terminada em NULL que fornece o nome de arquivo de caminho completo de um arquivo INF. Os arquivos devem estar na mídia de distribuição ou em um diretório criado pelo fornecedor, não em um local do sistema, como %SystemRoot%\inf. UpdateDriverForPlugAndPlayDevices copia arquivos de driver para os locais apropriados do sistema se a instalação for bem-sucedida.

[in] InstallFlags

Um valor fornecido pelo chamador criado usando OR para combinar zero ou mais dos seguintes sinalizadores de bits:

INSTALLFLAG_FORCE

Se esse sinalizador estiver definido e a função encontrar um dispositivo que corresponda ao valor HardwareId , a função instalará novos drivers para o dispositivo, independentemente de os drivers melhores já existirem no computador.

Importante Use esse sinalizador apenas com extrema cautela. Definir esse sinalizador pode fazer com que um driver mais antigo seja instalado em um driver mais recente, se um usuário executar o aplicativo do fornecedor depois que drivers mais recentes estiverem disponíveis.
 

INSTALLFLAG_READONLY

Se esse sinalizador for definido, a função não copiará, renomeará ou excluirá arquivos de instalação. O uso desse sinalizador deve ser limitado a ambientes nos quais o acesso a arquivos é restrito ou impossível, como um sistema operacional "inserido".

INSTALLFLAG_NONINTERACTIVE

Se esse sinalizador for definido, a função retornará FALSE quando qualquer tentativa de exibir a interface do usuário for detectada. Defina esse sinalizador somente se a função for chamada de um componente (como um serviço) que não pode exibir a interface do usuário.

Nota Se esse sinalizador estiver definido e uma exibição de interface do usuário for tentada, o dispositivo poderá ser deixado em um estado indeterminado.
 
O parâmetro InstallFlags normalmente é zero.

[out, optional] bRebootRequired

Um ponteiro para uma variável do tipo BOOL que indica se uma reinicialização é necessária e quem deve solicitá-la. Esse ponteiro é opcional e pode ser NULL.

Se o ponteiro for NULL, UpdateDriverForPlugAndPlayDevices solicitará uma reinicialização após a instalação de drivers, se necessário. Se o ponteiro for fornecido, a função retornará um valor BOOLEAN que será TRUE se o sistema precisar ser reiniciado. Em seguida, é responsabilidade do chamador solicitar uma reinicialização.

Para obter mais informações, consulte a seção Comentários a seguir.

Retornar valor

A função retornará TRUE se um dispositivo tiver sido atualizado para o driver especificado.

Caso contrário, ele retornará FALSE e o erro registrado poderá ser recuperado com uma chamada para GetLastError. Possíveis valores de erro retornados por GetLastError estão incluídos na tabela a seguir.

Código de retorno Descrição
ERROR_FILE_NOT_FOUND
 O caminho especificado para FullInfPath não existe.
ERROR_IN_WOW64
 O aplicativo de chamada é um aplicativo de 32 bits que tenta executar em um ambiente de 64 bits, o que não é permitido.
ERROR_INVALID_FLAGS
 O valor especificado para InstallFlags é inválido.
ERROR_NO_SUCH_DEVINST
 O valor especificado para HardwareId não corresponde a nenhum dispositivo no sistema. Ou seja, o dispositivo não está conectado.
ERROR_NO_MORE_ITEMS
 A função encontrou uma correspondência para o valor hardwareid , mas o driver especificado não foi uma correspondência melhor do que o driver atual e o chamador não especificou o sinalizador INSTALLFLAG_FORCE.

Comentários

UpdateDriverForPlugAndPlayDevices examina os dispositivos no sistema e tenta instalar os drivers especificados por FullInfPath para qualquer dispositivo que corresponda ao valor de HardwareId especificado.

O comportamento padrão é instalar apenas os drivers especificados se eles forem melhores do que os drivers instalados no momento e os drivers especificados também forem uma correspondência melhor do que qualquer driver no %SystemRoot%\inf. Para obter mais informações, consulte Como o Windows seleciona drivers.

UpdateDriverForPlugAndPlayDevices também pode ser usado para determinar se o dispositivo com o valor de HardwareId especificado está conectado. Para obter mais informações, consulte Escrevendo um aplicativo de instalação de dispositivo.

UpdateDriverForPlugAndPlayDevices envia uma solicitação de IRP_MN_QUERY_REMOVE_DEVICE para o dispositivo especificado, todos os filhos do dispositivo e todos os outros dispositivos que fazem parte recursivamente das relações de remoção para o dispositivo. Se algum desses dispositivos falhar em uma solicitação de remoção de consulta, UpdateDriverForPlugAndPlayDevices definirá o sinalizador DI_NEEDREBOOT no membro Flags da estrutura SP_DEVINSTALL_PARAMS do dispositivo. Para obter informações sobre relações de remoção, consulte a solicitação de IRP_MN_QUERY_DEVICE_RELATIONS .

Em geral, os aplicativos de instalação de dispositivo devem fornecer NULL para bRebootRequired. Portanto, o sistema iniciará uma reinicialização, se necessário. Um aplicativo deve especificar um valor de ponteiro somente nos seguintes casos:

  • O aplicativo deve chamar UpdateDriverForPlugAndPlayDevices várias vezes para concluir uma instalação.
  • O aplicativo deve executar outras operações antes da reinicialização (se necessário).
  • O aplicativo é um instalador de classe, que deve definir DI_NEEDREBOOT em SP_DEVINSTALL_PARAMS se uma reinicialização for necessária.
Se o aplicativo precisar chamar UpdateDriverForPlugAndPlayDevices várias vezes, ele deverá salvar qualquer reinicialização TRUE status valor recebido e solicitar uma reinicialização após o retorno da chamada final.

Se a função retornar ERROR_IN_WOW64 em um aplicativo de 32 bits, o aplicativo estará em execução em um sistema de 64 bits, o que não é permitido. Para obter mais informações, consulte Instalando dispositivos em sistemas de 64 bits.

Requisitos

Requisito Valor
Cliente mínimo com suporte Disponível no Microsoft Windows 2000 e versões posteriores do Windows.
Plataforma de Destino Área de Trabalho
Cabeçalho newdev.h (inclua Newdev.h)
Biblioteca Newdev.lib