Stopping a Service
A service can be stopped with the ControlService function by sending a SERVICE_CONTROL_STOP request. If the SCM receives a SERVICE_CONTROL_STOP request for a service, it instructs the service to stop by forwarding the request to the service's ServiceMain function. However, if the SCM determines that other running services are dependent on the specified service, it will not forward the stop request. Instead, it returns ERROR_DEPENDENT_SERVICES_RUNNING. Therefore, to programmatically stop such a service, you must first enumerate and stop its dependent services.
If a service accepts the SERVICE_CONTROL_STOP control code, it must stop upon receipt, going to either the SERVICE_STOP_PENDING or SERVICE_STOPPED state. After the SCM sends this control code, it will not send other control codes.
Windows XP/2000: If the service returns NO_ERROR and continues to run, it continues to receive control codes. This behavior changed starting with Windows Server 2003 and Windows XP SP2.
The following code implements a StopService function, which optionally attempts to stop the specified service's dependent services.
#include <windows.h> #include <tchar.h> #include <stdio.h> // This function attempts to stop a service. It allows the caller to // specify whether dependent services should also be stopped. It also // accepts a timeout value, to prevent a scenario in which a service // shutdown hangs, then the application stopping the service hangs. // // Parameters: // hSCM - Handle to the service control manager. // hService - Handle to the service to be stopped. // fStopDependencies - Indicates whether to stop dependent services. // dwTimeout - maximum time (in milliseconds) to wait // // If the operation is successful, returns ERROR_SUCCESS. Otherwise, // returns a system error code. DWORD StopService( SC_HANDLE hSCM, SC_HANDLE hService, BOOL fStopDependencies, DWORD dwTimeout ) { SERVICE_STATUS ss; DWORD dwStartTime = GetTickCount(); DWORD dwBytesNeeded; // Make sure the service is not already stopped if ( !QueryServiceStatusEx( hService, SC_STATUS_PROCESS_INFO, &ss, sizeof(STATUS_PROCESS_INFO), &dwBytesNeeded ) ) return GetLastError(); if ( ss.dwCurrentState == SERVICE_STOPPED ) return ERROR_SUCCESS; // If a stop is pending, just wait for it while ( ss.dwCurrentState == SERVICE_STOP_PENDING ) { Sleep( ss.dwWaitHint ); if ( !QueryServiceStatusEx( hService, SC_STATUS_PROCESS_INFO, &ss, sizeof(STATUS_PROCESS_INFO), &dwBytesNeeded ) ) return GetLastError(); if ( ss.dwCurrentState == SERVICE_STOPPED ) return ERROR_SUCCESS; if ( GetTickCount() - dwStartTime > dwTimeout ) return ERROR_TIMEOUT; } // If the service is running, dependencies must be stopped first if ( fStopDependencies ) { DWORD i; DWORD dwBytesNeeded; DWORD dwCount; LPENUM_SERVICE_STATUS lpDependencies = NULL; ENUM_SERVICE_STATUS ess; SC_HANDLE hDepService; // Pass a zero-length buffer to get the required buffer size if ( EnumDependentServices( hService, SERVICE_ACTIVE, lpDependencies, 0, &dwBytesNeeded, &dwCount ) ) { // If the Enum call succeeds, then there are no dependent // services so do nothing } else { if ( GetLastError() != ERROR_MORE_DATA ) return GetLastError(); // Unexpected error // Allocate a buffer for the dependencies lpDependencies = (LPENUM_SERVICE_STATUS) HeapAlloc( GetProcessHeap(), HEAP_ZERO_MEMORY, dwBytesNeeded ); if ( !lpDependencies ) return GetLastError(); __try { // Enumerate the dependencies if ( !EnumDependentServices( hService, SERVICE_ACTIVE, lpDependencies, dwBytesNeeded, &dwBytesNeeded, &dwCount ) ) return GetLastError(); for ( i = 0; i < dwCount; i++ ) { ess = *(lpDependencies + i); // Open the service hDepService = OpenService( hSCM, ess.lpServiceName, SERVICE_STOP | SERVICE_QUERY_STATUS ); if ( !hDepService ) return GetLastError(); __try { // Send a stop code if ( !ControlService( hDepService, SERVICE_CONTROL_STOP, &ss ) ) return GetLastError(); // Wait for the service to stop while ( ss.dwCurrentState != SERVICE_STOPPED ) { Sleep( ss.dwWaitHint ); if ( !QueryServiceStatusEx( hDepService, SC_STATUS_PROCESS_INFO, &ss, sizeof(STATUS_PROCESS_INFO), &dwBytesNeeded ) ) return GetLastError(); if ( ss.dwCurrentState == SERVICE_STOPPED ) break; if ( GetTickCount() - dwStartTime > dwTimeout ) return ERROR_TIMEOUT; } } __finally { // Always release the service handle CloseServiceHandle( hDepService ); } } } __finally { // Always free the enumeration buffer HeapFree( GetProcessHeap(), 0, lpDependencies ); } } } // Send a stop code to the main service if ( !ControlService( hService, SERVICE_CONTROL_STOP, &ss ) ) return GetLastError(); // Wait for the service to stop while ( ss.dwCurrentState != SERVICE_STOPPED ) { Sleep( ss.dwWaitHint ); if ( !QueryServiceStatusEx( hService, SC_STATUS_PROCESS_INFO, &ss, sizeof(STATUS_PROCESS_INFO), &dwBytesNeeded ) ) return GetLastError(); if ( ss.dwCurrentState == SERVICE_STOPPED ) break; if ( GetTickCount() - dwStartTime > dwTimeout ) return ERROR_TIMEOUT; } // Return success return ERROR_SUCCESS; } // Helper function to display an error message void DisplayError( LPTSTR szAPI, DWORD dwError ) { LPTSTR lpBuffer = NULL; FormatMessage( FORMAT_MESSAGE_ALLOCATE_BUFFER | FORMAT_MESSAGE_FROM_SYSTEM, NULL, dwError, MAKELANGID(LANG_NEUTRAL, SUBLANG_DEFAULT), (LPTSTR) &lpBuffer, 0, NULL ); _tprintf( TEXT("%s failed:/n"), szAPI ); _tprintf( TEXT(" error code = %u/n"), dwError ); _tprintf( TEXT(" message = %s/n"), lpBuffer ); LocalFree( lpBuffer ); } // Entry point for the program. This function contains sample code // demonstrating how to use the StopService function implemented // above. // // Parameters: // argc - the number of command-line arguments // argv[] - an array of command-line arguments void _tmain( int argc, TCHAR *argv[] ) { SC_HANDLE hSCM; SC_HANDLE hService; DWORD dwError; if ( argc < 2 ) { _tprintf( TEXT("usage: /"%s/" <ServiceName>/n"), argv[0] ); return; } __try { // Open the SCM database hSCM = OpenSCManager( NULL, NULL, SC_MANAGER_CONNECT ); if ( !hSCM ) { DisplayError( TEXT("OpenSCManager()"), GetLastError() ); __leave; } // Open the specified service hService = OpenService( hSCM, argv[1], SERVICE_STOP | SERVICE_QUERY_STATUS | SERVICE_ENUMERATE_DEPENDENTS ); if ( !hService ) { DisplayError( TEXT("OpenService()"), GetLastError() ); __leave; } // Try to stop the service, specifying a 30 second timeout dwError = StopService( hSCM, hService, TRUE, 30000 ) ; if ( dwError == ERROR_SUCCESS ) _tprintf( TEXT("Service stopped./n") ); else DisplayError( TEXT("StopService()"), dwError ); } __finally { if ( hService ) CloseServiceHandle( hService ); if ( hSCM ) CloseServiceHandle( hSCM ); } }