Función RegisterServiceCtrlHandlerA (winsvc.h)
Registra una función para controlar las solicitudes de control de servicio.
Esta función se ha reemplazado por la función RegisterServiceCtrlHandlerEx . Un servicio puede usar cualquiera de las funciones, pero la nueva función admite datos de contexto definidos por el usuario y la nueva función de controlador admite códigos de control extendidos adicionales.
Sintaxis
SERVICE_STATUS_HANDLE RegisterServiceCtrlHandlerA(
[in] LPCSTR lpServiceName,
[in] LPHANDLER_FUNCTION lpHandlerProc
);
Parámetros
[in] lpServiceName
Nombre del servicio ejecutado por el subproceso que realiza la llamada. Este es el nombre del servicio que el programa de control de servicio especificó en la función CreateService al crear el servicio.
Si el tipo de servicio es SERVICE_WIN32_OWN_PROCESS, la función no comprueba que el nombre especificado sea válido, ya que solo hay un servicio registrado en el proceso.
[in] lpHandlerProc
Puntero a la función de controlador que se va a registrar. Para obtener más información, vea Controlador.
Valor devuelto
Si la función se realiza correctamente, el valor devuelto es un identificador de estado del servicio.
Si la función no se realiza correctamente, el valor devuelto es cero. Para obtener información de error extendida, llame a GetLastError.
El administrador de control de servicios puede establecer los siguientes códigos de error.
| Código devuelto | Descripción |
|---|---|
|
No hay suficiente memoria disponible para convertir un parámetro de cadena ANSI en Unicode. Este error no se produce para los parámetros de cadena Unicode. |
|
La entrada de servicio se especificó incorrectamente cuando el proceso llamó a la función StartServiceCtrlDispatcher . |
Comentarios
La función ServiceMain de un nuevo servicio debe llamar inmediatamente a la función RegisterServiceCtrlHandler para registrar una función de controlador de control con el distribuidor de controles. Esto permite al distribuidor de control invocar la función especificada cuando recibe solicitudes de control para este servicio. Para obtener una lista de los posibles códigos de control, vea Controlador. Los subprocesos del proceso de llamada pueden usar el identificador de estado del servicio devuelto por esta función para identificar el servicio en llamadas posteriores a la función SetServiceStatus .
Se debe llamar a la función RegisterServiceCtrlHandler antes de la primera llamada a SetServiceStatus porque RegisterServiceCtrlHandler devuelve un identificador de estado de servicio para que el llamador lo use para que ningún otro servicio pueda establecer accidentalmente este estado de servicio. Además, el controlador de control debe estar en su lugar para recibir solicitudes de control en el momento en que el servicio especifica los controles que acepta a través de la función SetServiceStatus .
Cuando se invoca la función de controlador de control con una solicitud de control, el servicio debe llamar a SetServiceStatus para notificar el estado al administrador de controles de servicio solo si el estado del servicio ha cambiado, como cuando el servicio está procesando controles de detención o apagado. Si el estado del servicio no ha cambiado, el servicio no debe notificar el estado al administrador de control de servicios.
No es necesario cerrar el identificador de estado del servicio.
Ejemplos
Para obtener un ejemplo, consulte Escritura de una función ServiceMain.
Nota
El encabezado winsvc.h define RegisterServiceCtrlHandler como alias que selecciona automáticamente la versión ANSI o Unicode de esta función en función de la definición de la constante de preprocesador UNICODE. La combinación del uso del alias neutral de codificación con código que no es neutral de codificación puede dar lugar a errores de coincidencia que dan lugar a errores de compilación o tiempo de ejecución. Para obtener más información, vea Convenciones para prototipos de función.
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) |
| Library | Advapi32.lib |
| Archivo DLL | Advapi32.dll |