Funzione DiUninstallDevice (newdev.h)

Articolo
02/29/2024

La funzione DiUninstallDevice disinstalla un dispositivo e rimuove il nodo del dispositivo (devnode) dal sistema. Ciò è diverso dall'uso di SetupDiCallClassInstaller con il codice DIF_REMOVE perché tenta di disinstallare il nodo del dispositivo oltre ai nodi di sviluppo figlio presenti al momento della chiamata.

Prima di Windows 8 tutti i dispositivi figlio non presenti al momento della chiamata non verranno disinstallati. Tuttavia, a partire da Windows 8, tutti i dispositivi figlio non presenti al momento della chiamata verranno disinstallati.

Sintassi

BOOL DiUninstallDevice(
  [in]            HWND             hwndParent,
  [in]            HDEVINFO         DeviceInfoSet,
  [in]            PSP_DEVINFO_DATA DeviceInfoData,
  [in]            DWORD            Flags,
  [out, optional] PBOOL            NeedReboot
);

Parametri

[in] hwndParent

Handle per la finestra di primo livello utilizzata per visualizzare qualsiasi componente dell'interfaccia utente associato alla richiesta di disinstallazione per il dispositivo. Questo parametro è facoltativo e può essere impostato su NULL.

[in] DeviceInfoSet

Handle per il set di informazioni sul dispositivo che contiene un elemento informazioni sul dispositivo. Questo elemento rappresenta il dispositivo da disinstallare tramite questa chiamata.

[in] DeviceInfoData

Puntatore a una struttura SP_DEVINFO_DATA che rappresenta il dispositivo specificato nel set di informazioni sul dispositivo specificato per cui viene eseguita la richiesta di disinstallazione.

[in] Flags

Valore di tipo DWORD che specifica i flag di disinstallazione del dispositivo. A partire da Windows 7, questo parametro deve essere impostato su zero.

[out, optional] NeedReboot

Puntatore a un valore di tipo BOOL impostato da DiUninstallDevice per indicare se è necessario un riavvio del sistema per completare la richiesta di disinstallazione del dispositivo. Questo parametro è facoltativo e può essere impostato su NULL.

Se il parametro viene specificato e è necessario riavviare il sistema, DiUninstallDevice imposta il valore su TRUE. In questo caso, l'applicazione deve richiedere all'utente di riavviare il sistema. Se questo parametro viene fornito e non è necessario riavviare il sistema, DiUninstallDevice imposta il valore su FALSE.

Se questo parametro è NULL e per completare la disinstallazione del dispositivo è necessario riavviare il sistema, DiUninstallDevice visualizza una finestra di dialogo di riavvio del sistema.

Per altre informazioni su questo parametro, vedere la sezione Osservazioni .

Valore restituito

DiUninstallDevice restituisce TRUE se la funzione ha disinstallato correttamente il nodo del dispositivo di primo livello che rappresenta il dispositivo. In caso contrario, DiUninstallDevice restituisce FALSE e l'errore registrato può essere recuperato effettuando una chiamata a GetLastError. L'elenco seguente mostra alcuni dei valori di errore più comuni che GetLastError potrebbe restituire per questa API:

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 disinstallare i dispositivi.
ERROR_INVALID_FLAGS	Il valore specificato per il parametro Flags non è uguale a zero.

Nota Il valore restituito non indica che la rimozione di tutti gli elementi di sviluppo figlio ha avuto esito positivo o negativo. A partire da Windows Vista, le informazioni sullo stato della rimozione di devnodes figlio sono disponibili nel file di Setupapi.dev.log . Per altre informazioni su questo file, vedere Log di testo setupAPI.

Commenti

DiUninstallDevice esegue la stessa funzione di SetupDiCallClassInstaller se usata con il codice DIF_REMOVE . La differenza principale è che vengono eliminati anche gli elementi di sviluppo figlio per il dispositivo di primo livello. DiUninstallDevice restituisce un errore solo se non è stato possibile disinstallare il nodo del dispositivo di primo livello, che è coerente con il comportamento di SetupDiCallClassInstaller se usato con il codice DIF_REMOVE . Informazioni dettagliate sull'esito positivo della disinstallazione di devnode figlio nel file di Setupapi.dev.log.

Il dispositivo da disinstallare viene specificato fornendo un set di informazioni sul dispositivo che include il dispositivo a cui si fa riferimento e una struttura SP_DEVINFO_DATA per il dispositivo specifico. Sono disponibili nei parametri DeviceInfoSet e DeviceInfoData .

Per creare un set di informazioni sul dispositivo contenente il dispositivo specificato e ottenere una struttura di SP_DEVINFO_DATA per il dispositivo, completare una delle attività 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.
Chiamare SetupDiEnumDeviceInfo 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.

Nel caso in cui la richiesta di disinstallazione del dispositivo richieda un riavvio del computer, DiUninstallDevice richiede all'utente di riavviare il sistema se il parametro NeedReboot è impostato su NULL. Se è presente una finestra dell'interfaccia utente usata dall'applicazione, il parametro hwndParent deve essere impostato sul valore dell'handle di tale finestra.

Tuttavia, se l'applicazione gestisce la notifica di un riavvio di sistema necessario, deve impostare il parametro NeedReboot su un valore non NULL . DiUninstallDevice imposta il parametro NeedReboot su TRUE o FALSE, a seconda che sia necessario un riavvio del sistema.

L'elenco seguente mostra alcuni esempi del motivo per cui l'applicazione potrebbe gestire il riavvio del sistema:

L'applicazione deve disinstallare diversi dispositivi. Dopo la disinstallazione di tutti i dispositivi, l'applicazione deve richiedere all'utente di riavviare il sistema se una chiamata a DiUninstallDevice ha restituito TRUE nel parametro NeedReboot .
L'applicazione richiede che vengano eseguite altre operazioni prima che il sistema possa essere riavviato. 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 classi. In questo 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 7 e versioni successive di Windows.
Piattaforma di destinazione	Desktop
Intestazione	newdev.h (include Newdev.h)
Libreria	Newdev.lib
DLL	Newdev.dll