ControlService
The ControlService
function sends a control code to a Win32 service.
BOOL ControlService(
|
SC_HANDLE hService, |
// handle to
service |
|
DWORD dwControl, |
// control code |
|
LPSERVICE_STATUS lpServiceStatus |
// pointer to
service status structure |
|
); |
|
Parameters
hService
Identifies
the service. This handle is returned by the OpenService or CreateService function. The access
required for this handle depends on the dwControl code requested.
dwControl
Specifies the
requested control code. This value can be one of the standard control codes in
the table, or it can be a user-defined control code in the range of 128 to 255,
inclusive. For user-defined control codes, the hService handle must have
SERVICE_USER_DEFINED_CONTROL access, and the service defines the action
associated with the control code.
|
Value |
Meaning |
|
SERVICE_CONTROL_STOP |
|
|
|
Requests
the service to stop. The hService handle must have SERVICE_STOP
access. |
|
SERVICE_CONTROL_PAUSE |
|
|
|
Requests
the service to pause. The hService handle must have
SERVICE_PAUSE_CONTINUE access. |
|
SERVICE_CONTROL_CONTINUE |
|
|
|
Requests
the paused service to resume. The hService handle must have
SERVICE_PAUSE_CONTINUE access. |
|
SERVICE_CONTROL_INTERROGATE |
|
|
|
Requests
the service to update immediately its current status information to the
service control manager. The hService handle must have
SERVICE_INTERROGATE access. |
|
SERVICE_CONTROL_SHUTDOWN |
|
|
|
The ControlService
function fails if this control code is specified. |
lpServiceStatus
Points to a SERVICE_STATUS structure where the latest
status information of the service is returned. The information returned
reflects the most recent status reported by the service to the service control
manager.
Return Values
If the
function succeeds, the return value is nonzero.
If the
function fails, the return value is zero. To get extended error information,
call GetLastError.
Errors
The following
error codes may be set by the service control manager. Other error codes may be
set by the registry functions that are called by the service control manager.
|
Value |
Meaning |
|
ERROR_ACCESS_DENIED |
|
|
|
The
specified handle was not opened with the necessary access. |
|
ERROR_DEPENDENT_SERVICES_RUNNING |
|
|
|
The service
cannot be stopped because other running services are dependent on it. |
|
ERROR_INVALID_SERVICE_CONTROL |
|
|
|
The
requested control code is not valid, or it is unacceptable to the service. |
|
ERROR_SERVICE_CANNOT_ACCEPT_CTRL |
|
|
|
The
requested control code cannot be sent to the service because the state of the
service is SERVICE_STOPPED, SERVICE_START_PENDING, or SERVICE_STOP_PENDING. |
|
ERROR_SERVICE_NOT_ACTIVE |
|
|
|
The service
has not been started. |
|
ERROR_SERVICE_REQUEST_TIMEOUT |
|
|
|
The service
did not respond to the start request in a timely fashion. |
Remarks
The ControlService
function asks the service control manager to send the requested control code to
the service. The service control manager sends the code if the service accepts
the control and if the service is in a controllable state. The QueryServiceStatus or ControlService
function returns a SERVICE_STATUS structure whose dwCurrentState and dwControlsAccepted
members indicate the current state and controls accepted by a running Win32
service.
All running
services accept the SERVICE_CONTROL_INTERROGATE control code by default. Each
service specifies the other control codes that it accepts when it calls the SetServiceStatus function to report its
status.
The following
table shows the action of the service control manager in each of the possible
service states:
|
Service
state |
Stop |
Other
controls |
|
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) If the
service accepts this control code, send the request to the service;
otherwise, ControlService returns FALSE and GetLastError
returns ERROR_INVALID_SERVICE_CONTROL. |
|
|
(b) The
service is not in a controllable state, so ControlService returns
FALSE and GetLastError returns ERROR_SERVICE_CANNOT_ACCEPT_CTRL. |
|
|
(c) The
service is not in a controllable state, so ControlService returns
FALSE and GetLastError returns ERROR_SERVICE_NOT_ACTIVE. |
|
See Also