Função InitiateShutdownA (winreg.h)

Inicia um desligamento e uma reinicialização do computador especificado e reinicia todos os aplicativos que foram registrados para reinicialização.

Sintaxe

DWORD InitiateShutdownA(
  [in, optional] LPSTR lpMachineName,
  [in, optional] LPSTR lpMessage,
  [in]           DWORD dwGracePeriod,
  [in]           DWORD dwShutdownFlags,
  [in]           DWORD dwReason
);

Parâmetros

[in, optional] lpMachineName

O nome do computador a ser desligado. Se o valor desse parâmetro for NULL, o computador local será desligado.

[in, optional] lpMessage

A mensagem a ser exibida na caixa de diálogo de desligamento interativo.

[in] dwGracePeriod

O número de segundos a aguardar antes de desligar o computador. Se o valor desse parâmetro for zero, o computador será desligado imediatamente. Esse valor é limitado a MAX_SHUTDOWN_TIMEOUT.

Se o valor desse parâmetro for maior que zero e o parâmetro dwShutdownFlags especificar o sinalizador SHUTDOWN_GRACE_OVERRIDE, a função falhará e retornará o código de erro ERROR_BAD_ARGUMENTS.

[in] dwShutdownFlags

Um ou mais sinalizadores de bits que especificam opções para o desligamento. Os valores a seguir são definidos.

Valor Significado
SHUTDOWN_FORCE_OTHERS
0x00000001 (0x1)
Todas as sessões são registradas com força. Se esse sinalizador não estiver definido e os usuários diferentes do usuário atual estiverem conectados ao computador especificado pelo parâmetro lpMachineName , essa função falhará com um valor retornado de ERROR_SHUTDOWN_USERS_LOGGED_ON.
SHUTDOWN_FORCE_SELF
0x00000002 (0x2)
Especifica que a sessão de origem é registrada com força. Se esse sinalizador não estiver definido, a sessão de origem será desligada interativamente, portanto, um desligamento não será garantido mesmo se a função retornar com êxito.
SHUTDOWN_GRACE_OVERRIDE
0x00000020 (0x20)
Substitui o período de carência para que o computador seja desligado imediatamente.
SHUTDOWN_HYBRID
0x00000200 (0x200)
Começando com InitiateShutdown em execução no Windows 8, você deve incluir o sinalizador SHUTDOWN_HYBRID com um ou mais sinalizadores nesta tabela para especificar opções para o desligamento.

Começando com Windows 8, InitiateShutdown sempre iniciará um desligamento completo do sistema se o sinalizador SHUTDOWN_HYBRID estiver ausente.

SHUTDOWN_INSTALL_UPDATES
0x00000040 (0x40)
O computador instala todas as atualizações antes de iniciar o desligamento.
SHUTDOWN_NOREBOOT
0x00000010 (0x10)
O computador está desligado, mas não está desligado ou reinicializado.
SHUTDOWN_POWEROFF
0x00000008 (0x8)
O computador está desligado e desligado.
SHUTDOWN_RESTART
0x00000004 (0x4)
O computador é desligado e reinicializado.
SHUTDOWN_RESTARTAPPS
0x00000080 (0x80)
O sistema é reinicializado usando a função ExitWindowsEx com o sinalizador EWX_RESTARTAPPS. Isso reinicia todos os aplicativos que foram registrados para reinicialização usando a função RegisterApplicationRestart .

[in] dwReason

O motivo para iniciar o desligamento. Esse parâmetro deve ser um dos códigos de motivo de desligamento do sistema. Se esse parâmetro for zero, o padrão será um desligamento indefinido registrado como "Nenhum título por esse motivo pode ser encontrado". Por padrão, ele também é um desligamento não planejado. Dependendo de como o sistema é configurado, um desligamento não planejado dispara a criação de um arquivo que contém as informações de estado do sistema, o que pode atrasar o desligamento. Portanto, não use zero para esse parâmetro.

Retornar valor

Se a função for bem-sucedida, ela retornará ERROR_SUCCESS.

