Функция 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)
 Начиная с запуска InitiateShutdown в Windows 8, необходимо включить флаг SHUTDOWN_HYBRID с одним или несколькими флагами в этой таблице, чтобы указать параметры завершения работы.

Начиная с Windows 8, InitiateShutdown всегда инициирует полное завершение работы системы, если флаг SHUTDOWN_HYBRID отсутствует.
SHUTDOWN_INSTALL_UPDATES
0x00000040 (0x40)
 Компьютер устанавливает все обновления перед началом завершения работы.
SHUTDOWN_NOREBOOT
0x00000010 (0x10)
 Компьютер завершает работу, но не выключается или не перезагружается.
SHUTDOWN_POWEROFF
0x00000008 (0x8)
 Компьютер выключен и выключен.
SHUTDOWN_RESTART
0x00000004 (0x4)
 Компьютер завершает работу и перезагружается.
SHUTDOWN_RESTARTAPPS
0x00000080 (0x80)
 Система перезагружается с помощью функции ExitWindowsEx с флагом EWX_RESTARTAPPS. При этом будут перезапущены все приложения, которые были зарегистрированы для перезапуска с помощью функции 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 как псевдоним, который автоматически выбирает версию ANSI или Юникод этой функции на основе определения константы препроцессора UNICODE. Сочетание использования псевдонима, не зависящий от кодировки, с кодом, не зависящим от кодировки, может привести к несоответствиям, которые приводят к ошибкам компиляции или среды выполнения. Дополнительные сведения см. в разделе Соглашения для прототипов функций.

Требования

Требование Значение
Минимальная версия клиента Windows Vista [классические приложения | Приложения UWP]
Минимальная версия сервера Windows Server 2008 [классические приложения | Приложения UWP]
Целевая платформа Windows
Header winreg.h (включая Windows.h)
Библиотека Advapi32.lib
DLL Advapi32.dll

См. также раздел

Завершает работу