Función RegisterServiceCtrlHandlerExA (winsvc.h)

Artículo
08/27/2023

Registra una función para controlar las solicitudes de control de servicio extendido.

Sintaxis

SERVICE_STATUS_HANDLE RegisterServiceCtrlHandlerExA(
  [in]           LPCSTR                lpServiceName,
  [in]           LPHANDLER_FUNCTION_EX lpHandlerProc,
  [in, optional] LPVOID                lpContext
);

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.

[in] lpHandlerProc

Puntero a la función de controlador que se va a registrar. Para obtener más información, vea HandlerEx.

[in, optional] lpContext

Cualquier dato definido por el usuario. Este parámetro, que se pasa a la función de controlador, puede ayudar a identificar el servicio cuando varios servicios comparten un proceso.

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
ERROR_NOT_ENOUGH_MEMORY	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.
ERROR_SERVICE_NOT_IN_EXE	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 RegisterServiceCtrlHandlerEx 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 HandlerEx. 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 RegisterServiceCtrlHandlerEx antes de la primera llamada a SetServiceStatus porque RegisterServiceCtrlHandlerEx 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.

Nota

El encabezado winsvc.h define RegisterServiceCtrlHandlerEx 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