Se a função falhar, ela retornará um dos seguintes códigos de erro.

Código de retorno Descrição
ERROR_ACCESS_DENIED
O chamador não tem o privilégio necessário (SE_SHUTDOWN_PRIVILEGE ou SE_REMOTE_SHUTDOWN_PRIVILEGE) para executar essa operação.
ERROR_BAD_NETPATH
O computador especificado não existe ou não está acessível.
ERROR_INVALID_COMPUTERNAME
O nome do computador especificado não é um nome de computador válido.
ERROR_INVALID_FUNCTION
O computador especificado não dá suporte a uma interface de desligamento.
ERROR_INVALID_PARAMETER
Um conjunto inválido de parâmetros foi passado. Isso inclui as combinações a seguir.
  • O parâmetro lpMachineName especifica um computador remoto e o parâmetro dwShutdownFlags não especifica SHUTDOWN_FORCE_SELF.
  • O valor de dwGracePeriod é maior que zero e o parâmetro dwShutdownFlags não especifica SHUTDOWN_FORCE_SELF.
  • O valor de dwGracePeriod é maior que zero e o parâmetro dwShutdownFlags especifica SHUTDOWN_GRACE_OVERRIDE.
ERROR_SHUTDOWN_IN_PROGRESS
Um desligamento já foi iniciado no computador especificado.
ERROR_SHUTDOWN_IS_SCHEDULED
Um desligamento para o computador especificado foi agendado, mas não iniciado. Para que essa função seja bem-sucedida, o sinalizador SHUTDOWN_GRACE_OVERRIDE deve ser definido.
ERROR_SHUTDOWN_USERS_LOGGED_ON
Um ou mais usuários diferentes do usuário atual estão conectados ao computador especificado e o sinalizador SHUTDOWN_FORCE_OTHERS não foi definido.

Comentários

Para desligar o computador local, o thread de chamada deve ter o privilégio SE_SHUTDOWN_NAME. Para desligar um computador remoto, o thread de chamada deve ter o privilégio SE_REMOTE_SHUTDOWN_NAME no computador remoto. Por padrão, os usuários podem habilitar o privilégio SE_SHUTDOWN_NAME no computador no qual estão conectados e os administradores podem habilitar o privilégio SE_REMOTE_SHUTDOWN_NAME em computadores remotos. Para obter mais informações, confira Executar com privilégios especiais.

Os motivos comuns para a falha incluem um nome de computador inválido ou inacessível ou privilégio insuficiente. O erro ERROR_SHUTDOWN_IN_PROGRESS será retornado se um desligamento já estiver em andamento no computador especificado. O erro ERROR_NOT_READY pode ser retornado se a troca rápida de usuário estiver habilitada, mas nenhum usuário estiver conectado.

Um valor retornado diferente de zero não significa que o logoff foi ou será bem-sucedido. O desligamento é um processo assíncrono e pode ocorrer muito depois que a chamada à API for retornada ou não. Mesmo que o valor do tempo limite seja zero, o desligamento ainda poderá ser anulado por aplicativos, serviços ou até mesmo pelo sistema. O valor retornado diferente de zero indica que a validação dos direitos e parâmetros foi bem-sucedida e que o sistema aceitou a solicitação de desligamento.

Observação

O cabeçalho winreg.h define InitiateShutdown como um alias que seleciona automaticamente a versão ANSI ou Unicode dessa função com base na definição da constante de pré-processador UNICODE. Misturar o uso do alias neutro de codificação com código que não seja neutro em codificação pode levar a incompatibilidades que resultam em erros de compilação ou de runtime. Para obter mais informações, consulte Convenções para protótipos de função.

Requisitos

Requisito Valor
Cliente mínimo com suporte Windows Vista [aplicativos da área de trabalho | Aplicativos UWP]
Servidor mínimo com suporte Windows Server 2008 [aplicativos da área de trabalho | Aplicativos UWP]
Plataforma de Destino Windows
Cabeçalho winreg.h (inclua Windows.h)
Biblioteca Advapi32.lib
DLL Advapi32.dll

Confira também

Desligar