Função InitiateSystemShutdownExA (winreg.h)

Inicia um desligamento e uma reinicialização opcional do computador especificado e, opcionalmente, registra o motivo do desligamento.

Sintaxe

BOOL InitiateSystemShutdownExA(
  [in, optional] LPSTR lpMachineName,
  [in, optional] LPSTR lpMessage,
  [in]           DWORD dwTimeout,
  [in]           BOOL  bForceAppsClosed,
  [in]           BOOL  bRebootAfterShutdown,
  [in]           DWORD dwReason
);

Parâmetros

[in, optional] lpMachineName

O nome da rede do computador a ser desligado. Se lpMachineName for NULL ou uma cadeia de caracteres vazia, a função desligará o computador local.

[in, optional] lpMessage

A mensagem a ser exibida na caixa de diálogo desligamento. Esse parâmetro poderá ser NULL se nenhuma mensagem for necessária.

Windows Server 2003 e Windows XP: Essa cadeia de caracteres também é armazenada como um comentário na entrada do log de eventos.

Windows Server 2003 e Windows XP com SP1: A cadeia de caracteres é limitada a 3.072 TCHARs.

[in] dwTimeout

O período de tempo que a caixa de diálogo de desligamento deve ser exibida, em segundos. Enquanto essa caixa de diálogo é exibida, o desligamento pode ser interrompido pela função AbortSystemShutdown .

Se dwTimeout não for zero, InitiateSystemShutdownEx exibirá uma caixa de diálogo no computador especificado. A caixa de diálogo exibe o nome do usuário que chamou a função, exibe a mensagem especificada pelo parâmetro lpMessage e solicita que o usuário faça logoff. A caixa de diálogo emite um bipe quando é criada e permanece sobre outras janelas do sistema. A caixa de diálogo pode ser movida, mas não fechada. Um temporizador conta o tempo restante antes do desligamento.

Se dwTimeout for zero, o computador será desligado sem exibir a caixa de diálogo e o desligamento não poderá ser interrompido por AbortSystemShutdown.

Windows Server 2003 e Windows XP com SP1: O valor de tempo limite é limitado a MAX_SHUTDOWN_TIMEOUT segundos.

Windows Server 2003 e Windows XP com SP1: Se o computador a ser desligado for um servidor dos Serviços de Terminal, o sistema exibirá uma caixa de diálogo para todos os usuários locais e remotos avisando que o desligamento foi iniciado. A caixa de diálogo inclui quem solicitou o desligamento, a mensagem de exibição ( consulte lpMessage) e quanto tempo há até que o servidor seja desligado.

[in] bForceAppsClosed

Se esse parâmetro for TRUE, os aplicativos com alterações não salvas deverão ser fechados à força. Se esse parâmetro for FALSE, o sistema exibirá uma caixa de diálogo instruindo o usuário a fechar os aplicativos.

[in] bRebootAfterShutdown

Se esse parâmetro for TRUE, o computador será reiniciado imediatamente após o desligamento. Se esse parâmetro for FALSE, o sistema liberará todos os caches para o disco e desligará o sistema com segurança.

[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.

Windows XP: As informações de estado do sistema não são salvas durante um desligamento do sistema não planejado. O texto anterior não se aplica.

Valor retornado

Se a função for bem-sucedida, o valor retornado será diferente de zero.

Se a função falhar, o valor retornado será zero. Para obter informações de erro estendidas, chame GetLastError.

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.

Quando essa função é chamada, o chamador deve especificar se os aplicativos com alterações não salvas devem ou não ser fechados à força. Se o chamador optar por não forçar o fechamento desses aplicativos e um aplicativo com alterações não salvas estiver em execução na sessão do console, o desligamento permanecerá em andamento até que o usuário conectado à sessão do console anule o desligamento, salve as alterações, feche o aplicativo ou force o aplicativo a fechar. Durante esse período, o desligamento pode não ser anulado, exceto pelo usuário do console, e outro desligamento pode não ser iniciado.

Observe que chamar essa função com o valor do parâmetro bForceAppsClosed definido como TRUE evita essa situação. Lembre-se de que fazer isso pode resultar em perda de dados.

Windows Server 2003 e Windows XP: Se o computador estiver bloqueado e o parâmetro bForceAppsClosed for FALSE, o último código de erro será ERROR_MACHINE_LOCKED. Se o sistema não estiver pronto para lidar com a solicitação, o último código de erro será ERROR_NOT_READY. O aplicativo deve aguardar um pouco e tentar novamente a chamada. Por exemplo, o sistema pode ser despreparado para iniciar um desligamento e retornar ERROR_NOT_READY, se a solicitação de desligamento vier ao mesmo tempo em que um usuário tentar fazer logon no sistema. Nesse caso, o aplicativo deve aguardar um pouco e repetir a chamada.

Observação

O cabeçalho winreg.h define InitiateSystemShutdownEx 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 XP [aplicativos da área de trabalho | aplicativos UWP]
Servidor mínimo com suporte	Windows Server 2003 [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

AbortSystemShutdown

Desligar

Funções de desligamento do sistema