Win32Shutdown method of the Win32_OperatingSystem class

Article
11/09/2023

The Win32Shutdown WMI class method provides the full set of shutdown options supported by Win32 operating systems. These include logoff, shutdown, reboot, and forcing a logoff, shutdown, or reboot.

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

Syntax

uint32 Win32Shutdown(
  [in] sint32 Flags,
  [in] sint32 Reserved = 
);

Parameters

Flags [in]

Bitmapped set of flags to shut the computer down. To force a command, add the Force flag (4) to the command value. Using Force in conjunction with Shutdown or Reboot on a remote computer immediately shuts down everything (including WMI, COM, and so on), or reboots the remote computer. This results in an indeterminate return value.

0 (0x0)

Log Off - Logs the user off the computer. Logging off stops all processes associated with the security context of the process that called the exit function, logs the current user off the system, and displays the logon dialog box.

4 (0x4)

Forced Log Off (0 + 4) - Logs the user off the computer immediately and does not notify applications that the logon session is ending. This can result in a loss of data.

1 (0x1)

Shutdown - Shuts down the computer to a point where it is safe to turn off the power. (All file buffers are flushed to disk, and all running processes are stopped.) Users see the message, It is now safe to turn off your computer.

During shutdown the system sends a message to each running application. The applications perform any cleanup while processing the message and return True to indicate that they can be terminated.

5 (0x5)

Forced Shutdown (1 + 4) - Shuts down the computer to a point where it is safe to turn off the power. (All file buffers are flushed to disk, and all running processes are stopped.) Users see the message, It is now safe to turn off your computer.

When the forced shutdown approach is used, all services, including WMI, are shut down immediately. Because of this, you will not be able to receive a return value if you are running the script against a remote computer.

2 (0x2)

Reboot - Shuts down and then restarts the computer.

6 (0x6)

Forced Reboot (2 + 4) - Shuts down and then restarts the computer.

When the forced reboot approach is used, all services, including WMI, are shut down immediately. Because of this, you will not be able to receive a return value if you are running the script against a remote computer.

8 (0x8)

Power Off - Shuts down the computer and turns off the power (if supported by the computer in question).

12 (0xC)

Forced Power Off (8 + 4) - Shuts down the computer and turns off the power (if supported by the computer in question).

When the forced power off approach is used, all services, including WMI, are shut down immediately. Because of this, you will not be able to receive a return value if you are running the script against a remote computer.

Reserved [in]

A means to extend Win32Shutdown. Currently, the Reserved parameter is ignored.

Return value

Returns zero (0) to indicate success. Any other number indicates an error. For error codes, see WMI Error Constants or WbemErrorEnum. For general HRESULT values, see System Error Codes.

Success (0)
Other (1–4294967295)

Remarks

For more efficient management of computers in an organization, administrators need the ability to remotely shut down or restart a computer, or to remotely log off a user. The ability to carry out these tasks allows administrators to install software, reconfigure computer settings, remove computers from the network, and perform other tasks without having to manually shut down or restart each computer.

For example, to perform a network upgrade, you might need to shut down all the computers running on a particular network segment. To force a Group Policy upgrade, you need to log users off their computers. If a computer virus is present anywhere in your organization, you might want to shut down as many computers as possible, before the virus has an opportunity to spread. The ability to shut down and restart computers and to log off users programmatically instead of manually can be an enormous time-saver.

The calling process must have the SE_SHUTDOWN_NAME privilege.

The Win32ShutdownTracker method provides the same set of shutdown options supported by the Win32Shutdown method in Win32_OperatingSystem but it also allows you to specify comments, a reason for shutdown, or a timeout.

The Win32Shutdown method does not have a parameter for locking a workstation, leaving the user logged on. However, workstations can be locked from the command line by using the following command:

% windir %\System32\rundll32.exe user32.dll,LockWorkStation

Examples

The following PowerShell example uses the Win32Shutdown method to shut down the specified computer.

$computername= "."
$win32OS = get-wmiobject win32_operatingsystem -computername $computername
$win32OS.psbase.Scope.Options.EnablePrivileges = $true
$win32OS.win32shutdown(8)

The following PowerShell code sample uses the EnableAllPrivileges from get-wmiobject cmdlet to achieve the proper priviliges.

$win32OS = get-wmiobject win32_operatingsystem -computername $computername -EnableAllPrivileges
$win32OS.win32shutdown(8)

The following VB.NET sample code uses the Shutdown method to reboot or log off a system.

Dim

testResult AsSingle

Dim WMIServiceObject, ComputerObject AsObject 

'Now get some privileges 

WMIServiceObject = GetObject(
"Winmgmts:{impersonationLevel=impersonate,(Debug,Shutdown)}")
ForEach ComputerObject In WMIServiceObject.InstancesOf("Win32_OperatingSystem") 
    testResult = ComputerObject.Win32Shutdown(2 + 4, 0) 
    'reboot
    'testResult = ComputerObject.Win32Shutdown(0, 0) 'logoff 
    ' testResult = ComputerObject.Win32Shutdown(8 + 4, 0) 'shutdown 

If testResult <> 0 Then 

MsgBox("Sorry, an error has occurred while trying to perform selected operation") 

Else 

'Operation selected in statement above if condition would be carried out 

EndIf 

Next

Requirements

Requirement	Value
Minimum supported client	Windows Vista
Minimum supported server	Windows Server 2008
Namespace	Root\CIMV2
MOF	CIMWin32.mof
DLL	CIMWin32.dll