Función ControlServiceExA (winsvc.h)

Artículo
03/08/2023

Envía un código de control a un servicio.

Sintaxis

BOOL ControlServiceExA(
  [in]      SC_HANDLE hService,
  [in]      DWORD     dwControl,
  [in]      DWORD     dwInfoLevel,
  [in, out] PVOID     pControlParams
);

Parámetros

[in] hService

Identificador del servicio. Este identificador lo devuelve la función OpenService o CreateService. Los derechos de acceso necesarios para este identificador dependen del código dwControl solicitado.

[in] dwControl

Este parámetro puede ser uno de los siguientes códigos de control.

Código de control	Significado
SERVICE_CONTROL_CONTINUE 0x00000003	Notifica a un servicio en pausa que debe reanudarse. El identificador de hService debe tener el derecho de acceso SERVICE_PAUSE_CONTINUE.
SERVICE_CONTROL_INTERROGATE 0x00000004	Notifica a un servicio que debe notificar su información de estado actual al administrador de control de servicios. El identificador hService debe tener el derecho de acceso SERVICE_INTERROGATE. Tenga en cuenta que este control no suele ser útil, ya que 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 identificador de hService debe tener el derecho de acceso SERVICE_PAUSE_CONTINUE. Sin embargo, este código de control ha quedado en desuso; Use la funcionalidad Plug and Play en su lugar.
SERVICE_CONTROL_NETBINDDISABLE 0x0000000A	Notifica a un servicio de red que se ha deshabilitado uno de sus enlaces. El identificador de hService debe tener el derecho de acceso SERVICE_PAUSE_CONTINUE. Sin embargo, este código de control ha quedado en desuso; Use la funcionalidad Plug and Play en su lugar.
SERVICE_CONTROL_NETBINDENABLE 0x00000009	Notifica a un servicio de red que se ha habilitado un enlace deshabilitado. El identificador de hService debe tener el derecho de acceso SERVICE_PAUSE_CONTINUE. Sin embargo, este código de control ha quedado en desuso; Use la funcionalidad Plug and Play en su lugar.
SERVICE_CONTROL_NETBINDREMOVE 0x00000008	Notifica a un servicio de red que se ha quitado un componente para el enlace. El identificador de hService debe tener el derecho de acceso SERVICE_PAUSE_CONTINUE. Sin embargo, este código de control ha quedado en desuso; Use la funcionalidad Plug and Play en su lugar.
SERVICE_CONTROL_PARAMCHANGE 0x00000006	Notifica a un servicio que sus parámetros de inicio han cambiado. El identificador de hService debe tener el derecho de acceso SERVICE_PAUSE_CONTINUE.
SERVICE_CONTROL_PAUSE 0x00000002	Notifica a un servicio que debe pausar. El identificador de hService debe tener el derecho de acceso SERVICE_PAUSE_CONTINUE.
SERVICE_CONTROL_STOP 0x00000001	Notifica a un servicio que debe detenerse. El identificador hService debe tener el derecho de acceso SERVICE_STOP. Después de enviar la solicitud de detención a un servicio, no debe enviar otros controles al servicio.

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. El identificador de hService debe tener el derecho de acceso SERVICE_USER_DEFINED_CONTROL.

[in] dwInfoLevel

Nivel de información de los parámetros de control de servicio. Este parámetro debe establecerse en SERVICE_CONTROL_STATUS_REASON_INFO (1).

[in, out] pControlParams

Puntero a los parámetros de control de servicio. Si dwInfoLevel es SERVICE_CONTROL_STATUS_REASON_INFO, este miembro es un puntero a una estructura de SERVICE_CONTROL_STATUS_REASON_PARAMS.

Valor devuelto

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

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

