Функция обратного вызова HandlerRoutine

Статья
07/12/2023

Определяемая приложением функция, используемая с функцией SetConsoleCtrlHandler. Консольный процесс использует эту функцию для обработки сигналов управления, полученных процессом. При получении сигнала система создает новый поток в процессе для выполнения функции.

Тип PHANDLER_ROUTINE определяет указатель на эту функцию обратного вызова. HandlerRoutine — это заполнитель для имени определяемой приложением функции.

Синтаксис

BOOL WINAPI HandlerRoutine(
  _In_ DWORD dwCtrlType
);

Параметры

dwCtrlType [in]
Тип сигнала элемента управления, полученного обработчиком. Этот параметр может принимать одно из указанных ниже значений.

Значение	Значение
CTRL_C_EVENT 0	`Сигнал CTRL+C` был получен из ввода клавиатуры или сигнала, созданного функцией GenerateConsoleCtrlEvent.
CTRL_BREAK_EVENT 1	`Сигнал CTRL+BREAK` был получен из ввода клавиатуры или сигнала, созданного GenerateConsoleCtrlEvent.
CTRL_CLOSE_EVENT 2	Сигнал о том, что система отправляет все процессы, подключенные к консоли, когда пользователь закрывает консоль (нажав кнопку "Закрыть" в меню окна консоли или нажав кнопку "Завершить задачу" из диспетчера задач).
CTRL_LOGOFF_EVENT 5	Сигнал о том, что система отправляется во все процессы консоли при выходе пользователя из системы. Этот сигнал не указывает, какой пользователь отключается, поэтому никаких предположений не может быть сделано. Обратите внимание, что этот сигнал получается только службами. Интерактивные приложения завершаются при выходе, поэтому они не присутствуют, когда система отправляет этот сигнал.
CTRL_SHUTDOWN_EVENT 6	Сигнал о том, что система отправляется при завершении работы системы. Интерактивные приложения отсутствуют к тому времени, когда система отправляет этот сигнал, поэтому она может быть получена только службами в этой ситуации. Службы также имеют собственный механизм уведомлений для событий завершения работы. Дополнительные сведения см. в разделе "Обработчик".

Возвращаемое значение

Если функция обрабатывает сигнал управления, она должна вернуть значение TRUE. Если возвращает значение FALSE, используется следующая функция обработчика в списке обработчиков для этого процесса.

Замечания

Так как система создает новый поток в процессе для выполнения функции обработчика, возможно, что функция обработчика будет завершена другим потоком в процессе. Не забудьте синхронизировать потоки в процессе с потоком для функции обработчика.

Каждый процесс консоли имеет собственный список функций HandlerRoutine . Изначально этот список содержит только функцию обработчика по умолчанию, которая вызывает ExitProcess. Процесс консоли добавляет или удаляет дополнительные функции обработчика, вызывая функцию SetConsoleCtrlHandler, которая не влияет на список функций обработчика для других процессов. Когда консольный процесс получает любой из сигналов управления, его функции-обработчики вызываются на последней зарегистрированной основе до тех пор, пока один из обработчиков не возвращает TRUE. Если ни один из обработчиков не возвращает значение TRUE, вызывается обработчик по умолчанию.

Сигналы CTRL_CLOSE_EVENT, CTRL_LOGOFF_EVENT и CTRL_SHUTDOWN_EVENT дают процессу возможность очистки перед завершением работы. ОбработчикRoutine может выполнить любую необходимую очистку, а затем выполнить одно из следующих действий:

Вызовите функцию ExitProcess, чтобы завершить процесс.
Возвращает значение FALSE. Если ни одна из зарегистрированных функций обработчика не возвращает значение TRUE, обработчик по умолчанию завершает процесс.
Возвращает значение TRUE. В этом случае другие функции обработчика не вызываются, и система завершает процесс.

Процесс может использовать функцию SetProcessShutdownParameters , чтобы система не отображала диалоговое окно пользователю во время выхода или завершения работы. В этом случае система завершает процесс, когда HandlerRoutine возвращает ЗНАЧЕНИЕ TRUE или когда истекает период ожидания.

При запуске консольного приложения в качестве службы он получает измененный обработчик управления консолью по умолчанию. Этот измененный обработчик не вызывает ExitProcess при обработке сигналов CTRL_LOGOFF_EVENT и CTRL_SHUTDOWN_EVENT. Это позволяет службе продолжать работу после выхода пользователя. Если служба устанавливает собственный обработчик управления консолью, этот обработчик вызывается перед обработчиком по умолчанию. Если установленный обработчик вызывает ExitProcess при обработке сигнала CTRL_LOGOFF_EVENT , служба завершает работу при выходе пользователя из системы.

Обратите внимание, что сторонние библиотеки или библиотеки DLL могут устанавливать обработчик консоли для приложения. В противном случае этот обработчик переопределяет обработчик по умолчанию и может привести к выходу приложения при выходе пользователя из системы.

Время ожидания

Событие	Обстоятельствах	Время ожидания
`CTRL_CLOSE_EVENT`	любой	системный параметр `SPI_GETHUNGAPPTIMEOUT`, 5000 мс
`CTRL_LOGOFF_EVENT`	quick[1]	Раздел `CriticalAppShutdownTimeout` реестра или 500 мс
`CTRL_LOGOFF_EVENT`	ни один из указанных выше	системный параметр `SPI_GETWAITTOKILLTIMEOUT`, 5000 мс
`CTRL_SHUTDOWN_EVENT`	Процесс обслуживания	системный параметр `SPI_GETWAITTOKILLSERVICETIMEOUT`, 20000 мс
`CTRL_SHUTDOWN_EVENT`	quick[1]	Раздел `CriticalAppShutdownTimeout` реестра или 500 мс
`CTRL_SHUTDOWN_EVENT`	ни один из указанных выше	системный параметр `SPI_GETWAITTOKILLTIMEOUT`, 5000 мс
`CTRL_C`, `CTRL_BREAK`	любой	не истекло время ожидания

[1]: "быстрые" события никогда не используются, но есть код для их поддержки.

Требования


Минимальная версия клиента	Windows 2000 Professional [только классические приложения]
Минимальная версия сервера	Windows 2000 Server [только классические приложения]
Верхний колонтитул	ConsoleApi.h (через WinCon.h, включая Windows.h)