Win32_ProcessStartup class

The Win32_ProcessStartup abstract WMI class represents the startup configuration of a Windows-based process. The class is defined as a method type definition, which means that it is only used for passing information to the Create method of the Win32_Process class.

The following syntax is simplified from Managed Object Format (MOF) code and includes all inherited properties.

Syntax

[Abstract, UUID("{8502C4DB-5FBB-11D2-AAC1-006008C78BC7}"), AMENDMENT]
class Win32_ProcessStartup : Win32_MethodParameterClass
{
  uint32 CreateFlags;
  string EnvironmentVariables[];
  uint16 ErrorMode = 1;
  uint32 FillAttribute;
  uint32 PriorityClass;
  uint16 ShowWindow;
  string Title;
  string WinstationDesktop;
  uint32 X;
  uint32 XCountChars;
  uint32 XSize;
  uint32 Y;
  uint32 YCountChars;
  uint32 YSize;
};

Members

The Win32_ProcessStartup class has these types of members:

Properties

The Win32_ProcessStartup class has these properties.

CreateFlags

Data type: uint32

Access type: Read/write

Qualifiers: MappingStrings ("Win32API|Process and Thread Functions|CreateProcess|dwCreationFlags")

Additional values that control the priority class and the creation of the process. The following creation values can be specified in any combination, except as noted.

Debug_Process (1)

If this flag is set, the calling process is treated as a debugger, and the new process is being debugged. The system notifies the debugger of all debug events that occur in the process being debugged.

Debug_Only_This_Process (2)

If this flag is not set and the calling process is being debugged, the new process becomes another process being debugged. If the calling process is not a process of being debugged, no debugging-related actions occur.

Create_Suspended (4)

The primary thread of the new process is created in a suspended state and does not run until the ResumeThread method is called.

Detached_Process (8)

For console processes, the new process does not have access to the console of the parent process. This flag cannot be used if the Create_New_Console flag is set.

Create_New_Console (16)

This new process has a new console, instead of inheriting the parent console. This flag cannot be used with the Detached_Process flag.

Create_New_Process_Group (512)

This new process is the root process of a new process group. The process group includes all of the processes that are descendants of this root process. The process identifier of the new process group is the same as the process identifier that is returned in the ProcessID property of the Win32_Process class. Process groups are used by the GenerateConsoleCtrlEvent method to enable the sending of either a CTRL+C signal or a CTRL+BREAK signal to a group of console processes.

Create_Unicode_Environment (1024)

The environment settings listed in the EnvironmentVariables property use Unicode characters. If this flag is not set, the environment block uses ANSI characters.

Create_Default_Error_Mode (67108864)

Newly created processes are given the system default error mode of the calling process instead of inheriting the error mode of the parent process. This flag is useful for multithreaded shell applications that run with hard errors disabled.

CREATE_BREAKAWAY_FROM_JOB (16777216)

Used for the created process not to be limited by the job object.

EnvironmentVariables

Data type: string array

Access type: Read/write

Qualifiers: MappingStrings ("Win32Registry|HKEY_CURRENT_USER\\Environment")

List of settings for the configuration of a computer. Environment variables specify search paths for files, directories for temporary files, application-specific options, and other similar information. The system maintains a block of environment settings for each user and one for the computer. The system environment block represents environment variables for all of the users of a specific computer. A user's environment block represents the environment variables that the system maintains for a specific user, and includes the set of system environment variables. By default, each process receives a copy of the environment block for its parent process. Typically, this is the environment block for the user who is logged on. A process can specify different environment blocks for its child processes.

ErrorMode

Data type: uint16

Access type: Read/write

Qualifiers: MappingStrings ("Win32API|Error Functions|SetErrorMode")

On some non-x86 processors, misaligned memory references cause an alignment fault exception. The No_Alignment_Fault_Except flag lets you control whether or not an operating system automatically fixes such alignment faults, or makes them visible to an application. On a millions of instructions per second (MIPS) platform, an application must explicitly call SetErrorMode with the No_Alignment_Fault_Except flag to have the operating system automatically fix alignment faults.

How an operating system processes several types of serious errors. You can specify that the operating system process errors, or an application can receive and process errors.

The default setting is for the operating system to make alignment faults visible to an application. Because the x86 platform does not make alignment faults visible to an application, the No_Alignment_Fault_Except flag does not make the operating system raise an alignment fault error—even if the flag is not set. The default state for SetErrorMode is to set all of the flags to 0 (zero).

(1)

Default

Fail_Critical_Errors (2)

If this flag is set, the operating system does not display the critical error handler message box when such an error occurs. Instead, the operating system sends the error to the calling process.

No_Alignment_Fault_Except (4)

If this flag is set, the operating system automatically fixes memory alignment faults and makes them invisible to the application. It does this for the calling and descendant processes. This flag applies to reduced instruction set computing (RISC) only, and has no effect on x86 processors.

No_GP_Fault_Error_Box (8)

