RequestStateChange method of the CIM_EnabledLogicalElement class

  • Article

Requests that the state of the element be changed to the value specified in the RequestedState parameter. When the requested state change takes place, the EnabledState and RequestedState of the element will be the same. Invoking the RequestStateChange method multiple times could result in earlier requests being overwritten or lost.

Syntax

uint32 RequestStateChange(
  [in]  uint16              RequestedState,
  [out] CIM_ConcreteJob REF Job,
  [in]  datetime            TimeoutPeriod
);

Parameters

RequestedState [in]

The state requested for the element. This information will be placed into the RequestedState property of the instance if the return code of the RequestStateChange method is 0 ('Completed with No Error'), or 4096 (0x1000) ('Job Started'). Refer to the description of the EnabledState and RequestedState properties for the detailed explanations of the RequestedState values.

Start (2)

Changes the state to 'Running'.

Suspend (3)

Stops the job temporarily. The intention is to subsequently restart the job with 'Start'. It might be possible to enter the 'Service' state while suspended. (This is job-specific.)

Terminate (4)

Stops the job cleanly, saves data, preserves the state, and shuts down all underlying processes in an orderly manner.

Kill (5)

Terminates the job immediately with no requirement to save data or preserve the state.

Service (6)

Puts the job into a vendor-specific service state. It might be possible to restart the job.

DMTF Reserved (7..32767)

Vendor Reserved (32768..65535)

Job [out]

May contain a reference to the CIM_ConcreteJob created to track the state transition initiated by the method invocation.

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 Null 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 4098 (Use Of Timeout Parameter Not Supported) must be returned.

Return value

Returns a 0 on success; otherwise, returns an error.

Completed with No Error (0)

Not Supported (1)

Unknown or Unspecified Error (2)

Cannot complete within Timeout Period (3)

Failed (4)

Invalid Parameter (5)

In Use (6)

DMTF Reserved (..)

Method Parameters Checked - Job Started (4096)

Invalid State Transition (4097)

Use of Timeout Parameter Not Supported (4098)

Busy (4099)

Method Reserved (4100..32767)

Vendor Specific (32768..65535)

Requirements

Requirement Value
Minimum supported client
 Windows 8.1
Minimum supported server
 Windows Server 2012 R2
Namespace
 Root\virtualization\v2
MOF
WindowsVirtualization.V2.mof
DLL
Vmms.exe

See also

CIM_EnabledLogicalElement