Funzione DiInstallDevice (newdev.h)
La funzione DiInstallDevice installa un driver specificato preinstallato nell'archivio driver in un dispositivo specificato presente nel sistema.
Sintassi
BOOL DiInstallDevice(
[in, optional] HWND hwndParent,
[in] HDEVINFO DeviceInfoSet,
[in] PSP_DEVINFO_DATA DeviceInfoData,
[in, optional] PSP_DRVINFO_DATA DriverInfoData,
[in] DWORD Flags,
[out, optional] PBOOL NeedReboot
);
Parametri
[in, optional] hwndParent
Handle per la finestra di primo livello usata da DiInstallDevice per visualizzare qualsiasi componente dell'interfaccia utente associato all'installazione del dispositivo. Questo parametro è facoltativo e può essere impostato su NULL.
[in] DeviceInfoSet
Handle per un set di informazioni sul dispositivo che contiene un elemento informazioni sul dispositivo che rappresenta il dispositivo specificato.
[in] DeviceInfoData
Puntatore a una struttura SP_DEVINFO_DATA che rappresenta il dispositivo specificato nel set di informazioni sul dispositivo specificato.
[in, optional] DriverInfoData
Puntatore a una struttura SP_DRVINFO_DATA che specifica il driver da installare nel dispositivo specificato. Questo parametro è facoltativo e può essere impostato su NULL. Se questo parametro è NULL, DiInstallDevice cerca i driver preinstallati nell'archivio driver per il driver che corrisponde al dispositivo specificato e, se presente, installa il driver nel dispositivo specificato.
[in] Flags
Valore di tipo DWORD che specifica zero o il flag seguente:
DIIDFLAG_SHOWSEARCHUI
Se il chiamante non specifica un driver (DriverInfoData è impostato su NULL) e DiInstallDevice non individua un driver preinstallato che corrisponde al dispositivo specificato. DiInstallDevice visualizza invece la procedura guidata Trovato nuovo hardware per il dispositivo.
DIIDFLAG_NOFINISHINSTALLUI
DiInstallDevice non avvia le pagine dell'installazione guidata o le azioni di fine installazione. Il chiamante di DiInstallDevice deve avviare queste operazioni. Il chiamante deve specificare questo flag solo se il chiamante richiede che le pagine della procedura guidata di installazione completa vengano richiamate nel contesto di un componente dell'interfaccia utente fornito dal chiamante.
DIIDFLAG_INSTALLNULLDRIVER
DiInstallDevice tenta di installare un driver Null nel dispositivo specificato. Se questo flag è impostato, DiInstallDevice non usa il parametro DriverInfoData . DiInstallDevice rimuove tutte le impostazioni del dispositivo e, se il dispositivo non può essere eseguito in modalità non elaborata, la funzione imposta lo stato del dispositivo su CM_PROB_FAILED_INSTALL. Se DiInstallDevice non è in grado di installare un driver Null, lo stato risultante del dispositivo è uguale a se il dispositivo è stato connesso per la prima volta al computer e Windows non ha individuato un driver per il dispositivo.
DIIDFLAG_INSTALLCOPYINFDRIVERS
Qualsiasi file INF aggiuntivo specificato tramite una direttiva CopyINF verrà installato in qualsiasi dispositivo a cui è applicabile. Eventuali errori durante l'installazione di un INF aggiuntivo non causano l'esito negativo dell'installazione primaria di INF.
[out, optional] NeedReboot
Puntatore a un valore di tipo BOOL impostato da DiInstallDevice per indicare se è necessario un riavvio del sistema per completare l'installazione. Questo parametro è facoltativo e può essere impostato su NULL. Se questo parametro viene fornito e per completare l'installazione è necessario riavviare il sistema, DiInstallDevice imposta il valore su TRUE. In questo caso, il chiamante è responsabile del riavvio del sistema. Se questo parametro viene fornito e non è necessario riavviare il sistema, DiInstallDevice imposta questo parametro su FALSE. Se questo parametro è NULL e per completare l'installazione è necessario riavviare il sistema, DiInstallDevice visualizza una finestra di dialogo di riavvio del sistema.
Valore restituito
DiInstallDevice restituisce TRUE se la funzione ha installato correttamente il driver specificato nel dispositivo specificato. In caso contrario, DiInstallDevice 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 |
|---|---|
|
Il chiamante non dispone dei privilegi di amministratore. Per impostazione predefinita, Windows Vista e Windows Server 2008 richiedono che un processo chiamante disponga dei privilegi di amministratore per installare un driver in un dispositivo. |
|
Il valore specificato per Flags non è zero o un OR bit per bit dei flag validi. |
|
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
Chiamare DiInstallDevice solo se è necessario installare un driver specifico in un dispositivo specifico. In caso contrario, usare UpdateDriverForPlugAndPlayDevices o DiInstallDriver per installare un driver per un dispositivo. Per altre informazioni su quali di queste funzioni chiamare per installare un driver in un dispositivo, vedere Funzioni SetupAPI che semplificano l'installazione del driver.
Prima di chiamare DiInstallDevice, il chiamante deve ottenere una struttura SP_DEVINFO_DATA per specificare il dispositivo e, facoltativamente, una struttura SP_DRVINFO_DATA per specificare un driver per il dispositivo.
Per creare un set di informazioni sul dispositivo contenente il dispositivo specificato e ottenere una struttura di SP_DEVINFO_DATA per il dispositivo, eseguire una delle operazioni seguenti:
-
Chiamare SetupDiGetClassDevs per recuperare un set di informazioni sul dispositivo contenente il dispositivo e quindi chiamare SetupDiEnumDeviceInfo per enumerare i dispositivi nel set di informazioni sul dispositivo. In ogni chiamata SetupDiEnumDeviceInfo restituisce una struttura SP_DEVINFO_DATA che rappresenta il dispositivo enumerato nel set di informazioni sul dispositivo. Per ottenere informazioni specifiche sul dispositivo enumerato, chiamare SetupDiGetDeviceProperty e specificare la struttura SP_DEVINFO_DATA restituita da SetupDiEnumDeviceInfo.
- oppure -
- Chiamare SetupDiOpenDeviceInfo per aggiungere un dispositivo con un ID istanza del dispositivo noto al set di informazioni sul dispositivo. SetupDiOpenDeviceInfo restituisce una struttura SP_DEVINFO_DATA che rappresenta il dispositivo nel set di informazioni sul dispositivo.
In generale, un'applicazione di installazione deve impostare NeedReboot su NULL. Ciò garantisce che DiInstallDevice richieda 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 DiInstallDevice più volte per completare un'installazione. In questo caso, l'applicazione deve registrare se un valore TrueNeedReboot viene restituito da una delle chiamate a DiInstallDevice e, in tal caso, chiedere all'utente di riavviare il sistema dopo la chiamata finale a DiInstallDevice.
- L'applicazione deve eseguire operazioni necessarie, diverse dalla chiamata a DiInstallDevice, 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.
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 |
| DLL | Newdev.dll |