If this flag is set, the operating system does not display the general protection (GP) fault message box when a GP error occurs. This flag should only be set by debugging applications that handle GP errors.

No_Open_File_Error_Box (16)

If this flag is set, the operating system does not display a message box when it fails to find a file. Instead, the error is returned to the calling process. This flag is currently ignored.

FillAttribute

Data type: uint32

Access type: Read/write

Qualifiers: MappingStrings ("Win32API|Process and Thread Structures|STARTUPINFO|dwFillAttribute")

The text and background colors if a new console window is created in a console application. These values are ignored in graphical user interface (GUI) applications. To specify both foreground and background colors, add the values together. For example, to have red type (4) on a blue background (16), set the FillAttribute to 20.

1

Foreground_Blue

2

Foreground_Green

4

Foreground_Red

8

Foreground_Intensity

16

Background_Blue

32

Background_Green

64

Background_Red

128

Background_Intensity

PriorityClass

Data type: uint32

Access type: Read/write

Qualifiers: MappingStrings ("Win32API|Process and Thread Structures|JOBOBJECT_BASIC_LIMIT_INFORMATION|PriorityClass")

Priority class of the new process. Use this property to determine the schedule priorities of the threads in the process. If the property is left null, the priority class defaults to Normal—unless the priority class of the creating process is Idle or Below_Normal. In these cases, the child process receives the default priority class of the calling process.

Normal (32)

Indicates a normal process with no special schedule needs.

Idle (64)

Indicates a process with threads that run only when the system is idle and are preempted by the threads of any process running in a higher priority class. An example is a screen saver. The idle priority class is inherited by child processes.

High (128)

Indicates a process that performs time-critical tasks that must be executed immediately to run correctly. The threads of a high-priority class process preempt the threads of normal-priority or idle-priority class processes. An example is Windows Task List, which must respond quickly when called by the user, regardless of the load on the operating system. Use extreme care when using the high-priority class, because a high-priority class CPU-bound application can use nearly all of the available cycles. Only a real-time priority preempts threads set to this level.

Realtime (256)

Indicates a process that has the highest possible priority. The threads of a real-time priority class process preempt the threads of all other processes—including high-priority threads and operating system processes performing important tasks. For example, a real-time process that executes for more than a very brief interval can cause disk caches not to flush, or cause a mouse to be unresponsive.

Below_Normal (16384)

Indicates a process that has a priority higher than Idle but lower than Normal.

Above_Normal (32768)

Indicates a process that has a priority higher than Normal but lower than High.

ShowWindow

Data type: uint16

Access type: Read/write

Qualifiers: MappingStrings ("Win32API|Process and Thread Structures|STARTUPINFO|wShowWindow")

How the window is displayed to the user. It can be any of the values that can be specified in the nCmdShow parameter for the ShowWindow function.

Title

Data type: string

Access type: Read/write

Qualifiers: MappingStrings ("Win32API|Process and Thread Structures|STARTUPINFO|lpTitle")

Text displayed in the title bar when a new console window is created; used for console processes. If NULL, the name of the executable file is used as the window title. This property must be NULL for GUI or console processes that do not create a new console window.

WinstationDesktop

Data type: string

Access type: Read/write

Qualifiers: MappingStrings ("Win32API|Process and Thread Structures|STARTUPINFO|lpDesktop")

The name of the desktop or the name of both the desktop and window station for the process. A backslash in the string indicates that the string includes both desktop and window station names. If WinstationDesktop is NULL, the new process inherits the desktop and window station of its parent process. If WinstationDesktop is an empty string, the process does not inherit the desktop and window station of its parent process. The system determines if a new desktop and window station must be created. A window station is a secure object that contains a clipboard, a set of global atoms, and a group of desktop objects. The interactive window station that is assigned to the logon session of the interactive user also contains the keyboard, mouse, and display device. A desktop is a secure object contained within a window station. A desktop has a logical display surface and contains windows, menus, and hooks. A window station can have multiple desktops. Only the desktops of the interactive window station can be visible and receive user input.

X

Data type: uint32

Access type: Read/write

Qualifiers: MappingStrings ("Win32API|Process and Thread Structures|STARTUPINFO|dwX")

The X offset of the upper left corner of a window if a new window is created—in pixels. The offsets are from the upper left corner of the screen. For GUI processes, the specified position is used the first time the new process calls CreateWindow to create an overlapped window if the X parameter of CreateWindow is CW_USEDEFAULT.

[!Note  X]
and Y cannot be specified independently.

 

XCountChars

Data type: uint32

Access type: Read/write

Qualifiers: MappingStrings ("Win32API|Process and Thread Structures|STARTUPINFO|XCountChars")

Screen buffer width in character columns. This property is used for processes that create a console window, and is ignored in GUI processes.

Note

XCountChars and YCountChars cannot be specified independently.

 

XSize

Data type: uint32

Access type: Read/write

Qualifiers: MappingStrings ("Win32API|Process and Thread Structures|STARTUPINFO|dwXSize")

