Funzione DiInstallDriverW (newdev.h)

Articolo
02/29/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 DiInstallDriverW(
  [in, optional]  HWND    hwndParent,
  [in]            LPCWSTR InfPath,
  [in]            DWORD   Flags,
  [out, optional] PBOOL   NeedReboot
);

Parametri

[in, optional] hwndParent

Handle per la finestra di primo livello usata 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 Flags è zero, DiInstallDriver installa 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 .For information about how Windows selects drivers.

Se Flags 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 Flags 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 nell'Archivio driver , ma non saranno ancora disponibili per l'installazione nei dispositivi. Al successivo arresto del sistema, questi pacchetti driver verranno resi disponibili per l'installazione nei dispositivi in futuro e verranno installati in tutti i dispositivi che rappresentano la corrispondenza migliore per tale che i dispositivi siano pronti al successivo avvio del sistema.

[out, optional] NeedReboot

Puntatore a un valore di tipo BOOL impostato da DiInstallDriver per indicare se è necessario un riavvio del sistema per completare l'installazione. Questo parametro è facoltativo e può essere NULL. Se il parametro viene fornito e per completare l'installazione è necessario riavviare il sistema, 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 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 nel 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 restituiti da 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 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 è consentita. Per altre informazioni, vedere Installazione di dispositivi in sistemi a 64 bit.

Commenti

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 rimuove prima tale istanza e quindi aggiunge la nuova istanza del pacchetto driver all'archivio driver.
Enumera i dispositivi presenti nel sistema.
Se Flags è 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 Flags è 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 a 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 True NeedReboot viene restituito da una delle chiamate a DiInstallDriver e, in tal caso, chiedere all'utente di riavviare il sistema dopo la restituzione della chiamata finale a DiInstallDriver.
L'applicazione deve eseguire le 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 di classe, nel qual caso, il programma di installazione della classe deve impostare il flag DI_NEEDREBOOT nel membro Flags della struttura SP_DEVINSTALL_PARAMS per un dispositivo.

Per installare un driver selezionato in un dispositivo selezionato, chiama DiInstallDevice. Per altre informazioni, vedi 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 che non è indipendente dalla codifica può causare mancate corrispondenze che generano errori di compilazione o di runtime. Per altre informazioni, vedere Convenzioni per i prototipi di funzioni.

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

Condividi tramite