Função InitiateSystemShutdownA (winreg.h)

Inicia um desligamento e uma reinicialização opcional do computador especificado.

Para registrar um motivo para o desligamento no log de eventos, chame a função InitiateSystemShutdownEx .

Sintaxe

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

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, InitiateSystemShutdown 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 de um desligamento forçado.

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. Observe que isso pode resultar em perda de dados.

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.

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 esses aplicativos fechados 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.

Exemplos

Para obter um exemplo, consulte Exibindo a caixa de diálogo Desligamento.

Requisitos

Confira também

AbortSystemShutdown

InitiateSystemShutdownEx

Desligar

Funções de desligamento do sistema