Функция 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 |