Función SetServiceStatus (winsvc.h)

Artículo
03/08/2023

Novedades la información de estado del administrador de control de servicio para el servicio de llamada.

Sintaxis

BOOL SetServiceStatus(
  [in] SERVICE_STATUS_HANDLE hServiceStatus,
  [in] LPSERVICE_STATUS      lpServiceStatus
);

Parámetros

[in] hServiceStatus

Identificador de la estructura de información de estado del servicio actual. La función RegisterServiceCtrlHandlerEx devuelve este identificador.

[in] lpServiceStatus

Puntero a la estructura SERVICE_STATUS que contiene la información de estado más reciente para el servicio de llamada.

Valor devuelto

Si la función se realiza correctamente, el valor devuelto es distinto de cero.

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. Otros códigos de error se pueden establecer mediante las funciones del Registro a las que llama el administrador de control de servicio.

Código devuelto	Descripción
ERROR_INVALID_DATA	La estructura de estado del servicio especificada no es válida.
ERROR_INVALID_HANDLE	El identificador especificado no es válido.

Comentarios

Una función ServiceMain llama primero a la función RegisterServiceCtrlHandlerEx para obtener el SERVICE_STATUS_HANDLE del servicio. A continuación, llama inmediatamente a la función SetServiceStatus para notificar al administrador de control de servicio que su estado es SERVICE_START_PENDING. Durante la inicialización, el servicio puede proporcionar el estado actualizado para indicar que está progresando, pero necesita más tiempo. Un error común es que el servicio haga que el subproceso principal realice la inicialización mientras un subproceso independiente continúa llamando a SetServiceStatus para evitar que el administrador de control de servicios lo marque como bloqueado. Sin embargo, si el subproceso principal se bloquea, el inicio del servicio termina en un bucle infinito porque el subproceso de trabajo sigue informando de que el subproceso principal está progresando.

Después de procesar una solicitud de control, la función Handler del servicio debe llamar a SetServiceStatus si el estado del servicio cambia para notificar su nuevo estado al administrador de control de servicios. Solo es necesario hacerlo cuando el servicio cambia de estado, como cuando se está procesando los controles de detención o apagado. Un servicio también puede usar esta función en cualquier momento desde cualquier subproceso del servicio para notificar al administrador de control de servicios los cambios de estado, como cuando el servicio debe detenerse debido a un error recuperable.

Un servicio puede llamar a esta función solo después de llamar a RegisterServiceCtrlHandlerEx para obtener un identificador de estado de servicio.

Si un servicio llama a SetServiceStatus con el miembro dwCurrentState establecido en SERVICE_STOPPED y el miembro dwWin32ExitCode establecido en un valor distinto de cero, la entrada siguiente se escribe en el registro de eventos del sistema:

   Event ID    = 7023
   Source      = Service Control Manager
   Type        = Error
   Description = <ServiceName> terminated with the following error:
                 <ExitCode>.

Estos son los procedimientos recomendados al llamar a esta función:

Inicialice todos los campos de la estructura SERVICE_STATUS , asegurándose de que hay valores válidos de punto de comprobación y sugerencia de espera para los estados pendientes. Use sugerencias de espera razonables.
No se registre para aceptar controles mientras el estado es SERVICE_START_PENDING o el servicio puede bloquearse. Una vez completada la inicialización, acepte el código SERVICE_CONTROL_STOP.
Llame a esta función con valores de punto de control y sugerencia de espera solo si el servicio está progresando en las tareas relacionadas con la operación de inicio, detención, pausa o continuación pendientes. De lo contrario, SCM no puede detectar si el servicio está bloqueado.
Escriba el estado detenido con un código de salida adecuado si se produce un error en ServiceMain .
Si el estado es SERVICE_STOPPED, realice toda la limpieza necesaria y llame a SetServiceStatus una sola vez. Esta función realiza una llamada LRPC al SCM. La primera llamada a la función en el estado SERVICE_STOPPED cierra el identificador de contexto RPC y las llamadas posteriores pueden provocar que el proceso se bloquee.
No intente realizar ningún trabajo adicional después de llamar a SetServiceStatus con SERVICE_STOPPED, ya que el proceso de servicio se puede finalizar en cualquier momento.

Ejemplos

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

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