Функция 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 с пакетом обновления 1 (SP1): Строка ограничена 3072 TCHAR.
[in] dwTimeout
Продолжительность отображения диалогового окна завершения работы в секундах. Пока отображается это диалоговое окно, завершение работы можно остановить с помощью функции AbortSystemShutdown .
Если значение dwTimeout не равно нулю, на указанном компьютере отобразится диалоговое окно InitiateSystemShutdown . В диалоговом окне отображается имя пользователя, вызвавшего функцию, отображается сообщение, указанное параметром lpMessage , и предлагается пользователю выйти из системы. При создании диалогового окна создается звуковой сигнал и он остается на вершине других окон в системе. Диалоговое окно можно переместить, но не закрыть. Таймер отсчитывает оставшееся время до принудительного завершения работы.
Если значение dwTimeout равно нулю, компьютер завершает работу без отображения диалогового окна и завершение работы не может быть остановлено abortSystemShutdown.
Windows Server 2003 и Windows XP с пакетом обновления 1 (SP1): Время ожидания ограничено MAX_SHUTDOWN_TIMEOUT секундами.
Windows Server 2003 и Windows XP с пакетом обновления 1 (SP1): Если компьютер, для которого требуется завершить работу, является сервером служб терминалов, система отображает диалоговое окно для всех локальных и удаленных пользователей с предупреждением о начале завершения работы. В диалоговом окне указывается, кто запросил завершение работы, отображаемое сообщение (см. раздел 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 в качестве псевдонима, который автоматически выбирает версию ANSI или Юникод этой функции на основе определения константы препроцессора ЮНИКОД. Использование псевдонима, не зависящий от кодирования, с кодом, который не является нейтральным для кодировки, может привести к несоответствиям, которые приводят к ошибкам компиляции или времени выполнения. Дополнительные сведения см. в разделе Соглашения для прототипов функций.
Требования
| Минимальная версия клиента | Windows XP [классические приложения | Приложения UWP] |
| Минимальная версия сервера | Windows Server 2003 [классические приложения | Приложения UWP] |
| Целевая платформа | Windows |
| Header | winreg.h (включая Windows.h) |
| Библиотека | Advapi32.lib |
| DLL | Advapi32.dll |