ControlServiceExA function (winsvc.h)
Sends a control code to a service.
Syntax
BOOL ControlServiceExA(
[in] SC_HANDLE hService,
[in] DWORD dwControl,
[in] DWORD dwInfoLevel,
[in, out] PVOID pControlParams
);
Parameters
[in] hService
A handle to the service. This handle is returned by the OpenService or CreateService function. The access rights required for this handle depend on the dwControl code requested.
[in] dwControl
This parameter can be one of the following control codes.
This parameter can also be a user-defined control code, as described in the following table.
| Control code | Meaning |
|---|---|
|
The service defines the action associated with the control code. The hService handle must have the SERVICE_USER_DEFINED_CONTROL access right. |
[in] dwInfoLevel
The information level for the service control parameters. This parameter must be set to SERVICE_CONTROL_STATUS_REASON_INFO (1).
[in, out] pControlParams
A pointer to the service control parameters. If dwInfoLevel is SERVICE_CONTROL_STATUS_REASON_INFO, this member is a pointer to a SERVICE_CONTROL_STATUS_REASON_PARAMS structure.
Return value
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.
The following error codes can be set by the service control manager. Other error codes can be set by the registry functions that are called by the service control manager.
| Return code | Description |
|---|---|
|
The handle does not have the required access right. |
|
The service cannot be stopped because other running services are dependent on it. |
|
The specified handle was not obtained using CreateService or OpenService, or the handle is no longer valid. |
|
The requested control code in the dwControl parameter is undefined, or dwControl is SERVICE_CONTROL_STOP but the dwReason or pszComment members of the SERVICE_CONTROL_STATUS_REASON_PARAMS structure are not valid. |
|
The requested control code is not valid, or it is unacceptable to the service. |
|
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. |
|
The service has not been started. |
|
The process for the service was started, but it did not call StartServiceCtrlDispatcher, or the thread that called StartServiceCtrlDispatcher may be blocked in a control handler function. |
|
The system is shutting down. |
Remarks
The ControlServiceEx function asks the Service Control Manager (SCM) to send the requested control code to the service. The SCM sends the code if the service has specified that it will accept the code, and is in a state in which a control code can be sent to it.
The SCM processes service control notifications in a serial fashion — it waits for one service to complete processing a service control notification before sending the next one. Because of this, a call to ControlServiceEx blocks for 30 seconds if any service is busy handling a control code. If the busy service still has not returned from its handler function when the timeout expires, ControlServiceEx fails with ERROR_SERVICE_REQUEST_TIMEOUT.
To stop and start a service requires a security descriptor that allows you to do so. The default security descriptor allows the LocalSystem account, and members of the Administrators and Power Users groups to stop and start services. To change the security descriptor of a service, see Modifying the DACL for a Service.
The QueryServiceStatusEx function returns a SERVICE_STATUS_PROCESS structure whose dwCurrentState and dwControlsAccepted members indicate the current state and controls accepted by a running service. All running services accept the SERVICE_CONTROL_INTERROGATE control code by default. Drivers do not accept control codes other than SERVICE_CONTROL_STOP and SERVICE_CONTROL_INTERROGATE. Each service specifies the other control codes that it accepts when it calls the SetServiceStatus function to report its status. A service should always accept these codes when it is running, no matter what it is doing.
The following table shows the action of the SCM 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, ControlServiceEx returns zero and GetLastError returns ERROR_INVALID_SERVICE_CONTROL.
- (b)
- The service is not in a state in which a control can be sent to it, so ControlServiceEx returns zero and GetLastError returns ERROR_SERVICE_CANNOT_ACCEPT_CTRL.
- (c)
- The service is not active, so ControlServiceEx returns zero and GetLastError returns ERROR_SERVICE_NOT_ACTIVE.
Note
The winsvc.h header defines ControlServiceEx as an alias that automatically selects the ANSI or Unicode version of this function based on the definition of the UNICODE preprocessor constant. Mixing usage of the encoding-neutral alias with code that is not encoding-neutral can lead to mismatches that result in compilation or runtime errors. For more information, see Conventions for Function Prototypes.
Requirements
| Requirement | Value |
|---|---|
| Minimum supported client | Windows Vista [desktop apps only] |
| Minimum supported server | Windows Server 2008 [desktop apps only] |
| Target Platform | Windows |
| Header | winsvc.h (include Windows.h) |
| Library | Advapi32.lib |
| DLL | Advapi32.dll |