Función ControlServiceExA (winsvc.h)
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. 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 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 |
---|---|
|
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. |
[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 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 en el parámetro dwControl no está definido o dwControl es SERVICE_CONTROL_STOP, pero los miembros dwReason o pszComment de la estructura SERVICE_CONTROL_STATUS_REASON_PARAMS no son válidos. |
|
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 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. Por este motivo, 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 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 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 está ejecutando, 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) |
RUNNING | (a) | (a) |
CONTINUE_PENDING | (a) | (a) |
PAUSE_PENDING | (a) | (a) |
PAUSED | (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 Convenciones para prototipos de función.
Requisitos
Cliente mínimo compatible | Windows Vista [solo aplicaciones de escritorio] |
Servidor mínimo compatible | Windows Server 2008 [solo aplicaciones de escritorio] |
Plataforma de destino | Windows |
Encabezado | winsvc.h (incluye Windows.h) |
Library | Advapi32.lib |
Archivo DLL | Advapi32.dll |
Consulte también
SERVICE_CONTROL_STATUS_REASON_PARAMS