StopService method of the Win32_Service class (Sdoias.h)

The StopService WMI class method places the service, represented by the Win32_Service object, in the stopped state.

This topic uses Managed Object Format (MOF) syntax. For more information about using this method, see Calling a Method.

Syntax

uint32 StopService();

Parameters

This method has no parameters.

Return value

Returns one of the values listed in the following list, or any other value to indicate an error. For additional error codes, see WMI Error Constants or WbemErrorEnum. For general HRESULT values, see System Error Codes.

0

The request was accepted.

1

The request is not supported.

2

The user did not have the necessary access.

3

The service cannot be stopped because other services that are running are dependent on it.

4

The requested control code is not valid, or it is unacceptable to the service.

5

The requested control code cannot be sent to the service because the state of the service (Win32_BaseService.State property) is equal to 0, 1, or 2.

6

The service has not been started.

7

The service did not respond to the start request in a timely fashion.

8

Unknown failure when starting the service.

9

The directory path to the service executable file was not found.

10

The service is already running.

11

The database to add a new service is locked.

12

A dependency this service relies on has been removed from the system.

13

The service failed to find the service needed from a dependent service.

14

The service has been disabled from the system.

15

The service does not have the correct authentication to run on the system.

16

This service is being removed from the system.

17

The service has no execution thread.

18

The service has circular dependencies when it starts.

19

A service is running under the same name.

20

The service name has invalid characters.

21

Invalid parameters have been passed to the service.

22

The account under which this service runs is either invalid or lacks the permissions to run the service.

23

The service exists in the database of services available from the system.

24

The service is currently paused in the system.

Remarks

After you have determined which services can be stopped or paused, you can use the StopService and PauseService methods to stop and pause services. The decision to stop a service rather than pause it, or vice versa, depends on several factors, including the following:

• Is the service capable of being paused? If not, your only option is the stop the service.
• Do you need to continue handling client requests for anyone already connected to the service? If so, pausing a service typically allows it to handle existing clients while denying access to new clients. By contrast, when you stop a service, all clients are immediately disconnected.
• Do you need to reconfigure a service and have the changes take effect immediately? Although service properties can be changed while a service is paused, most of them do not take effect until the service is actually stopped and restarted.

The scripting code required to stop a service is almost identical to the code required to pause the service.

If you attempt to stop a service which has dependent services running, the StopService method fails with a return value of 3. The dependent services must be stopped first.

If you stop a service, then immediately check the Win32_Service.State property, as the value may still show the service as running.

Examples

The following VBScript code sample demonstrates how to shut down a service.

Set ServiceSet = GetObject("winmgmts:").ExecQuery("select * from Win32_Service where Name='ClipSrv'")

for each Service in ServiceSet
 RetVal = Service.StopService()
 if RetVal = 0 then 
  WScript.Echo "Service stopped" 
 elseif RetVal = 5 then 
  WScript.Echo "Service already stopped" 
 end if
next

The following Perl code sample demonstrates how to shut down a service.

use strict;
use Win32::OLE;

my $ServiceSet;

eval { $ServiceSet = 
 Win32::OLE->GetObject("winmgmts:{impersonationLevel=impersonate}!\\\\.\\root\\cimv2")->
 ExecQuery("SELECT * FROM Win32_Service WHERE Name='ClipSrv'"); };

if (!$@ && defined $ServiceSet)
{
 foreach my $ServiceInst (in $ServiceSet)
 {
  my $Result = $ServiceInst->StopService();
  if ($Result == 0)
  {
   print "\nService stopped\n";
  }
  elsif ($Result == 5) 
  {
   print "\nService already stopped\n";
  }
 }
}
else
{
 print STDERR Win32::OLE->LastError, "\n";
}

The following VBScript code example shows that you cannot stop the NetDDE service until the dependent services have been stopped. To run the script, ensure that the NetDDE service and its dependent services are running by using the Services.msc MMC snap-in or the Net Start command.

The Win32_DependentService class allows you to locate service dependencies through an Associators Of query.

strComputer = "."
Set objWMIService = GetObject("winmgmts:" _
    & "{impersonationLevel=impersonate}!\\" & _
    strComputer & "\root\cimv2")

Set objNetDDEservice = _
    objWMIService.Get("Win32_Service.Name='NetDDE'")

WScript.Echo "NetDDE service state: " & objNetDDEService.State
WScript.Echo "Stopping NetDDE service"
Return = objNetDDEService.StopService()
WScript.Echo "Return value: " & Return  & _
    "  Service cannot be stopped because " & _
    "dependent services are running"

Set colServiceList = objWMIService.ExecQuery("Associators of " _
    & "{Win32_Service.Name='NetDDE'} Where " _
        & "AssocClass=Win32_DependentService " & _
    "Role=Antecedent" )

For Each objService in colServiceList
   WScript.Echo "Dependent service: " & objService.Name & _
   "   State: " & objService.State
   WScript.Echo "Stopping dependent service " & objService.Name
   objService.StopService()    
Next

Wscript.Sleep 20000
WScript.Echo "Stopping NetDDE service"
Return = objNetDDEService.StopService()
WScript.Echo "Return value: " & Return

Requirements

See also

Operating System Classes

Win32_Service

WMI Tasks: Services

PauseService