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.
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 |
|---|---|
|
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 |
|---|---|
|
El identificador no tiene el derecho de acceso necesario. |
|
No se puede detener el servicio porque otros servicios en ejecución dependen de él. |
|
El identificador especificado no se obtuvo mediante CreateService o OpenService, o el identificador ya no es válido. |
|
El código de control solicitado no está definido. |
|
El código de control solicitado no es válido o no es aceptable para el servicio. |
|
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. |
|
El servicio no se ha iniciado. |
|
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. |
|
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 |