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