Código devuelto	Descripción
ERROR_ACCESS_DENIED	El identificador no tiene el derecho de acceso necesario.
ERROR_DEPENDENT_SERVICES_RUNNING	No se puede detener el servicio porque otros servicios en ejecución dependen de él.
ERROR_INVALID_HANDLE	El identificador especificado no se obtuvo mediante CreateService o OpenServiceo el identificador ya no es válido.
ERROR_INVALID_PARAMETER	El código de control solicitado en el parámetro dwControl de no está definido o dwControl es SERVICE_CONTROL_STOP, pero el dwReason o los miembros de pszComment de la estructura de SERVICE_CONTROL_STATUS_REASON_PARAMS no son válidos.
ERROR_INVALID_SERVICE_CONTROL	El código de control solicitado no es válido o es inaceptable para el servicio.
ERROR_SERVICE_CANNOT_ACCEPT_CTRL	El código de control solicitado no se puede enviar al servicio porque el estado del servicio es SERVICE_STOPPED, SERVICE_START_PENDING o SERVICE_STOP_PENDING.
ERROR_SERVICE_NOT_ACTIVE	No se ha iniciado el servicio.
ERROR_SERVICE_REQUEST_TIMEOUT	El proceso para el servicio se inició, pero no llamó a StartServiceCtrlDispatcher, o el subproceso que llamó a StartServiceCtrlDispatcher puede bloquearse en una función de controlador de control.
ERROR_SHUTDOWN_IN_PROGRESS	El sistema se apaga.

Observaciones

La función ControlServiceEx solicita al Administrador de control de servicios (SCM) que envíe el código de control solicitado al servicio. El SCM envía el código si el servicio ha especificado que aceptará el código y se encuentra en un estado en el que se puede enviar un código de control.

El SCM procesa las notificaciones de control de servicio de forma serie: espera a que un servicio complete el procesamiento de una notificación de control de servicio antes de enviar la siguiente. Debido a esto, una llamada a ControlServiceEx bloquea durante 30 segundos si algún servicio está ocupado controlando un código de control. Si el servicio ocupado todavía no ha devuelto de su función de controlador cuando expira el tiempo de espera, ControlServiceEx produce un error con ERROR_SERVICE_REQUEST_TIMEOUT.

Para detener e iniciar un servicio, se requiere un descriptor de seguridad que le permita hacerlo. El descriptor de seguridad predeterminado permite que la cuenta localSystem de y los miembros de los grupos Administradores y usuarios avanzados detengan e inicien los servicios. Para cambiar el descriptor de seguridad de un servicio, consulte Modificación de la DACL de un servicio.

La función queryServiceStatusEx devuelve una estructura SERVICE_STATUS_PROCESS cuyos dwCurrentState y dwControlsAccepted miembros indican el estado actual y los controles aceptados por un servicio en ejecución. Todos los servicios en ejecución aceptan el código de control de SERVICE_CONTROL_INTERROGATE de forma predeterminada. Los controladores no aceptan códigos de control distintos de SERVICE_CONTROL_STOP y SERVICE_CONTROL_INTERROGATE. Cada servicio especifica los demás códigos de control que acepta cuando llama a la función setServiceStatus para notificar su estado. Un servicio siempre debe aceptar estos códigos cuando se está ejecutando, independientemente de lo que haga.

En la tabla siguiente se muestra la acción del SCM en cada uno de los estados de servicio posibles.

Estado del servicio	Parar	Otros controles
DETENIDO	(c)	(c)
STOP_PENDING	(b)	(b)
START_PENDING	(a)	(b)
CORRIENTE	(a)	(a)
CONTINUE_PENDING	(a)	(a)
PAUSE_PENDING	(a)	(a)
PAUSA	(a)	(a)

(a): Si el servicio acepta este código de control, envíe la solicitud al servicio; De lo contrario, ControlServiceEx devuelve cero y GetLastError devuelve ERROR_INVALID_SERVICE_CONTROL.
(b): El servicio no está en un estado en el que se puede enviar un control, por lo que ControlServiceEx devuelve cero y GetLastError devuelve ERROR_SERVICE_CANNOT_ACCEPT_CTRL.
(c): El servicio no está activo, por lo que ControlServiceEx devuelve cero y GetLastError devuelve ERROR_SERVICE_NOT_ACTIVE.

Nota

El encabezado winsvc.h define ControlServiceEx 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 Conventions for Function Prototypes.

Requisitos

Requisito	Valor
cliente mínimo admitido	Windows Vista [solo aplicaciones de escritorio]
servidor mínimo admitido	Windows Server 2008 [solo aplicaciones de escritorio]
de la plataforma de destino de	Windows
encabezado de	winsvc.h (incluya Windows.h)
biblioteca de	Advapi32.lib
DLL de	Advapi32.dll