通过

InitiateShutdownA 函数 （winreg.h）

  • 项目

启动指定计算机的关闭和重启，并重启已注册重启的任何应用程序。

语法

DWORD InitiateShutdownA(
  [in, optional] LPSTR lpMachineName,
  [in, optional] LPSTR lpMessage,
  [in]           DWORD dwGracePeriod,
  [in]           DWORD dwShutdownFlags,
  [in]           DWORD dwReason
);

参数

[in, optional] lpMachineName

要关闭的计算机的名称。 如果此参数的值 NULL，则关闭本地计算机。

[in, optional] lpMessage

要显示在交互式关闭对话框中的消息。

[in] dwGracePeriod

关闭计算机之前等待的秒数。 如果此参数的值为零，则计算机将立即关闭。 此值限制为 MAX_SHUTDOWN_TIMEOUT。

如果此参数的值大于零，并且 dwShutdownFlags 参数指定标志 SHUTDOWN_GRACE_OVERRIDE，则函数将失败并返回错误代码 ERROR_BAD_ARGUMENTS。

[in] dwShutdownFlags

指定关闭选项的一个或多个位标志。 定义了以下值。

价值 意义
SHUTDOWN_FORCE_OTHERS
0x00000001（0x1）
 所有会话都会强制注销。 如果未设置此标志，并且当前用户以外的用户登录到由 lpMachineName 参数指定的计算机，则此函数将失败，返回值 ERROR_SHUTDOWN_USERS_LOGGED_ON。
SHUTDOWN_FORCE_SELF
0x00000002（0x2）
 指定原始会话已强制注销。 如果未设置此标志，则原始会话以交互方式关闭，因此即使函数成功返回，也不能保证关闭。
SHUTDOWN_GRACE_OVERRIDE
0x00000020（0x20）
 重写宽限期，以便计算机立即关闭。
SHUTDOWN_HYBRID
0x00000200（0x200）
 从 Windows 8 上运行的 InitiateShutdown 开始，必须在此表中包含一个或多个标志的 SHUTDOWN_HYBRID 标志，以指定关闭选项。

从 Windows 8 开始，如果缺少 SHUTDOWN_HYBRID 标志，InitiateShutdown 始终启动完整的系统关闭。
SHUTDOWN_INSTALL_UPDATES
0x00000040（0x40）
 计算机在启动关闭之前安装任何更新。
SHUTDOWN_NOREBOOT
0x00000010（0x10）
 计算机已关闭，但未关闭或重新启动。
SHUTDOWN_POWEROFF
0x00000008（0x8）
 计算机已关闭并关闭。
SHUTDOWN_RESTART
0x00000004（0x4）
 计算机已关闭并重新启动。
SHUTDOWN_RESTARTAPPS
0x00000080（0x80）
 系统使用具有EWX_RESTARTAPPS标志的 ExitWindowsEx 函数重新启动。 这会使用 RegisterApplicationRestart 函数重启已注册的任何应用程序重启。

[in] dwReason

启动关闭的原因。 此参数必须是系统关闭原因代码之一。 如果此参数为零，则默认值为未定义的关闭，该关闭记录为“找不到此原因的标题”。 默认情况下，它也是计划外关闭。 根据系统的配置方式，计划外关闭会触发创建包含系统状态信息的文件，该文件可能会延迟关闭。 因此，不要对此参数使用零。

返回值

如果函数成功，则返回 ERROR_SUCCESS。

如果函数失败，它将返回以下错误代码之一。

返回代码 描述
ERROR_ACCESS_DENIED
 调用方没有执行此操作所需的权限（SE_SHUTDOWN_PRIVILEGE或SE_REMOTE_SHUTDOWN_PRIVILEGE）。
ERROR_BAD_NETPATH
 指定的计算机不存在或不可访问。
ERROR_INVALID_COMPUTERNAME
 指定的计算机名称不是有效的计算机名称。
ERROR_INVALID_FUNCTION
 指定的计算机不支持关闭接口。
ERROR_INVALID_PARAMETER
 传递了无效的参数集。 这包括以下组合。
  • lpMachineName 参数指定远程计算机，dwShutdownFlags 参数未指定 SHUTDOWN_FORCE_SELF。
  • dwGracePeriod 的值大于零，dwShutdownFlags 参数未指定 SHUTDOWN_FORCE_SELF。
  • dwGracePeriod 的值大于零，dwShutdownFlags 参数指定 SHUTDOWN_GRACE_OVERRIDE。
ERROR_SHUTDOWN_IN_PROGRESS
 已在指定计算机上启动关闭。
ERROR_SHUTDOWN_IS_SCHEDULED
 已计划指定计算机的关闭，但未启动。 要使此函数成功，必须设置 SHUTDOWN_GRACE_OVERRIDE 标志。
ERROR_SHUTDOWN_USERS_LOGGED_ON
 与当前用户以外的一个或多个用户记录在指定的计算机上，并且未设置 SHUTDOWN_FORCE_OTHERS 标志。

言论

若要关闭本地计算机，调用线程必须具有SE_SHUTDOWN_NAME权限。 若要关闭远程计算机，调用线程必须在远程计算机上具有SE_REMOTE_SHUTDOWN_NAME权限。 默认情况下，用户可以在登录的计算机上启用SE_SHUTDOWN_NAME特权，管理员可以在远程计算机上启用SE_REMOTE_SHUTDOWN_NAME特权。 有关详细信息，请参阅 使用特殊特权运行。

失败的常见原因包括无效或无法访问的计算机名称或权限不足。 如果在指定计算机上正在进行关闭，则返回错误ERROR_SHUTDOWN_IN_PROGRESS。 如果启用了快速用户切换，但未登录用户，则可以返回错误ERROR_NOT_READY。

非零返回值并不意味着注销是还是会成功。 关闭是一个异步进程，在 API 调用返回或根本不返回之后，它可能会发生。 即使超时值为零，关闭仍可由应用程序、服务甚至系统中止。 非零返回值指示权限和参数的验证成功，并且系统已接受关闭请求。

注意

winreg.h 标头将 InitiateShutdown 定义为一个别名，该别名根据 UNICODE 预处理器常量的定义自动选择此函数的 ANSI 或 Unicode 版本。 将中性编码别名与不中性编码的代码混合使用可能会导致编译或运行时错误不匹配。 有关详细信息，请参阅函数原型的 约定。

要求

要求 价值
最低支持的客户端 Windows Vista [桌面应用 |UWP 应用]
支持的最低服务器 Windows Server 2008 [桌面应用 |UWP 应用]
目标平台 窗户
标头 winreg.h （包括 Windows.h）
库 Advapi32.lib
DLL Advapi32.dll

另请参阅

关闭