Funzione DiInstallDriverA (newdev.h)

Articolo
11/20/2024

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 per la finestra di primo livello usata 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 di seguito (Flag viene in genere impostato 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 su come Windows seleziona un driver per un dispositivo, vedere How Windows Selects Drivers.

Se Flag include DIIRFLAG_FORCE_INF, DiInstallDriver installa il driver specificato in un dispositivo corrispondente indipendentemente dal fatto che il driver sia una corrispondenza migliore per il dispositivo rispetto al driver attualmente installato nel dispositivo. Se viene specificato anche DIIRFLAG_INSTALL_AS_SET, DIIRFLAG_FORCE_INF viene ignorato.

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

Se Flag include DIIRFLAG_INSTALL_AS_SET (supportato in Windows 10 versione 1709 e successive), InfPath deve specificare una directory anziché un percorso completo di un file INF e DiInstallDriver installerà tutti i file INF in tale directory con un comportamento speciale. Tutti i pacchetti driver verranno inseriti nella Driver Store, ma non saranno ancora disponibili per l'installazione nei dispositivi. 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 in modo che i dispositivi siano pronti all'avvio successivo del sistema.

[out, optional] NeedReboot

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

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 del sistema. Se il pacchetto driver non è installato correttamente nell'archivio driver, DiInstallDriver restituisce false e l'errore registrato può essere recuperato effettuando una chiamata a GetLastError. Di seguito sono riportati alcuni dei valori di errore più comuni che GetLastError:

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 driver nell'archivio driver .
ERROR_FILE_NOT_FOUND	Il percorso del file INF specificato non esiste.
ERROR_INVALID_FLAGS	Il valore specificato per flag 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 è consentita. Per altre informazioni, vedere Installazione di dispositivi in sistemi a 64 bit.

Osservazioni

DiInstallDriver esegue le operazioni seguenti:

Preinstalla il pacchetto driver nell'archivio driver . Se nell'archivio driver è già preinstallata un'istanza dello stesso pacchetto driver, DiInstallDriver prima rimuove tale istanza e quindi aggiunge la nuova istanza del pacchetto driver all'archivio driver.
Enumera i dispositivi presenti nel sistema.
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.
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 chiedere 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, oltre a chiamare DiInstallDriver, prima che si verifichi un riavvio del sistema. Se è necessario un riavvio del sistema, l'applicazione deve completare le operazioni necessarie e quindi chiedere 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 DI_NEEDREBOOT nel flag membro della struttura di 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 del preprocessore UNICODE. La combinazione dell'utilizzo dell'alias indipendente dalla codifica con il codice non indipendente dalla codifica può causare mancate corrispondenze che generano errori di compilazione o di runtime. Per altre informazioni, vedere convenzioni di per i prototipi di funzioni.

Fabbisogno

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

Vedere anche

DiInstallDevice

Condividi tramite