Requests that the state of the computer system be changed to the value specified in the
RequestedState parameter. Invoking the
RequestStateChange method
multiple times could result in earlier requests being overwritten or lost. If 0 is returned, then the task
completed successfully. Any other return code indicates an error condition.
While the state change is in progress, the RequestedState property is changed
to the value of the RequestedState parameter.
Syntax
uint32 RequestStateChange(
[in] uint16 RequestedState,
[out] CIM_ConcreteJob REF Job,
[in] datetime TimeoutPeriod
);
Parameters
- RequestedState [in]
-
The new state. The following are possible values.
| Value | Meaning |
- Enabled
- 2
| Turns the VM on.
|
- Disabled
- 3
| Turns the VM off.
|
- Reboot
- 10
| A hard reset of the VM.
|
- Reset
- 11
| For future use.
|
- DMTF Reserved
- 13–32767
| Reserved.
|
- Paused
- 32768
| Pauses the VM.
|
- Suspended
- 32769
| Saves the state of the VM.
|
- Vendor Reserved
- 32770–65535
| Reserved.
|
- Job [out]
-
An optional reference to CIM_ConcreteJob that is
returned if the operation is executed asynchronously. If present, the returned reference can be used to monitor
progress and obtain the result of the method.
- TimeoutPeriod [in]
-
A timeout period that specifies the maximum amount of time that the client expects the transition to the new
state to take. The interval format must be used to specify the timeout period. A value of 0 or a null parameter
indicates that the client has no time requirements for the transition. If this property does not contain 0 or
null and the implementation does not support this parameter, a return code of
"Use Of Timeout Parameter Not Supported" must be returned.
Return Value
This method returns one of the following values.
- Completed with No Error (0)
- DMTF Reserved (7–4095)
- Method Parameters Checked - Transition Started (4096)
- Failed (32768)
- Access Denied (32769)
- Not Supported (32770)
- Status is unknown (32771)
- Timeout (32772)
- Invalid parameter (32773)
- System is in use (32774)
- Invalid state for this operation (32775)
- Incorrect data type (32776)
- System is not available (32777)
- Out of memory (32777)
Remarks
Access to the Msvm_ComputerSystem class
might be restricted by UAC Filtering. For more information, see
User Account Control and WMI.
Examples
The following C# example starts or disables a virtual machine. The referenced utilities can be found in
Common Utilities for the Virtualization Samples.
using System;
using System.Management;
namespace HyperVSamples
{
class RequestStateChangeClass
{
static void RequestStateChange(string vmName, string action)
{
ManagementScope scope = new ManagementScope(@"root\virtualization", null);
ManagementObject vm = Utility.GetTargetComputer(vmName, scope);
ManagementBaseObject inParams = vm.GetMethodParameters("RequestStateChange");
const int Enabled = 2;
const int Disabled = 3;
if (action.ToLower() == "start")
{
inParams["RequestedState"] = Enabled;
}
else if (action.ToLower() == "stop")
{
inParams["RequestedState"] = Disabled;
}
else
{
throw new Exception("Wrong action is specified");
}
ManagementBaseObject outParams = vm.InvokeMethod("RequestStateChange", inParams, null);
if ((UInt32)outParams["ReturnValue"] == ReturnCode.Started)
{
if (Utility.JobCompleted(outParams, scope))
{
Console.WriteLine("{0} state was changed successfully.", vmName);
}
else
{
Console.WriteLine("Failed to change virtual system state");
}
}
else if ((UInt32)outParams["ReturnValue"] == ReturnCode.Completed)
{
Console.WriteLine("{0} state was changed successfully.", vmName);
}
else
{
Console.WriteLine("Change virtual system state failed with error {0}", outParams["ReturnValue"]);
}
}
static void Main(string[] args)
{
if (args != null && args.Length != 1)
{
Console.WriteLine("Usage: GetVirtualMachineDNSName vmName action");
Console.WriteLine("action: start|stop");
return;
}
RequestStateChange(args[0], args[1]);
}
}
}
The following VBScript example starts or disables a virtual machine.
dim objWMIService
dim fileSystem
const JobStarting = 3
const JobRunning = 4
const JobCompleted = 7
const wmiStarted = 4096
const Enabled = 2
const Disabled = 3
Main()
'-----------------------------------------------------------------
' Main rountine
'-----------------------------------------------------------------
Sub Main()
set fileSystem = Wscript.CreateObject("Scripting.FileSystemObject")
strComputer = "."
set objWMIService = GetObject("winmgmts:\\" & strComputer & "\root\virtualization")
set objArgs = WScript.Arguments
if WScript.Arguments.Count = 2 then
vmName= objArgs.Unnamed.Item(0)
action = objArgs.Unnamed.Item(1)
else
WScript.Echo "usage: cscript StartVM.vbs vmName start|stop"
WScript.Quit
end if
set computerSystem = GetComputerSystem(vmName)
if RequestStateChange(computerSystem, action) then
WriteLog "Done"
WScript.Quit(0)
else
WriteLog "RequestStateChange failed"
WScript.Quit(1)
end if
End Sub
'-----------------------------------------------------------------
' Retrieve Msvm_VirtualComputerSystem from base on its ElementName
'
'-----------------------------------------------------------------
Function GetComputerSystem(vmElementName)
On Error Resume Next
query = Format1("select * from Msvm_ComputerSystem where ElementName = '{0}'", vmElementName)
set GetComputerSystem = objWMIService.ExecQuery(query).ItemIndex(0)
if (Err.Number <> 0) then
WriteLog Format1("Err.Number: {0}", Err.Number)
WriteLog Format1("Err.Description:{0}",Err.Description)
WScript.Quit(1)
end if
End Function
'-----------------------------------------------------------------
' Turn on a virtual machine
'-----------------------------------------------------------------
Function RequestStateChange(computerSystem, action)
WriteLog Format2("RequestStateChange({0}, {1})", computerSystem.ElementName, action)
RequestStateChange = false
set objInParam = computerSystem.Methods_("RequestStateChange").InParameters.SpawnInstance_()
if action = "start" then
objInParam.RequestedState = Enabled
else
objInParam.RequestedState = Disabled
end if
set objOutParams = computerSystem.ExecMethod_("RequestStateChange", objInParam)
if (WMIMethodStarted(objOutParams)) then
if (WMIJobCompleted(objOutParams)) then
WriteLog Format1("VM {0} was started successfully", computerSystem.ElementName)
RequestStateChange = true
end if
end if
End Function
'-----------------------------------------------------------------
' Handle wmi return values
'-----------------------------------------------------------------
Function WMIMethodStarted(outParam)
WMIMethodStarted = false
if Not IsNull(outParam) then
wmiStatus = outParam.ReturnValue
if wmiStatus = wmiStarted then
WMIMethodStarted = true
end if
end if
End Function
'-----------------------------------------------------------------
' Handle wmi Job object
'-----------------------------------------------------------------
Function WMIJobCompleted(outParam)
dim WMIJob
set WMIJob = objWMIService.Get(outParam.Job)
WMIJobCompleted = true
jobState = WMIJob.JobState
while jobState = JobRunning or jobState = JobStarting
WScript.Sleep(1000)
set WMIJob = objWMIService.Get(outParam.Job)
jobState = WMIJob.JobState
wend
if (jobState <> JobCompleted) then
WriteLog Format1("ErrorDescription:{0}", WMIJob.ErrorDescription)
WMIJobCompleted = false
end if
End Function
'-----------------------------------------------------------------
' Create the console log files.
'-----------------------------------------------------------------
Sub WriteLog(line)
dim fileStream
set fileStream = fileSystem.OpenTextFile(".\StartVM.log", 8, true)
WScript.Echo line
fileStream.WriteLine line
fileStream.Close
End Sub
'------------------------------------------------------------------------------
' The string formating functions to avoid string concatenation.
'------------------------------------------------------------------------------
Function Format2(myString, arg0, arg1)
Format2 = Format1(myString, arg0)
Format2 = Replace(Format2, "{1}", arg1)
End Function
'------------------------------------------------------------------------------
' The string formating functions to avoid string concatenation.
'------------------------------------------------------------------------------
Function Format1(myString, arg0)
Format1 = Replace(myString, "{0}", arg0)
End Function
Requirements
| Minimum supported client | None supported |
| Minimum supported server | Windows Server 2008 |
| MOF | WindowsVirtualization.mof |
| Namespace | \\.\Root\Virtualization |
See Also
- Msvm_ComputerSystem
Send comments about this topic to Microsoft
Build date: 10/8/2009