InitiateSystemShutdownA 函数 (winreg.h)

  • 项目

启动指定计算机的关闭和可选重启。

若要在事件日志中记录关闭的原因，请调用 InitiateSystemShutdownEx 函数。

语法

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

参数

[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 不为零， 则 InitiateSystemShutdown 将在指定的计算机上显示一个对话框。 该对话框显示调用函数的用户的名称，显示 由 lpMessage 参数指定的消息，并提示用户注销。 对话框在创建时发出蜂鸣声，并停留在系统中其他窗口的顶部。 对话框可以移动，但不能关闭。 计时器会倒计时强制关闭之前的剩余时间。

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

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

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

[in] bForceAppsClosed

如果此参数为 TRUE，则强制关闭具有未保存更改的应用程序。 请注意，这可能会导致数据丢失。

如果此参数为 FALSE，则系统将显示一个对话框，指示用户关闭应用程序。

[in] bRebootAfterShutdown

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

返回值

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

如果函数失败，则返回值为零。 要获得更多的错误信息，请调用 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 标头将 InitiateSystemShutdown 定义为别名，该别名根据 UNICODE 预处理器常量的定义自动选择此函数的 ANSI 或 Unicode 版本。 将非特定编码别名与非非特定编码的代码混合使用可能会导致不匹配，从而导致编译或运行时错误。 有关详细信息，请参阅 函数原型的约定。

要求

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

另请参阅

AbortSystemShutdown

InitiateSystemShutdownEx

关闭

系统关闭函数