Функция InitiateSystemShutdownA (winreg.h)

Статья
11/20/2024

Инициирует завершение работы и необязательный перезапуск указанного компьютера.

Чтобы записать причину завершения работы в журнале событий, вызовите функцию InitiateSystemShutdownEx.

Синтаксис

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

Параметры

[in, optional] lpMachineName

Сетевое имя компьютера для завершения работы. Если lpMachineNameNULL или пустая строка, функция завершает работу локального компьютера.

[in, optional] lpMessage

Сообщение, отображаемое в диалоговом окне завершения работы. Этот параметр может быть null, если сообщение не требуется.

Windows Server 2003 и Windows XP: эта строка также хранится в виде комментария в записи журнала событий.

Windows Server 2003 и Windows XP с пакетом обновления 1 (SP1): строка ограничена 3072 TCHARs.

[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: Если компьютер заблокирован, а параметр bForceAppsClosedFALSE, последний код ошибки ERROR_MACHINE_LOCKED. Если система не готова к обработке запроса, последний код ошибки ERROR_NOT_READY. Приложение должно ждать некоторое время и повторить вызов. Например, система может быть нечитаемой для запуска завершения работы и возврата ERROR_NOT_READY, если запрос на завершение работы происходит в то же время, когда пользователь пытается войти в систему. В этом случае приложение должно ждать некоторое время и повторить вызов.

Примеры

Пример см. в разделе Отображение диалогового окна завершения работы.

Заметка

Заголовок winreg.h определяет InitiateSystemShutdown как псевдоним, который автоматически выбирает версию ANSI или Юникод этой функции на основе определения константы препроцессора ЮНИКОДа. Сочетание использования псевдонима, нейтрального для кодирования, с кодом, не зависящим от кодирования, может привести к несоответствиям, которые приводят к ошибкам компиляции или среды выполнения. Дополнительные сведения см. в соглашениях о прототипах функций.

Требования

Требование	Ценность
минимальные поддерживаемые клиентские	Windows XP [классические приложения \| Приложения UWP]
минимальный поддерживаемый сервер	Windows Server 2003 [классические приложения \| Приложения UWP]
целевая платформа	Виндоус
заголовка	winreg.h (включая Windows.h)
библиотеки	Advapi32.lib
DLL	Advapi32.dll

См. также

AbortSystemShutdown

InitiateSystemShutdownEx

завершение работы

функции завершения работы системы

Поделиться через