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 de 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 3072 TCHARs.
[in] dwTimeout
O período de tempo em 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
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 empõe quando é criada e permanece na parte superior de 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 VERDADEIRO, 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 habilita o sistema com segurança.
Valor de retorno
Se a função for bem-sucedida, o valor retornado não será zero.
Se a função falhar, o valor retornado será zero. Para obter informações de erro estendidas, chame GetLastError.
Observações
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 de SE_SHUTDOWN_NAME no computador no qual estão conectados e os administradores podem habilitar o privilégio de SE_REMOTE_SHUTDOWN_NAME em computadores remotos. Para obter mais informações, consulte Em execução com privilégios especiais.
Os motivos comuns para 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 alternância de usuário rápido 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 tempo depois que a chamada à API tiver retornado 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 VERDADEIRO evita essa situação. Lembre-se de que fazer isso pode resultar em perda de dados.
Exemplos
Para obter um exemplo, consulte Exibindo a caixa de diálogo Desligamento.
Nota
O cabeçalho winreg.h define InitiateSystemShutdown 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. A combinação do uso do alias neutro de codificação com código que não é neutro em codificação pode levar a incompatibilidades que resultam em erros de compilação ou de runtime. Para obter mais informações, consulte Conventions for Function Prototypes.
Requisitos
| Requisito | Valor |
|---|---|
| de cliente com suporte mínimo | Windows XP [aplicativos da área de trabalho | Aplicativos UWP] |
| servidor com suporte mínimo | Windows Server 2003 [aplicativos da área de trabalho | Aplicativos UWP] |
| da Plataforma de Destino |
Windows |
| cabeçalho | winreg.h (inclua Windows.h) |
| biblioteca | Advapi32.lib |
| de DLL |
Advapi32.dll |