Función DiUninstallDevice (newdev.h)

Artículo
08/25/2023

La función DiUninstallDevice desinstala un dispositivo y quita su nodo de dispositivo (devnode) del sistema. Esto difiere del uso de SetupDiCallClassInstaller con el código de DIF_REMOVE porque intenta desinstalar el nodo del dispositivo además de los devnodes secundarios que están presentes en el momento de la llamada.

Antes de Windows 8 los dispositivos secundarios que no estén presentes en el momento de la llamada no se desinstalarán. Sin embargo, a partir de Windows 8, se desinstalarán todos los dispositivos secundarios que no estén presentes en el momento de la llamada.

Sintaxis

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

Parámetros

[in] hwndParent

Identificador de la ventana de nivel superior que se usa para mostrar cualquier componente de interfaz de usuario asociado a la solicitud de desinstalación del dispositivo. Este parámetro es opcional y se puede establecer en NULL.

[in] DeviceInfoSet

Identificador del conjunto de información del dispositivo que contiene un elemento de información del dispositivo. Este elemento representa el dispositivo que se va a desinstalar a través de esta llamada.

[in] DeviceInfoData

Puntero a una estructura de SP_DEVINFO_DATA que representa el dispositivo especificado en el conjunto de información del dispositivo especificado para el que se realiza la solicitud de desinstalación.

[in] Flags

Valor de tipo DWORD que especifica las marcas de desinstalación de dispositivos. A partir de Windows 7, este parámetro debe establecerse en cero.

[out, optional] NeedReboot

Puntero a un valor de tipo BOOL que DiUninstallDevice establece para indicar si se requiere un reinicio del sistema para completar la solicitud de desinstalación del dispositivo. Este parámetro es opcional y se puede establecer en NULL.

Si se especifica el parámetro y se requiere un reinicio del sistema, DiUninstallDevice establece el valor en TRUE. En este caso, la aplicación debe pedir al usuario que reinicie el sistema. Si se proporciona este parámetro y no se requiere un reinicio del sistema, DiUninstallDevice establece el valor en FALSE.

Si este parámetro es NULL y se requiere un reinicio del sistema para completar la desinstalación del dispositivo, DiUninstallDevice muestra un cuadro de diálogo de reinicio del sistema.

Para obtener más información sobre este parámetro, vea la sección Comentarios .

Valor devuelto

DiUninstallDevice devuelve TRUE si la función desinstaló correctamente el nodo de dispositivo de nivel superior que representa el dispositivo. De lo contrario, DiUninstallDevice devuelve FALSE y el error registrado se puede recuperar realizando una llamada a GetLastError. En la lista siguiente se muestran algunos de los valores de error más comunes que GetLastError podría devolver para esta API:

Código devuelto	Descripción
ERROR_ACCESS_DENIED	El autor de la llamada no tiene privilegios de administrador. De forma predeterminada, Windows requiere que el autor de la llamada tenga privilegios de administrador para desinstalar dispositivos.
ERROR_INVALID_FLAGS	El valor especificado para el parámetro Flags no es igual a cero.

Nota El valor devuelto no indica que la eliminación de todos los nodos secundarios se ha realizado correctamente o ha producido un error. A partir de Windows Vista, la información sobre el estado de la eliminación de los nodos secundarios está disponible en el archivo Setupapi.dev.log . Para obtener más información sobre este archivo, vea SetupAPI Text Logs.

Comentarios

DiUninstallDevice realiza la misma función que SetupDiCallClassInstaller cuando se usa con el código DIF_REMOVE . La diferencia clave es que también se eliminan los devnodes secundarios para el dispositivo de nivel superior. DiUninstallDevice solo devuelve un error si no se pudo desinstalar el nodo de dispositivo de nivel superior, que es coherente con el comportamiento de SetupDiCallClassInstaller cuando se usa con el código de DIF_REMOVE . La información detallada sobre si la desinstalación de devnode secundaria se realizó correctamente está disponible en el archivo Setupapi.dev.log.

El dispositivo que se va a desinstalar se especifica proporcionando un conjunto de información del dispositivo que incluye el dispositivo al que se hace referencia y una estructura de SP_DEVINFO_DATA para el dispositivo específico. Estos se proporcionan en los parámetros DeviceInfoSet y DeviceInfoData .

Para crear un conjunto de información de dispositivo que contenga el dispositivo especificado y para obtener una estructura de SP_DEVINFO_DATA para el dispositivo, complete una de las siguientes tareas:

Llame a SetupDiGetClassDevs para recuperar un conjunto de información del dispositivo que contiene el dispositivo y, a continuación, llame a SetupDiEnumDeviceInfo para enumerar los dispositivos del conjunto de información del dispositivo. En cada llamada, SetupDiEnumDeviceInfo devuelve una estructura SP_DEVINFO_DATA que representa el dispositivo enumerado en el conjunto de información del dispositivo.
Para obtener información específica sobre el dispositivo enumerado, llame a SetupDiGetDeviceProperty y proporcione la estructura SP_DEVINFO_DATA devuelta por SetupDiEnumDeviceInfo.
Llame a SetupDiEnumDeviceInfo para agregar un dispositivo con un identificador de instancia de dispositivo conocido al conjunto de información del dispositivo. SetupDiOpenDeviceInfo devuelve una estructura SP_DEVINFO_DATA que representa el dispositivo en el conjunto de información del dispositivo.

En caso de que la solicitud de desinstalación de dispositivos requiera un reinicio del equipo, DiUninstallDevice solicita al usuario que reinicie el sistema si el parámetro NeedReboot está establecido en NULL. Si hay alguna ventana de interfaz de usuario que use la aplicación, el parámetro hwndParent debe establecerse en el valor del identificador de esa ventana.

Sin embargo, si la aplicación administra la notificación de un reinicio del sistema necesario, debe establecer el parámetro NeedReboot en un valor distinto de NULL . DiUninstallDevice establece el parámetro NeedReboot en TRUE o FALSE, dependiendo de si se requiere un reinicio del sistema.

En la lista siguiente se muestran ejemplos de por qué la aplicación podría administrar el reinicio del sistema:

La aplicación tiene que desinstalar varios dispositivos. Una vez desinstalados todos los dispositivos, la aplicación debe pedir al usuario que reinicie el sistema si alguna llamada a DiUninstallDevice devolvió TRUE en el parámetro NeedReboot .
La aplicación requiere que se produzcan otras operaciones antes de que se pueda reiniciar el sistema. Si se requiere un reinicio del sistema, la aplicación debe finalizar las operaciones necesarias y, a continuación, pedir al usuario que reinicie el sistema.
La aplicación es un instalador de clase. En este caso, el instalador de clase debe establecer la marca DI_NEEDREBOOT en el miembro Flags de la estructura SP_DEVINSTALL_PARAMS de un dispositivo.

Requisitos

Requisito	Value
Cliente mínimo compatible	Disponible en Windows 7 y versiones posteriores de Windows.
Plataforma de destino	Escritorio
Encabezado	newdev.h (incluya Newdev.h)
Library	Newdev.lib
Archivo DLL	Newdev.dll