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 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 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 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 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 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.
[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 poderá ser encontrado". Por padrão, também é um desligamento não planejado. Dependendo de como o sistema está 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 não planejado do sistema. O texto anterior não se aplica.
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 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 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 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.
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 repetir 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 tenta fazer logon no sistema. Nesse caso, o aplicativo deve aguardar um pouco e repetir a chamada.
Nota
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 do 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 |