Função InitiateShutdownA (winreg.h)
Inicia um desligamento e uma reinicialização do computador especificado e reinicia todos os aplicativos que foram registrados para reinicialização.
Sintaxe
DWORD InitiateShutdownA(
[in, optional] LPSTR lpMachineName,
[in, optional] LPSTR lpMessage,
[in] DWORD dwGracePeriod,
[in] DWORD dwShutdownFlags,
[in] DWORD dwReason
);
Parâmetros
[in, optional] lpMachineName
O nome do computador a ser desligado. Se o valor desse parâmetro for NULL, o computador local será desligado.
[in, optional] lpMessage
A mensagem a ser exibida na caixa de diálogo de desligamento interativo.
[in] dwGracePeriod
O número de segundos a aguardar antes de desligar o computador. Se o valor desse parâmetro for zero, o computador será desligado imediatamente. Esse valor é limitado a MAX_SHUTDOWN_TIMEOUT.
Se o valor desse parâmetro for maior que zero e o parâmetro dwShutdownFlags especificar o sinalizador SHUTDOWN_GRACE_OVERRIDE, a função falhará e retornará o código de erro ERROR_BAD_ARGUMENTS.
[in] dwShutdownFlags
Um ou mais sinalizadores de bits que especificam opções para o desligamento. Os valores a seguir são definidos.
| Valor | Significado |
|---|---|
|
Todas as sessões são registradas com força. Se esse sinalizador não estiver definido e os usuários diferentes do usuário atual estiverem conectados ao computador especificado pelo parâmetro lpMachineName , essa função falhará com um valor retornado de ERROR_SHUTDOWN_USERS_LOGGED_ON. |
|
Especifica que a sessão de origem é registrada com força. Se esse sinalizador não estiver definido, a sessão de origem será desligada interativamente, portanto, um desligamento não será garantido mesmo se a função retornar com êxito. |
|
Substitui o período de carência para que o computador seja desligado imediatamente. |
|
Começando com InitiateShutdown em execução no Windows 8, você deve incluir o sinalizador SHUTDOWN_HYBRID com um ou mais sinalizadores nesta tabela para especificar opções para o desligamento.
Começando com Windows 8, InitiateShutdown sempre iniciará um desligamento completo do sistema se o sinalizador SHUTDOWN_HYBRID estiver ausente. |
|
O computador instala todas as atualizações antes de iniciar o desligamento. |
|
O computador está desligado, mas não está desligado ou reinicializado. |
|
O computador está desligado e desligado. |
|
O computador é desligado e reinicializado. |
|
O sistema é reinicializado usando a função ExitWindowsEx com o sinalizador EWX_RESTARTAPPS. Isso reinicia todos os aplicativos que foram registrados para reinicialização usando a função RegisterApplicationRestart . |
[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.
Retornar valor
Se a função for bem-sucedida, ela retornará ERROR_SUCCESS.
Se a função falhar, ela retornará um dos seguintes códigos de erro.
| Código de retorno | Descrição |
|---|---|
|
O chamador não tem o privilégio necessário (SE_SHUTDOWN_PRIVILEGE ou SE_REMOTE_SHUTDOWN_PRIVILEGE) para executar essa operação. |
|
O computador especificado não existe ou não está acessível. |
|
O nome do computador especificado não é um nome de computador válido. |
|
O computador especificado não dá suporte a uma interface de desligamento. |
|
Um conjunto inválido de parâmetros foi passado. Isso inclui as combinações a seguir.
|
|
Um desligamento já foi iniciado no computador especificado. |
|
Um desligamento para o computador especificado foi agendado, mas não iniciado. Para que essa função seja bem-sucedida, o sinalizador SHUTDOWN_GRACE_OVERRIDE deve ser definido. |
|
Um ou mais usuários diferentes do usuário atual estão conectados ao computador especificado e o sinalizador SHUTDOWN_FORCE_OTHERS não foi definido. |
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.
Observação
O cabeçalho winreg.h define InitiateShutdown 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 Vista [aplicativos da área de trabalho | Aplicativos UWP] |
| Servidor mínimo com suporte | Windows Server 2008 [aplicativos da área de trabalho | Aplicativos UWP] |
| Plataforma de Destino | Windows |
| Cabeçalho | winreg.h (inclua Windows.h) |
| Biblioteca | Advapi32.lib |
| DLL | Advapi32.dll |