Función RegisterServiceCtrlHandlerW (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 RegisterServiceCtrlHandlerW(
  [in] LPCWSTR            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 especificó el programa de control de servicio 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 Handler.

Valor devuelto

Si la función se ejecuta correctamente, el valor devuelto es un identificador de estado del servicio.

Si se produce un error en la función, 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.

Observaciones

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 posibles códigos de control, consulte 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 SetServiceStatus porque RegisterServiceCtrlHandler devuelve un identificador de estado de servicio para que el autor de la llamada pueda usar para que ningún otro servicio pueda establecer involuntariamente 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 control de servicio solo si el estado del servicio ha cambiado, como cuando el servicio está procesando los 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.

El identificador de estado del servicio no tiene que cerrarse.

Ejemplos

Para obtener un ejemplo, consulte Escritura de una función ServiceMain.

Requisitos

Consulte también

CreateService

de controlador de

RegisterServiceCtrlHandlerEx

función de controlador de control de servicio de

Funciones de servicio

ServiceMain

SetServiceStatus