Fonction DiUninstallDevice (newdev.h)

Article
08/25/2023

La fonction DiUninstallDevice désinstalle un appareil et supprime son nœud d’appareil (devnode) du système. Cela diffère de l’utilisation de SetupDiCallClassInstaller avec le code DIF_REMOVE , car il tente de désinstaller le nœud d’appareil en plus des devnodes enfants présents au moment de l’appel.

Avant Windows 8 les appareils enfants qui ne sont pas présents au moment de l’appel ne seront pas désinstallés. Toutefois, à compter de Windows 8, tous les appareils enfants qui ne sont pas présents au moment de l’appel seront désinstallés.

Syntaxe

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

Paramètres

[in] hwndParent

Handle de la fenêtre de niveau supérieur utilisé pour afficher tout composant d’interface utilisateur associé à la demande de désinstallation de l’appareil. Ce paramètre est facultatif et peut être défini sur NULL.

[in] DeviceInfoSet

Handle du jeu d’informations d’appareil qui contient un élément d’informations sur l’appareil. Cet élément représente l’appareil à désinstaller via cet appel.

[in] DeviceInfoData

Pointeur vers une structure SP_DEVINFO_DATA qui représente l’appareil spécifié dans le jeu d’informations d’appareil spécifié pour lequel la demande de désinstallation est effectuée.

[in] Flags

Valeur de type DWORD qui spécifie les indicateurs de désinstallation de l’appareil. À compter de Windows 7, ce paramètre doit être défini sur zéro.

[out, optional] NeedReboot

Pointeur vers une valeur de type BOOL que DiUninstallDevice définit pour indiquer si un redémarrage du système est nécessaire pour terminer la demande de désinstallation de l’appareil. Ce paramètre est facultatif et peut être défini sur NULL.

Si le paramètre est donné et qu’un redémarrage du système est requis, DiUninstallDevice définit la valeur TRUE. Dans ce cas, l’application doit inviter l’utilisateur à redémarrer le système. Si ce paramètre est fourni et qu’un redémarrage du système n’est pas requis, DiUninstallDevice définit la valeur SUR FALSE.

Si ce paramètre a la valeur NULL et qu’un redémarrage du système est nécessaire pour terminer la désinstallation de l’appareil, DiUninstallDevice affiche une boîte de dialogue de redémarrage du système.

Pour plus d’informations sur ce paramètre, consultez la section Remarques .

Valeur retournée

DiUninstallDevice retourne TRUE si la fonction a correctement désinstallé le nœud d’appareil de niveau supérieur qui représente l’appareil. Sinon, DiUninstallDevice retourne FALSE, et l’erreur journalisée peut être récupérée en effectuant un appel à GetLastError. La liste suivante présente certaines des valeurs d’erreur les plus courantes que GetLastError peut retourner pour cette API :

Code de retour	Description
ERROR_ACCESS_DENIED	L’appelant ne dispose pas de privilèges d’administrateur. Par défaut, Windows exige que l’appelant dispose de privilèges d’administrateur pour désinstaller les appareils.
ERROR_INVALID_FLAGS	La valeur spécifiée pour le paramètre Flags n’est pas égale à zéro.

Note La valeur de retour n’indique pas que la suppression de tous les devnodes enfants a réussi ou échoué. À compter de Windows Vista, des informations sur la status de la suppression des devnodes enfants sont disponibles dans le fichier Setupapi.dev.log. Pour plus d’informations sur ce fichier, consultez SetupAPI Text Logs.

Remarques

DiUninstallDevice exécute la même fonction que SetupDiCallClassInstaller lorsqu’il est utilisé avec le code DIF_REMOVE . La principale différence est que les devnodes enfants pour l’appareil de niveau supérieur sont également supprimés. DiUninstallDevice retourne l’échec uniquement si le nœud d’appareil de niveau supérieur n’a pas pu être désinstallé, ce qui est cohérent avec le comportement de SetupDiCallClassInstaller lorsqu’il est utilisé avec le code DIF_REMOVE . Des informations détaillées sur la réussite de la désinstallation du devnode enfant sont disponibles dans le fichier Setupapi.dev.log.

L’appareil à désinstaller est spécifié en fournissant un jeu d’informations sur l’appareil qui inclut l’appareil référencé et une structure SP_DEVINFO_DATA pour l’appareil spécifique. Ceux-ci sont fournis dans les paramètres DeviceInfoSet et DeviceInfoData .

Pour créer un jeu d’informations sur l’appareil qui contient l’appareil spécifié et obtenir une structure SP_DEVINFO_DATA pour l’appareil, effectuez l’une des tâches suivantes :

Appelez SetupDiGetClassDevs pour récupérer un jeu d’informations sur l’appareil qui contient l’appareil, puis appelez SetupDiEnumDeviceInfo pour énumérer les appareils dans le jeu d’informations de l’appareil. À chaque appel, SetupDiEnumDeviceInfo retourne une structure SP_DEVINFO_DATA qui représente l’appareil énuméré dans le jeu d’informations de l’appareil.
Pour obtenir des informations spécifiques sur l’appareil énuméré, appelez SetupDiGetDeviceProperty et fournissez la structure SP_DEVINFO_DATA retournée par SetupDiEnumDeviceInfo.
Appelez SetupDiEnumDeviceInfo pour ajouter un appareil avec un id de instance d’appareil connu à l’ensemble d’informations de l’appareil. SetupDiOpenDeviceInfo retourne une structure SP_DEVINFO_DATA qui représente l’appareil dans le jeu d’informations de l’appareil.

Si la demande de désinstallation de l’appareil nécessite un redémarrage de l’ordinateur, DiUninstallDevice invite l’utilisateur à redémarrer le système si le paramètre NeedReboot a la valeur NULL. Si l’application utilise une fenêtre d’interface utilisateur, le paramètre hwndParent doit être défini sur la valeur du handle de cette fenêtre.

Toutefois, si l’application gère la notification d’un redémarrage système requis, elle doit définir le paramètre NeedReboot sur une valeur non NULL . DiUninstallDevice définit le paramètre NeedReboot sur TRUE ou FALSE, selon qu’un redémarrage du système est nécessaire ou non.

La liste suivante montre des exemples de raisons pour lesquelles l’application peut gérer le redémarrage du système :

L’application doit désinstaller plusieurs appareils. Une fois tous les appareils désinstallés, l’application doit inviter l’utilisateur à redémarrer le système si un appel à DiUninstallDevice a retourné TRUE dans le paramètre NeedReboot .
L’application nécessite d’autres opérations pour que le système puisse être redémarré. Si un redémarrage du système est nécessaire, l’application doit terminer les opérations requises, puis inviter l’utilisateur à redémarrer le système.
L’application est un programme d’installation de classe. Dans ce cas, le programme d’installation de classe doit définir l’indicateur DI_NEEDREBOOT dans le membre Indicateurs de la structure SP_DEVINSTALL_PARAMS d’un appareil.

Configuration requise

Condition requise	Valeur
Client minimal pris en charge	Disponible dans Windows 7 et versions ultérieures de Windows.
Plateforme cible	Desktop (Expérience utilisateur)
En-tête	newdev.h (inclure Newdev.h)
Bibliothèque	Newdev.lib
DLL	Newdev.dll