Condividi tramite


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
ERROR_ACCESS_DENIED
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.
ERROR_INVALID_FLAGS
Il valore specificato per Flags non è zero o un OR bit per bit dei flag validi.
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

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.
Per recuperare una struttura SP_DRVINFO_DATA per un driver selezionato, chiamare SetupDiBuildDriverInfoList per compilare un elenco di driver per il dispositivo e quindi chiamare SetupDiEnumDriverInfo per enumerare gli elementi dell'elenco di driver per il dispositivo. Per ogni driver enumerato, SetupDiEnumDriverInfo recupera una struttura SP_DRVINFO_DATA che identifica il driver. SetupDiGetDriverInfoDetail può anche essere chiamato per recuperare dettagli aggiuntivi su un driver enumerato.

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

Vedi anche

DiInstallDriver

SetupDiBuildDriverInfoList

SetupDiEnumDeviceInfo

SetupDiEnumDriverInfo

SetupDiGetClassDevs

SetupDiGetDeviceProperty

SetupDiGetDriverInfoDetail

SetupDiOpenDeviceInfo

UpdateDriverForPlugAndPlayDevices