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 应用]
目标平台 Windows
标头 winreg.h (包括 Windows.h)
Library Advapi32.lib
DLL Advapi32.dll

另请参阅

关闭