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

Artículo
08/27/2023

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

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

Esta función sustituye a la función de controlador de control handler usada con la función RegisterServiceCtrlHandler . 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_EX LphandlerFunctionEx;

DWORD LphandlerFunctionEx(
  [in] DWORD dwControl,
  [in] DWORD dwEventType,
  [in] LPVOID lpEventData,
  [in] LPVOID lpContext
)
{...}

Parámetros

[in] dwControl

Código de control. Este parámetro puede ser uno de los valores siguientes.

Código de control	Significado
SERVICE_CONTROL_CONTINUE 0x00000003	Notifica a un servicio en pausa que debe reanudarse.
SERVICE_CONTROL_INTERROGATE 0x00000004	Notifica a un servicio que notifique su información de estado actual al administrador de control de servicios. El controlador simplemente debe devolver NO_ERROR; el SCM es consciente del estado actual del servicio.
SERVICE_CONTROL_NETBINDADD 0x00000007	Notifica a un servicio de red que hay un nuevo componente para el enlace. El servicio debe enlazarse al nuevo componente. Las aplicaciones deben usar Plug and Play funcionalidad en su lugar.
SERVICE_CONTROL_NETBINDDISABLE 0x0000000A	Notifica a un servicio de red que se ha deshabilitado uno de sus enlaces. El servicio debe volver a leer su información de enlace y quitar el enlace. Las aplicaciones deben usar Plug and Play funcionalidad en su lugar.
SERVICE_CONTROL_NETBINDENABLE 0x00000009	Notifica a un servicio de red que se ha habilitado un enlace deshabilitado. El servicio debe volver a leer su información de enlace y agregar el nuevo enlace. Las aplicaciones deben usar Plug and Play funcionalidad en su lugar.
SERVICE_CONTROL_NETBINDREMOVE 0x00000008	Notifica a un servicio de red que se ha quitado un componente para el enlace. El servicio debe volver a leer su información de enlace y desenlace del componente quitado. Las aplicaciones deben usar Plug and Play funcionalidad en su lugar.
SERVICE_CONTROL_PARAMCHANGE 0x00000006	Notifica a un servicio que han cambiado los parámetros de inicio específicos del servicio. El servicio debe volver a leer sus parámetros de inicio.
SERVICE_CONTROL_PAUSE 0x00000002	Notifica a un servicio que debe pausar.
SERVICE_CONTROL_PRESHUTDOWN 0x0000000F	Notifica a un servicio que el sistema se apagará. Los servicios que necesitan tiempo adicional para realizar tareas de limpieza más allá de la restricción de tiempo ajustada en el apagado del sistema pueden usar esta notificación. El administrador de control de servicios envía esta notificación a las aplicaciones que se han registrado para ella antes de enviar una notificación de SERVICE_CONTROL_SHUTDOWN a las aplicaciones que se han registrado para esa notificación. Un servicio que controla esta notificación bloquea el apagado del sistema hasta que el servicio se detiene o el intervalo de tiempo de espera previo especificado a través de SERVICE_PRESHUTDOWN_INFO expira. Dado que esto afecta a la experiencia del usuario, los servicios solo deben usar esta característica si es absolutamente necesario evitar la pérdida de datos o un tiempo de recuperación significativo en el siguiente inicio del sistema. Windows Server 2003 y Windows XP: Este valor no se admite.
SERVICE_CONTROL_SHUTDOWN 0x00000005	Notifica a un servicio que el sistema está apagando para que el servicio pueda realizar tareas de limpieza. Tenga en cuenta que los servicios que se registran para SERVICE_CONTROL_PRESHUTDOWN notificaciones no pueden recibir esta notificación porque ya se han detenido. Si un servicio acepta este código de control, debe detenerse después de realizar sus tareas de limpieza y devolver NO_ERROR. Después de que el SCM envíe este código de control, no enviará otros códigos de control al servicio. Para obtener más información, vea la sección Comentarios.
SERVICE_CONTROL_STOP 0x00000001	Notifica a un servicio que se debe detener. Si un servicio acepta este código de control, debe detenerse al recibir y devolver NO_ERROR. Después de que el SCM envíe este código de control, no enviará otros códigos de control al servicio. Windows XP: Si el servicio devuelve NO_ERROR y continúa ejecutándose, continúa recibiendo códigos de control. Este comportamiento cambió a partir de Windows Server 2003 y Windows XP con SP2.

Este parámetro también puede ser uno de los siguientes códigos de control extendidos. Tenga en cuenta que estos códigos de control no son compatibles con la función Handler .

