Compartir a través de


Función ControlService (winsvc.h)

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

Para especificar información adicional al detener un servicio, use la función ControlServiceEx .

Sintaxis

BOOL ControlService(
  [in]  SC_HANDLE        hService,
  [in]  DWORD            dwControl,
  [out] LPSERVICE_STATUS lpServiceStatus
);

Parámetros

[in] hService

Identificador del servicio. La función OpenService o CreateService devuelve este identificador. 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 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 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 hService debe tener el derecho de acceso SERVICE_PAUSE_CONTINUE . Sin embargo, este código de control ha quedado en desuso; use Plug and Play funcionalidad en su lugar.
SERVICE_CONTROL_NETBINDDISABLE
0x0000000A
Notifica a un servicio de red que se ha deshabilitado uno de sus enlaces. El identificador hService debe tener el derecho de acceso SERVICE_PAUSE_CONTINUE . Sin embargo, este código de control ha quedado en desuso; use Plug and Play funcionalidad en su lugar.
SERVICE_CONTROL_NETBINDENABLE
0x00000009
Notifica a un servicio de red que se ha habilitado un enlace deshabilitado. El identificador hService debe tener el derecho de acceso SERVICE_PAUSE_CONTINUE . Sin embargo, este código de control ha quedado en desuso; use Plug and Play funcionalidad en su lugar.
SERVICE_CONTROL_NETBINDREMOVE
0x00000008
Notifica a un servicio de red que se ha quitado un componente para el enlace. El identificador hService debe tener el derecho de acceso SERVICE_PAUSE_CONTINUE . Sin embargo, este código de control ha quedado en desuso; use Plug and Play funcionalidad en su lugar.
SERVICE_CONTROL_PARAMCHANGE
0x00000006
Notifica a un servicio que sus parámetros de inicio han cambiado. El identificador hService debe tener el derecho de acceso SERVICE_PAUSE_CONTINUE .
SERVICE_CONTROL_PAUSE
0x00000002
Notifica a un servicio que debe pausar. El identificador 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 valor 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 hService debe tener el derecho de acceso SERVICE_USER_DEFINED_CONTROL .

[out] lpServiceStatus

Puntero a una estructura de SERVICE_STATUS que recibe la información de estado del servicio más reciente. La información devuelta refleja el estado más reciente que el servicio notificó al administrador de control de servicios.

El administrador de controles de servicio rellena la estructura solo cuando GetLastError devuelve uno de los siguientes códigos de error: NO_ERROR, ERROR_INVALID_SERVICE_CONTROL, ERROR_SERVICE_CANNOT_ACCEPT_CTRL o ERROR_SERVICE_NOT_ACTIVE. De lo contrario, la estructura no se rellena.

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 controles de servicio 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 OpenService, o el identificador ya no es válido.
ERROR_INVALID_PARAMETER
El código de control solicitado no está definido.
ERROR_INVALID_SERVICE_CONTROL
El código de control solicitado no es válido o no es aceptable 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
El servicio no se ha iniciado.
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 está apagando.

Comentarios

La función ControlService pide 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: esperará a que un servicio complete el procesamiento de una notificación de control de servicio antes de enviar la siguiente. Por este motivo, una llamada a ControlService se bloqueará 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, ControlService produce un error 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 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 para un servicio.

La función QueryServiceStatusEx devuelve una estructura de SERVICE_STATUS_PROCESS cuyos miembros dwCurrentState y dwControlsAccepted 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 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 ejecuta, independientemente de lo que haga.

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

Estado de servicio Stop Otros controles
STOPPED (c) (c)
STOP_PENDING (b) (b)
START_PENDING (a) (b)
CORRIENDO (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, ControlService 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 ControlService devuelve cero y GetLastError devuelve ERROR_SERVICE_CANNOT_ACCEPT_CTRL.
(c)
El servicio no está activo, por lo que ControlService devuelve cero y GetLastError devuelve ERROR_SERVICE_NOT_ACTIVE.

Ejemplos

Para obtener un ejemplo, consulte Detener un servicio.

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

Consulte también

ControlServiceEx

CreateService

OpenService

QueryServiceStatusEx

SERVICE_STATUS

Solicitudes de control de servicio

Funciones de servicio

SetServiceObjectSecurity

SetServiceStatus