LPHANDLER_FUNCTION función de devolución de llamada (winsvc.h)

Artículo
03/13/2024

Una función de devolución de llamada definida por la aplicación que se usa con la función RegisterServiceCtrlHandler . Un programa de servicio puede usarlo como función de controlador de control de un servicio determinado.

El tipo LPHANDLER_FUNCTION define un puntero a esta función. Handler es un marcador de posición para el nombre definido por la aplicación.

Esta función se ha reemplazado por la función de controlador de control HandlerEx usada con la función RegisterServiceCtrlHandlerEx . Un servicio puede usar cualquiera de los controladores de control, pero el nuevo controlador de control admite datos de contexto definidos por el usuario y códigos de control extendidos adicionales.

Sintaxis

LPHANDLER_FUNCTION LphandlerFunction;

void LphandlerFunction(
  DWORD dwControl
)
{...}

Parámetros

dwControl

Valor devuelto

None

Observaciones

Cuando se inicia un servicio, su función ServiceMain debe llamar inmediatamente a la función RegisterServiceCtrlHandler para especificar una función handler para procesar las solicitudes de control.

El distribuidor de controles del subproceso principal de un proceso de servicio invoca la función de controlador de control para el servicio especificado cada vez que recibe una solicitud de control del administrador de controles de servicio. Después de procesar la solicitud de control, el controlador de control debe llamar a la función SetServiceStatus si el estado del servicio cambia para notificar su nuevo estado al administrador de controles de servicio.

La función de controlador de control está pensada para recibir notificaciones y devolverse inmediatamente. La función de devolución de llamada debe guardar sus parámetros y crear otros subprocesos para realizar un trabajo adicional. (La aplicación debe asegurarse de que estos subprocesos se hayan salido antes de detener el servicio). En concreto, un controlador de control debe evitar operaciones que puedan bloquearse, como tomar un bloqueo, ya que esto podría provocar un interbloqueo o hacer que el sistema deje de responder.

Cuando el administrador de controles de servicio envía un código de control a un servicio, espera a que la función de controlador devuelva antes de enviar códigos de control adicionales a otros servicios. El controlador de control debe devolver lo antes posible; si no devuelve en un plazo de 30 segundos, el SCM devuelve un error. Si un servicio debe realizar un procesamiento prolongado cuando el servicio ejecuta el controlador de control, debe crear un subproceso secundario para realizar el procesamiento largo y, a continuación, volver del controlador de control. Esto evita que el servicio se enrede el distribuidor de control y bloquee otros servicios para recibir códigos de control.

Los servicios que deben limpiar absolutamente durante el apagado solo deben procesar el código de control de SERVICE_CONTROL_SHUTDOWN , ya que hay un tiempo limitado (aproximadamente 20 segundos) disponible para el apagado del servicio. Después de que expire este tiempo, el apagado del sistema continúa independientemente de si se ha completado el apagado del servicio. Tenga en cuenta que si el sistema se deja en estado de apagado (no reiniciado o apagado), el servicio continúa ejecutándose. Si el servicio se registra para aceptar SERVICE_CONTROL_SHUTDOWN, debe controlar el código de control y detenerlo de forma oportuna. De lo contrario, el servicio puede aumentar el tiempo necesario para apagar el sistema, ya que el sistema debe esperar toda la cantidad de tiempo permitido para el apagado del servicio antes de que el apagado del sistema pueda continuar.

Si el servicio requiere más tiempo para limpiarlo, debe enviar STOP_PENDING mensajes de estado, junto con una sugerencia de espera, por lo que el controlador de servicio sabe cuánto tiempo esperar antes de notificar al sistema que se ha completado el apagado del servicio. Sin embargo, para evitar que un servicio detenga el apagado, hay un límite durante cuánto tiempo esperará el controlador de servicio. Si el servicio se está cerrando a través del complemento Servicios, el límite es de 125 segundos. Si el sistema operativo se está reiniciando, el límite de tiempo se especifica en el valor WaitToKillServiceTimeout de la siguiente clave del Registro:

HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control

Los servicios también pueden usar la función SetConsoleCtrlHandler para recibir una notificación de apagado. Esta notificación se recibe cuando se cierran las aplicaciones en ejecución, que se producen antes de que se apaguen los servicios.

Ejemplos

Para obtener un ejemplo, vea Escribir una función de controlador de control.

Requisitos

Requisito	Value
Cliente mínimo compatible	Windows XP [solo aplicaciones de escritorio]
Servidor mínimo compatible	Windows Server 2003 [solo aplicaciones de escritorio]
Plataforma de destino	Windows
Encabezado	winsvc.h (incluye Windows.h)