Função DiRollbackDriver (newdev.h)
A função DiRollbackDriver reverte o driver instalado em um dispositivo especificado.
Sintaxe
BOOL DiRollbackDriver(
[in] HDEVINFO DeviceInfoSet,
[in] PSP_DEVINFO_DATA DeviceInfoData,
[in, optional] HWND hwndParent,
[in] DWORD Flags,
[out, optional] PBOOL NeedReboot
);
Parâmetros
[in] DeviceInfoSet
Um identificador para o conjunto de informações do dispositivo que contém um elemento de informações do dispositivo que representa o dispositivo para o qual a reversão do driver é executada.
[in] DeviceInfoData
Um ponteiro para uma estrutura SP_DEVINFO_DATA que representa o dispositivo específico no conjunto de informações do dispositivo especificado para o qual a reversão do driver é executada.
[in, optional] hwndParent
Um identificador para a janela de nível superior que o DiRollbackDriver usa para exibir qualquer componente de interface do usuário associado a uma reversão de driver para o dispositivo especificado. Esse parâmetro é opcional e pode ser definido como NULL.
[in] Flags
Um valor do tipo DWORD que pode ser definido como zero ou ROLLBACK_FLAG_NO_UI.
Normalmente, esse sinalizador deve ser definido como zero; nesse caso, o DiRollbackDriver não suprime os componentes de interface do usuário padrão associados a uma reversão de driver. No entanto, se esse sinalizador estiver definido como ROLLBACK_FLAG_NO_UI, o DiRollbackDriver suprimirá a exibição de componentes de interface do usuário associados a uma reversão de driver.
[out, optional] NeedReboot
Um ponteiro para um valor do tipo BOOL que DiRollbackDriver define para indicar se uma reinicialização do sistema é necessária para concluir a reversão. Esse parâmetro é opcional e pode ser NULL.
Se o parâmetro for fornecido e uma reinicialização do sistema for necessária para concluir a reversão, DiRollbackDriver definirá o valor como TRUE. Nesse caso, o chamador 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 para concluir a instalação, o DiRollbackDriver definirá o valor como FALSE.
Se o parâmetro for NULL e uma reinicialização do sistema for necessária para concluir a reversão, o DiRollbackDriver 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 a seguir.
Retornar valor
DiRollbackDriver retornará TRUE se a função tiver revertido com êxito o driver para o dispositivo; caso contrário, DiRollbackDriver retornará FALSE e o erro registrado poderá ser recuperado fazendo uma chamada para GetLastError. Alguns dos valores de erro mais comuns que GetLastError pode retornar são os seguintes:
| Código de retorno | Descrição |
|---|---|
|
O chamador não tem privilégios de Administrador. Por padrão, o Windows exige que o chamador tenha privilégios de Administrador para reverter um pacote de driver. |
|
O aplicativo de chamada é um aplicativo de 32 bits que está tentando executar em um ambiente de 64 bits, o que não é permitido. Para obter mais informações, consulte Instalando dispositivos em sistemas de 64 bits. |
|
O valor especificado para Flags não é igual a zero ou ROLLBACK_FLAG_NO_UI. |
|
Um driver de backup não está definido para o dispositivo. |
Comentários
Se um driver de backup instalado anteriormente estiver definido para um dispositivo, uma reversão de driver para o dispositivo substituirá o driver instalado no dispositivo pelo driver de backup. O Windows mantém no máximo um driver de backup para um dispositivo. O Windows define um driver como o driver de backup de um dispositivo imediatamente depois que o driver é instalado com êxito no dispositivo e o Windows determina que o dispositivo está funcionando corretamente. No entanto, se um driver não for instalado com êxito em um dispositivo ou se o dispositivo não funcionar corretamente após a instalação, o Windows não definirá o driver como o driver de backup do dispositivo. Para obter mais informações sobre a reversão de driver, consulte informações sobre Gerenciador de Dispositivos no Centro de Ajuda e Suporte.
Se o dispositivo especificado tiver um driver de backup, o DiRollbackDriver executará as seguintes operações:
- Se Flags estiver definido como zero, o DiRollbackDriver solicitará que o usuário confirme se o driver de backup deve ser instalado. Caso contrário, se Flags estiver definido como ROLLBACK_FLAG_NO_UI, o DiRollbackDriver instalará o driver de backup sem solicitar que o usuário confirme a instalação do driver de backup.
- O DiRollbackDriver instala o driver de backup. O driver é instalado se o driver de backup é uma correspondência melhor para o dispositivo do que o driver instalado atualmente no dispositivo.
- Se o driver substituído pelo driver de backup não for um driver de caixa de entrada e não estiver instalado em nenhum outro dispositivo no sistema, o DiRollbackDriver removerá o driver do sistema. O DiRollbackDriver remove o driver do sistema porque supõe-se que um usuário substituirá um driver somente se houver um problema com o driver.
Em geral, os aplicativos de instalação devem definir NeedReboot como NULL para que o sistema inicie automaticamente uma reinicialização do sistema se for necessária uma reinicialização para concluir a reversão. Um aplicativo deve fornecer um ponteiro NeedReboot somente nos seguintes casos:
- O aplicativo deve chamar DiRollbackDriver várias vezes para concluir uma instalação. Nesse caso, o aplicativo deve registrar se um valor TRUENeedReboot é retornado por qualquer uma das chamadas para DiRollbackDriver e, nesse caso, solicitar que o usuário reinicie o sistema após o retorno da chamada final para DiRollbackDriver .
- O aplicativo deve executar as operações necessárias, além de chamar DiRollbackDriver, antes que uma reinicialização do sistema ocorra. 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.
Requisitos
| Requisito | Valor |
|---|---|
| Cliente mínimo com suporte | Disponível no Windows Vista 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 |