Funzione DiInstallDriverA (newdev.h)

  • Articolo

La funzione DiInstallDriver preinstalla un driver nell'archivio driver e quindi installa il driver nei dispositivi presenti nel sistema supportato dal driver.

Sintassi

BOOL DiInstallDriverA(
  [in, optional]  HWND   hwndParent,
  [in]            LPCSTR InfPath,
  [in]            DWORD  Flags,
  [out, optional] PBOOL  NeedReboot
);

Parametri

[in, optional] hwndParent

Handle alla finestra di primo livello utilizzata da DiInstallDriver per visualizzare qualsiasi componente dell'interfaccia utente associato all'installazione del dispositivo. Questo parametro è facoltativo e può essere impostato su NULL.

[in] InfPath

Puntatore a una stringa con terminazione NULL che fornisce il percorso completo del file INF per il pacchetto driver.

[in] Flags

Valore di tipo DWORD che specifica zero o una combinazione di uno o più flag, come descritto qui (i flag sono in genere impostati su zero).

Se flag è zero, DiInstallDriver installa solo il driver specificato in un dispositivo se il driver è una corrispondenza migliore per un dispositivo rispetto al driver attualmente installato in un dispositivo. Per informazioni sul modo in cui Windows seleziona un driver per un dispositivo, vedere How Windows Selects Drivers (How Windows Selects Driver).

Se flag include DIIRFLAG_FORCE_INF, DiInstallDriver installa il driver specificato in un dispositivo corrispondente se il driver è una corrispondenza migliore per il dispositivo rispetto al driver attualmente installato nel dispositivo. Se DIIRFLAG_INSTALL_AS_SET viene specificato anche, DIIRFLAG_FORCE_INF viene ignorato.

Attenzione La forzatura dell'installazione del driver può comportare la sostituzione di un driver più compatibile o più recente con un driver meno compatibile o meno recente.
 

Se i flag includono DIIRFLAG_INSTALL_AS_SET (supportati in Windows 10 versione 1709 e versioni successive), InfPath deve specificare una directory anziché un percorso completo a un file INF e DiInstallDriver installerà tutti i file INF in tale directory con un comportamento speciale. Tutti i pacchetti driver verranno inseriti nell'archivio driver, ma non saranno resi disponibili per l'installazione nei dispositivi ancora. Al successivo arresto del sistema, questi pacchetti driver saranno resi disponibili per l'installazione nei dispositivi in futuro e verranno installati in tutti i dispositivi che sono la corrispondenza migliore per tale che i dispositivi siano pronti all'avvio successivo del sistema.

[out, optional] NeedReboot

Puntatore a un valore di tipo BOOL impostato da DiInstallDriver per indicare se è necessario riavviare un sistema per completare l'installazione. Questo parametro è facoltativo e può essere NULL. Se il parametro viene fornito e è necessario un riavvio del sistema per completare l'installazione, DiInstallDriver imposta il valore su TRUE. In questo caso, il chiamante deve richiedere all'utente di riavviare il sistema. Se questo parametro viene fornito e non è necessario completare l'installazione, DiInstallDriver imposta il valore su FALSE. Se il parametro è NULL e è necessario un riavvio del sistema per completare l'installazione, DiInstallDriver visualizza una finestra di dialogo di riavvio del sistema. Per altre informazioni su questo parametro, vedere la sezione Osservazioni seguenti.

Valore restituito

DiInstallDriver restituisce TRUE se la funzione ha preinstallato correttamente il pacchetto driver specificato nell'archivio driver. DiInstallDriver restituisce anche TRUE se la funzione ha installato correttamente il driver in uno o più dispositivi nel sistema. Se il pacchetto driver non è installato correttamente nell'archivio driver, DiInstallDriver restituisce FALSE e l'errore registrato può essere recuperato eseguendo una chiamata a GetLastError. Alcuni dei valori di errore più comuni che GetLastError potrebbero restituire sono i seguenti:

Codice restituito Descrizione
ERROR_ACCESS_DENIED
 Il chiamante non dispone dei privilegi di amministratore. Per impostazione predefinita, Windows richiede che il chiamante disponga dei privilegi di amministratore per preinstallare un pacchetto drivernell'archivio driver.
ERROR_FILE_NOT_FOUND
 Il percorso del file INF specificato non esiste.
ERROR_INVALID_FLAGS
 Il valore specificato per Flags non è uguale a zero o DIIRFLAG_FORCE_INF.
ERROR_IN_WOW64
 L'applicazione chiamante è un'applicazione a 32 bit che tenta di eseguire in un ambiente a 64 bit, che non è consentito. Per altre informazioni, vedere Installazione di dispositivi in sistemi a 64 bit.

Commenti

DiInstallDriver esegue le operazioni seguenti:

  1. Preinstalla il pacchetto drivernell'archivio driver. Se esiste un'istanza dello stesso pacchetto driver già preinstallato nell'archivio driver, DiInstallDriver rimuove prima tale istanza e quindi aggiunge la nuova istanza del pacchetto driver all'archivio driver.
  2. Enumera i dispositivi presenti nel sistema.
  3. Se flag è uguale a zero, installa il driver in un dispositivo solo se il driver specificato è una corrispondenza migliore per il dispositivo rispetto al driver attualmente installato nel dispositivo.
  4. Se Flag è uguale a DIIRFLAG_FORCE_INF, installa il driver in un dispositivo indipendentemente dal fatto che il pacchetto driver corrisponda al dispositivo rispetto al driver attualmente installato nel dispositivo.
In generale, un'applicazione di installazione deve impostare NeedReboot su NULL per indirizzare DiInstallDriver per richiedere all'utente di riavviare il sistema se è necessario un riavvio per completare l'installazione. Un'applicazione deve fornire un puntatore NeedReboot solo nei casi seguenti:
  • L'applicazione deve chiamare DiInstallDriver più volte per completare un'installazione. In questo caso, l'applicazione deve registrare se un valore TRUENeedReboot viene restituito da una delle chiamate a DiInstallDriver e, in tal caso, chiedere all'utente di riavviare il sistema dopo la chiamata finale a DiInstallDriver .
  • L'applicazione deve eseguire operazioni necessarie, diversamente dalla chiamata di DiInstallDriver, prima che si verifichi un riavvio del sistema. Se è necessario un riavvio del sistema, l'applicazione deve completare le operazioni necessarie e quindi richiedere all'utente di riavviare il sistema.
  • L'applicazione è un programma di installazione della classe, nel qual caso, il programma di installazione della classe deve impostare il flag DI_NEEDREBOOT nel membro Flag della struttura SP_DEVINSTALL_PARAMS per un dispositivo.
Per installare un driver selezionato in un dispositivo selezionato, chiamare DiInstallDevice. Per altre informazioni, vedere Funzioni setupAPI che semplificano l'installazione del driver.

Nota

L'intestazione newdev.h definisce DiInstallDriver come alias che seleziona automaticamente la versione ANSI o Unicode di questa funzione in base alla definizione della costante preprocessore UNICODE. La combinazione dell'utilizzo dell'alias di codifica neutrale con il codice che non è neutrale dalla codifica può causare errori di corrispondenza che causano errori di compilazione o runtime. Per altre informazioni, vedere Convenzioni per i prototipi di funzione.

Requisiti

Requisito Valore
Client minimo supportato Disponibile in Windows Vista e versioni successive di Windows.
Piattaforma di destinazione Desktop
Intestazione newdev.h (include Newdev.h)
Libreria Newdev.lib

Vedi anche

DiInstallDevice