启动SystemShutdownExA 函数 (winreg.h)

  • 项目

启动指定计算机的关闭和可选重启，并选择性地记录关闭原因。

语法

BOOL InitiateSystemShutdownExA(
  [in, optional] LPSTR lpMachineName,
  [in, optional] LPSTR lpMessage,
  [in]           DWORD dwTimeout,
  [in]           BOOL  bForceAppsClosed,
  [in]           BOOL  bRebootAfterShutdown,
  [in]           DWORD dwReason
);

参数

[in, optional] lpMachineName

要关闭的计算机的网络名称。 如果 lpMachineName 为 NULL 或空字符串，则该函数将关闭本地计算机。

[in, optional] lpMessage

要显示在关闭对话框中的消息。 如果不需要消息，此参数可以为 NULL 。

Windows Server 2003 和 Windows XP： 此字符串还作为注释存储在事件日志条目中。

Windows Server 2003 和 Windows XP SP1： 字符串限制为 3072 TCHAR。

[in] dwTimeout

关闭对话框应显示的时间长度（以秒为单位）。 显示此对话框时， AbortSystemShutdown 函数可以停止关闭。

如果 dwTimeout 不为零， 则 InitiateSystemShutdownEx 会在指定计算机上显示一个对话框。 该对话框显示调用函数的用户的名称，显示 lpMessage 参数指定的消息，并提示用户注销。 对话框在创建时发出哔哔声，并保留在系统中其他窗口的顶部。 对话框可以移动，但不能关闭。 计时器倒计时关闭前的剩余时间。

如果 dwTimeout 为零，则计算机关闭而不显示对话框，并且 AbortSystemShutdown 无法停止关闭。

Windows Server 2003 和 Windows XP SP1： 超时值限制为 MAX_SHUTDOWN_TIMEOUT 秒。

Windows Server 2003 和 Windows XP SP1： 如果要关闭的计算机是终端服务服务器，系统会向所有本地和远程用户显示一个对话框，警告他们已启动关闭。 对话框包括请求关闭的人员、显示消息 (看到 lpMessage) ，以及服务器关闭之前的时长。

[in] bForceAppsClosed

如果此参数为 TRUE，则会强行关闭具有未保存更改的应用程序。 如果此参数为 FALSE，则系统将显示一个对话框，指示用户关闭应用程序。

[in] bRebootAfterShutdown

如果此参数为 TRUE，则计算机在关闭后立即重启。 如果此参数为 FALSE，则系统会将所有缓存刷新到磁盘，并安全地关闭系统。

[in] dwReason

启动关闭的原因。 此参数必须是 系统关闭原因代码之一。

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

Windowsxp： 在计划外系统关闭期间，系统状态信息不会保存。 上述文本不适用。

返回值

如果该函数成功，则返回值为非零值。

如果函数失败，则返回值为零。 要获得更多的错误信息，请调用 GetLastError。

注解

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

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

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

调用此函数时，调用方必须指定是否应强行关闭具有未保存更改的应用程序。 如果调用方选择不强制关闭这些应用程序，并且具有未保存更改的应用程序在控制台会话上运行，则关闭将一直进行，直到登录到控制台会话的用户中止关闭、保存更改、关闭应用程序或强制关闭应用程序。 在此期间，除主机用户外，关闭可能不会中止，并且可能不会启动另一次关闭。

请注意，使用 bForceAppsClosed 参数的值设置为 TRUE 调用此函数可避免这种情况。 请记住，执行此操作可能会导致数据丢失。

Windows Server 2003 和 Windows XP： 如果计算机已锁定，并且 bForceAppsClosed 参数为 FALSE，则最后一个错误代码ERROR_MACHINE_LOCKED。 如果系统尚未准备好处理请求，则会ERROR_NOT_READY最后一个错误代码。 应用程序应稍等片刻，然后重试调用。 例如，如果用户尝试登录到系统时同时发出关闭请求，则系统可能未了解启动关闭并返回ERROR_NOT_READY。 在这种情况下，应用程序应稍等片刻，然后重试调用。

注意

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

要求

要求 值
最低受支持的客户端 Windows XP [桌面应用 | UWP 应用]
最低受支持的服务器 Windows Server 2003 [桌面应用 | UWP 应用]
目标平台 Windows
标头 winreg.h (包括 Windows.h)
Library Advapi32.lib
DLL Advapi32.dll

另请参阅

AbortSystemShutdown

关闭

系统关闭函数