Compartilhar via


Função InitiateSystemShutdownExW (winreg.h)

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

Sintaxe

BOOL InitiateSystemShutdownExW(
  [in, optional] LPWSTR lpMachineName,
  [in, optional] LPWSTR 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

Consulte também

AbortSystemShutdown

desligando

Funções de desligamento do sistema