Função DiUninstallDevice (newdev.h)

Artigo
03/08/2023

A função DiUninstallDevice desinstala um dispositivo e remove seu nó de dispositivo (devnode) do sistema. Isso difere do uso de SetupDiCallClassInstaller com o código DIF_REMOVE porque ele tenta desinstalar o nó do dispositivo, além de devnodes filho que estão presentes no momento da chamada.

Antes de Windows 8 todos os dispositivos filho que não estão presentes no momento da chamada não serão desinstalados. No entanto, começando com Windows 8, todos os dispositivos filho que não estiverem presentes no momento da chamada serão desinstalados.

Sintaxe

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

Parâmetros

[in] hwndParent

Um identificador para a janela de nível superior que é usado para exibir qualquer componente de interface do usuário associado à solicitação de desinstalação para o dispositivo. Esse parâmetro é opcional e pode ser definido como NULL.

[in] DeviceInfoSet

Um identificador para o conjunto de informações do dispositivo que contém um elemento de informações do dispositivo. Esse elemento representa o dispositivo a ser desinstalado por meio dessa chamada.

[in] DeviceInfoData

Um ponteiro para uma estrutura SP_DEVINFO_DATA que representa o dispositivo especificado no conjunto de informações do dispositivo especificado para o qual a solicitação de desinstalação é executada.

[in] Flags

Um valor do tipo DWORD que especifica sinalizadores de desinstalação do dispositivo. A partir do Windows 7, esse parâmetro deve ser definido como zero.

[out, optional] NeedReboot

Um ponteiro para um valor do tipo BOOL que DiUninstallDevice define para indicar se uma reinicialização do sistema é necessária para concluir a solicitação de desinstalação do dispositivo. Esse parâmetro é opcional e pode ser definido como NULL.

Se o parâmetro for fornecido e uma reinicialização do sistema for necessária, DiUninstallDevice definirá o valor como TRUE. Nesse caso, o aplicativo deve solicitar que o usuário reinicie o sistema. Se esse parâmetro for fornecido e uma reinicialização do sistema não for necessária, DiUninstallDevice definirá o valor como FALSE.

Se esse parâmetro for NULL e uma reinicialização do sistema for necessária para concluir a desinstalação do dispositivo, DiUninstallDevice exibirá uma caixa de diálogo de reinicialização do sistema.

Para obter mais informações sobre esse parâmetro, consulte a seção Comentários .

Retornar valor

DiUninstallDevice retornará TRUE se a função desinstalar com êxito o nó de dispositivo de nível superior que representa o dispositivo. Caso contrário, DiUninstallDevice retornará FALSE e o erro registrado poderá ser recuperado fazendo uma chamada para GetLastError. A lista a seguir mostra alguns dos valores de erro mais comuns que GetLastError pode retornar para esta API:

Código de retorno	Descrição
ERROR_ACCESS_DENIED	O chamador não tem privilégios de Administrador. Por padrão, o Windows exige que o chamador tenha privilégios de Administrador para desinstalar dispositivos.
ERROR_INVALID_FLAGS	O valor especificado para o parâmetro Flags não é igual a zero.

Nota O valor retornado não indica que a remoção de todos os devnodes filho foi bem-sucedida ou falhou. A partir do Windows Vista, as informações sobre o status da remoção de devnodes filho estão disponíveis no arquivo Setupapi.dev.log. Para obter mais informações sobre esse arquivo, consulte SetupAPI Text Logs.

Comentários

DiUninstallDevice executa a mesma função que SetupDiCallClassInstaller quando usado com o código DIF_REMOVE . A principal diferença é que os devnodes filho para o dispositivo de nível superior também são excluídos. DiUninstallDevice só retornará uma falha se o nó de dispositivo de nível superior não tiver sido desinstalado, o que é consistente com o comportamento de SetupDiCallClassInstaller quando usado com o código DIF_REMOVE . Informações detalhadas sobre se a desinstalação de devnode filho foi bem-sucedida estão disponíveis no arquivo Setupapi.dev.log.

O dispositivo a ser desinstalado é especificado fornecendo um conjunto de informações de dispositivo que inclui o dispositivo referenciado e uma estrutura SP_DEVINFO_DATA para o dispositivo específico. Eles são fornecidos nos parâmetros DeviceInfoSet e DeviceInfoData .

Para criar um conjunto de informações do dispositivo que contém o dispositivo especificado e obter uma estrutura SP_DEVINFO_DATA para o dispositivo, conclua uma das seguintes tarefas:

Chame SetupDiGetClassDevs para recuperar um conjunto de informações do dispositivo que contém o dispositivo e, em seguida, chame SetupDiEnumDeviceInfo para enumerar os dispositivos no conjunto de informações do dispositivo. Em cada chamada, SetupDiEnumDeviceInfo retorna uma estrutura SP_DEVINFO_DATA que representa o dispositivo enumerado no conjunto de informações do dispositivo.
Para obter informações específicas sobre o dispositivo enumerado, chame SetupDiGetDeviceProperty e forneça a estrutura SP_DEVINFO_DATA retornada por SetupDiEnumDeviceInfo.
Chame SetupDiEnumDeviceInfo para adicionar um dispositivo com uma ID de instância de dispositivo conhecida ao conjunto de informações do dispositivo. SetupDiOpenDeviceInfo retorna uma estrutura SP_DEVINFO_DATA que representa o dispositivo no conjunto de informações do dispositivo.

Caso a solicitação de desinstalação do dispositivo exija uma reinicialização do computador, DiUninstallDevice solicitará que o usuário reinicie o sistema se o parâmetro NeedReboot estiver definido como NULL. Se houver alguma janela de interface do usuário que o aplicativo esteja usando, o parâmetro hwndParent deverá ser definido como o valor do identificador dessa janela.

No entanto, se o aplicativo gerenciar a notificação de uma reinicialização do sistema necessária, ele deverá definir o parâmetro NeedReboot como um valor não NULL . DiUninstallDevice define o parâmetro NeedReboot como TRUE ou FALSE, dependendo se uma reinicialização do sistema é necessária.

A lista a seguir mostra exemplos de por que o aplicativo pode gerenciar a reinicialização do sistema:

O aplicativo precisa desinstalar vários dispositivos. Depois que todos os dispositivos forem desinstalados, o aplicativo deverá solicitar que o usuário reinicie o sistema se qualquer chamada para DiUninstallDevice retornasse TRUE no parâmetro NeedReboot .
O aplicativo requer que algumas outras operações ocorram antes que o sistema possa ser reiniciado. Se uma reinicialização do sistema for necessária, o aplicativo deverá concluir as operações necessárias e solicitar que o usuário reinicie o sistema.
O aplicativo é um instalador de classe. Nesse caso, o instalador de classe deve definir o sinalizador DI_NEEDREBOOT no membro Flags da estrutura SP_DEVINSTALL_PARAMS para um dispositivo.

Requisitos

Requisito	Valor
Cliente mínimo com suporte	Disponível no Windows 7 e versões posteriores do Windows.
Plataforma de Destino	Área de Trabalho
Cabeçalho	newdev.h (inclua Newdev.h)
Biblioteca	Newdev.lib
DLL	Newdev.dll