Pixel width of a window if a new window is created. For GUI processes, this is only used the first time the new process calls CreateWindow to create an overlapped window if the nWidth parameter of CreateWindow is CW_USEDEFAULT.

Note

XSize and YSize cannot be specified independently.

 

Y

Data type: uint32

Access type: Read/write

Qualifiers: MappingStrings ("Win32API|Process and Thread Structures|STARTUPINFO|dwY")

Pixel offset of the upper-left corner of a window if a new window is created. The offsets are from the upper-left corner of the screen. For GUI processes, the specified position is used the first time the new process calls CreateWindow to create an overlapped window if the y parameter of CreateWindow is CW_USEDEFAULT.

[!Note  X]
and Y cannot be specified independently.

 

YCountChars

Data type: uint32

Access type: Read/write

Qualifiers: MappingStrings ("Win32API|Process and Thread Structures|STARTUPINFO|YCountChars")

Screen buffer height in character rows. This property is used for processes that create a console window, but is ignored in GUI processes.

Note

XCountChars and YCountChars cannot be specified independently.

 

YSize

Data type: uint32

Access type: Read/write

Qualifiers: MappingStrings ("Win32API|Process and Thread Structures|STARTUPINFO|dwYSize")

Pixel height of a window if a new window is created. For GUI processes, this is used only the first time the new process calls CreateWindow to create an overlapped window if the nWidth parameter of CreateWindow is CW_USEDEFAULT.

Note

XSize and YSize cannot be specified independently.

 

Remarks

This class is derived from Win32_MethodParameterClass.

Overview

The Win32_Process Create method enables you to configure startup options for any new process running on a computer. For example, you can configure a process so that it starts in a "hidden" window, which prevents a user from seeing, and possibly interrupting, it. If the process runs in a command window, you can configure the size, title, and foreground and background colors of the window.

Startup options are configured using the Win32_ProcessStartup class. Win32_ProcessStartup is a Method Type class; the Method Type class exists solely to pass information to a method. In this case, all the properties of an instance of Win32_ProcessStartup are passed to an instance of Win32_Process.

Using Win32_ProcessStartup

  1. Create an instance of Win32_ProcessStartup.
  2. Configure the properties of the new instance.
  3. Include the instance as part of the Win32_Process Create method.

For example, if you have created a Win32_ProcessStartup instance named objConfig, you would pass the object name in the Create method as follows:

errReturn = objProcess.Create("Database.exe", null, objConfig, intProcessID)

Examples

You can use the Win32_ProcessStartup class to configure various startup options for a process. These options include, but are not limited to, such things as creating a process in a hidden window and creating a higher-priority process. The following VBScript creates a process in a hidden window.

Const HIDDEN_WINDOW = 12
strComputer = "."
Set objWMIService = GetObject("winmgmts:{impersonationLevel=impersonate}!\\" & strComputer & "\root\cimv2")
Set objStartup = objWMIService.Get("Win32_ProcessStartup")
Set objConfig = objStartup.SpawnInstance_
objConfig.ShowWindow = HIDDEN_WINDOW
Set objProcess = GetObject("winmgmts:root\cimv2:Win32_Process")
errReturn = objProcess.Create("Notepad.exe", null, objConfig, intProcessID)

The following VBScript creates a higher-priority process.

Const ABOVE_NORMAL = 32768
strComputer = "."
Set objWMIService = GetObject("winmgmts:{impersonationLevel=impersonate}!\\" & strComputer & "\root\cimv2")
Set objStartup = objWMIService.Get("Win32_ProcessStartup")
Set objConfig = objStartup.SpawnInstance_
objConfig.PriorityClass = ABOVE_NORMAL
Set objProcess = GetObject("winmgmts:root\cimv2:Win32_Process")
objProcess.Create "Database.exe", Null, objConfig, intProcessID

The following VBScript code example creates a Notepad process on the local computer. Win32_ProcessStartup is used to configure the process settings.

Const SW_NORMAL = 1
strComputer = "."
strCommand = "Notepad.exe" 
Set objWMIService = GetObject("winmgmts:{impersonationLevel=impersonate}!\\" & strComputer & "\root\cimv2")

' Configure the Notepad process to show a window
Set objStartup = objWMIService.Get("Win32_ProcessStartup")
Set objConfig = objStartup.SpawnInstance_
objConfig.ShowWindow = SW_NORMAL

' Create Notepad process
Set objProcess = objWMIService.Get("Win32_Process")
intReturn = objProcess.Create _
    (strCommand, Null, objConfig, intProcessID)
If intReturn <> 0 Then
    Wscript.Echo "Process could not be created." & vbNewLine & _
                 "Command line: " & strCommand & vbNewLine & _
                 "Return value: " & intReturn
Else
    Wscript.Echo "Process created." & vbNewLine & _
                 "Command line: " & strCommand & vbNewLine & _
                 "Process ID: " & intProcessID
End If

Requirements

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

See also

Win32_MethodParameterClass

Operating System Classes

Win32_Process

__ProviderHostQuotaConfiguration

WMI Tasks: Processes