Código de control	Significado
SERVICE_CONTROL_DEVICEEVENT 0x0000000B	Notifica a un servicio de eventos de dispositivo. (El servicio debe haberse registrado para recibir estas notificaciones mediante la función RegisterDeviceNotification ). Los parámetros dwEventType y lpEventData contienen información adicional.
SERVICE_CONTROL_HARDWAREPROFILECHANGE 0x0000000C	Notifica a un servicio que ha cambiado el perfil de hardware del equipo. El parámetro dwEventType contiene información adicional.
SERVICE_CONTROL_POWEREVENT 0x0000000D	Notifica a un servicio de eventos de alimentación del sistema. El parámetro dwEventType contiene información adicional. Si dwEventType está PBT_POWERSETTINGCHANGE, el parámetro lpEventData también contiene información adicional.
SERVICE_CONTROL_SESSIONCHANGE 0x0000000E	Notifica a un servicio de eventos de cambio de sesión. Tenga en cuenta que un servicio solo recibirá una notificación de inicio de sesión de usuario si se carga por completo antes de que se realice el intento de inicio de sesión. Los parámetros dwEventType y lpEventData contienen información adicional.
SERVICE_CONTROL_TIMECHANGE 0x00000010	Notifica a un servicio que ha cambiado la hora del sistema. El parámetro lpEventData contiene información adicional. No se usa el parámetro dwEventType . Windows Server 2008, Windows Vista, Windows Server 2003 y Windows XP: Este código de control no se admite.
SERVICE_CONTROL_TRIGGEREVENT 0x00000020	Notifica a un servicio registrado para un evento de desencadenador de servicio que se ha producido el evento. Windows Server 2008, Windows Vista, Windows Server 2003 y Windows XP: Este código de control no se admite.
SERVICE_CONTROL_USERMODEREBOOT 0x00000040	Notifica a un servicio que el usuario ha iniciado un reinicio. Windows Server 2008 R2, Windows 7, Windows Server 2008, Windows Vista, Windows Server 2003 y Windows XP: Este código de control no se admite.

Este parámetro también puede ser un código de control definido por el usuario, como se describe en la tabla siguiente.

Código de control	Significado
Intervalo de 128 a 255.	El servicio define la acción asociada al código de control.

[in] dwEventType

Tipo de evento que se ha producido. Este parámetro se usa si dwControl está SERVICE_CONTROL_DEVICEEVENT, SERVICE_CONTROL_HARDWAREPROFILECHANGE, SERVICE_CONTROL_POWEREVENT o SERVICE_CONTROL_SESSIONCHANGE. De lo contrario, es cero.

Si dwControl es SERVICE_CONTROL_DEVICEEVENT, este parámetro puede ser uno de los siguientes valores:

Si dwControl es SERVICE_CONTROL_HARDWAREPROFILECHANGE, este parámetro puede ser uno de los siguientes valores:

Si dwControl es SERVICE_CONTROL_POWEREVENT, este parámetro puede ser uno de los valores especificados en el parámetro wParam del mensaje de WM_POWERBROADCAST .

Si dwControl es SERVICE_CONTROL_SESSIONCHANGE, este parámetro puede ser uno de los valores especificados en el parámetro wParam del mensaje de WM_WTSSESSION_CHANGE .

[in] lpEventData

Información adicional del dispositivo, si es necesario. El formato de estos datos depende del valor de los parámetros dwControl y dwEventType .

Si dwControl es SERVICE_CONTROL_DEVICEEVENT, estos datos corresponden al parámetro lParam que las aplicaciones reciben como parte de un mensaje de WM_DEVICECHANGE .

Si dwControl es SERVICE_CONTROL_POWEREVENT y dwEventType es PBT_POWERSETTINGCHANGE, estos datos son un puntero a una estructura de POWERBROADCAST_SETTING .

Si dwControl es SERVICE_CONTROL_SESSIONCHANGE, este parámetro es un puntero a una estructura de WTSSESSION_NOTIFICATION .

Si dwControl es SERVICE_CONTROL_TIMECHANGE, estos datos son un puntero a una estructura de SERVICE_TIMECHANGE_INFO .

[in] lpContext

Datos definidos por el usuario pasados desde RegisterServiceCtrlHandlerEx. Cuando varios servicios comparten un proceso, el parámetro lpContext puede ayudar a identificar el servicio.

Valor devuelto

El valor devuelto de esta función depende del código de control recibido.

En la lista siguiente se identifican las reglas de este valor devuelto:

En general, si el servicio no controla el control, devuelva ERROR_CALL_NOT_IMPLEMENTED. Sin embargo, el servicio debe devolver NO_ERROR para SERVICE_CONTROL_INTERROGATE incluso si el servicio no lo controla.
Si el servicio controla SERVICE_CONTROL_STOP o SERVICE_CONTROL_SHUTDOWN, devuelva NO_ERROR.
Si el servicio controla SERVICE_CONTROL_DEVICEEVENT, devuelva NO_ERROR para conceder la solicitud y un código de error para denegar la solicitud.
Si el servicio controla SERVICE_CONTROL_HARDWAREPROFILECHANGE, devuelva NO_ERROR para conceder la solicitud y un código de error para denegar la solicitud.
Si el servicio controla SERVICE_CONTROL_POWEREVENT, devuelva NO_ERROR para conceder la solicitud y un código de error para denegar la solicitud.
Para todos los demás códigos de control que controla el servicio, devuelva NO_ERROR.

Comentarios

Cuando se inicia un servicio, su función ServiceMain debe llamar inmediatamente a la función RegisterServiceCtrlHandlerEx para especificar una función HandlerEx para procesar las solicitudes de control. Para especificar los códigos de control que se van a aceptar, use las funciones SetServiceStatus y RegisterDeviceNotification .

El distribuidor de controles del subproceso principal de un 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 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 devolver NO_ERROR. Devolver un error para este código de control y no detenerse de forma oportuna 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 espera 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

Asegúrese de controlar Plug and Play eventos de dispositivo lo antes posible; de lo contrario, el sistema puede dejar de responder. Si el controlador de eventos es realizar una operación que pueda bloquear la ejecución (por ejemplo, E/S), es mejor iniciar otro subproceso para realizar la operación de forma asincrónica.

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.

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)