The CommandLineEventConsumer class starts an arbitrary process in the local system when an event is delivered to it. This class is one of the standard event consumers that WMI provides. For more information, see Monitoring and Responding to Events with Standard Consumers.

Note  When using the CommandLineEventConsumer class, secure the executable that you want to start. If the executable is not in a secure location, or secured with a strong access control list (ACL), an unauthorized user can replace your executable with a malicious executable. For more information about ACLs, visit the Security section of the Microsoft Windows Software Development Kit (SDK), and see Creating a Security Descriptor for a New Object.

class CommandLineEventConsumer : __EventConsumer
{
  string CommandLineTemplate;
  boolean CreateNewConsole = False;
  boolean CreateNewProcessGroup = True;
  boolean CreateSeparateWowVdm = False;
  boolean CreateSharedWowVdm = False;
  string DesktopName;
  string ExecutablePath;
  uint32 FillAttributes;
  boolean ForceOffFeedback = False;
  boolean ForceOnFeedback = False;
  uint32 KillTimeout = 0;
  string Name;
  sint32 Priority = 0x20;
  boolean RunInteractively = False;
  uint32 ShowWindowCommand;
  boolean UseDefaultErrorMode = False;
  string WindowTitle;
  string WorkingDirectory;
  uint32 XCoordinate;
  uint32 XNumCharacters;
  uint32 XSize;
  uint32 YCoordinate;
  uint32 YNumCharacters;
  uint32 YSize;
};

Methods

The CommandLineEventConsumer class does not define any methods.

Properties

The CommandLineEventConsumer class defines the following properties.

CommandLineTemplate

Data type: string
Access type: Read/write
Qualifiers: Template

Standard string template that specifies the process to be started. This property can be NULL, and the ExecutablePath property is used as the command line.

CreateNewConsole

Data type: boolean
Access type: Read/write

Not used. If a value is assigned to this property, a tracing message is generated. For more information, see Tracing WMI Activity.

Windows Server 2003, Windows XP, Windows 2000, and Windows NT 4.0:  A message is logged to Wbemess.log. For more information, see WMI Log Files.

CreateNewProcessGroup

Data type: boolean
Access type: Read/write

If True, the new process is the root process of a new process group. The process group includes all processes that are descendants of this root process. The process identifier of the new process group is the same as this process identifier. Process groups are used by the GenerateConsoleCtrlEvent method to enable sending a CTRL+C or CTRL+BREAK signal to a group of console processes.

CreateSeparateWowVdm

Data type: boolean
Access type: Read/write

If True, the new process runs in a private Virtual DOS Machine (VDM). This is only valid when starting an application running on a 16-bit Windows operating system. If set to False, all applications running on a 16-bit Windows operating system run as threads in a single, shared VDM. For more information, see the Remarks section of this topic.

CreateSharedWowVdm

Data type: boolean
Access type: Read/write

If True, the CreateProcess method runs the new process in the shared Virtual DOS Machine (VDM). This property can override the DefaultSeparateVDM switch in the Windows section of Win.ini if set to True. For more information, see the Remarks section of this topic.

DesktopName

Data type: string
Access type: Read/write

Not used. If a value is assigned to this property a tracing message is generated. For more information, see Tracing WMI Activity.

Windows Server 2003, Windows XP, Windows 2000, and Windows NT 4.0:  A message is logged to Wbemess.log.

ExecutablePath

Data type: string
Access type: Read-only

Module to execute. The string can specify the full path and file name of the module to execute, or it can specify a partial name. If a partial name is specified, the current drive and current directory are assumed.

The ExecutablePath property can be NULL. In that case, the module name must be the first white space-delimited token in the CommandLineTemplate property value. If using a long file name that contains a space, use quoted strings to indicate where the file name ends and the arguments begin—to clarify the file name.

Note  Because the CommandLineTemplate property can be a template where the module to execute is supplied by a variable, a NULLExecutablePath property permits the module that is specified in the parameter to execute, and then it is out of your control. Always set the ExecutablePath property in the CommandLineEventConsumer registration to include the required executable, which avoids overwriting by events parameters. If you must use a template and variable to specify the module to execute, be careful about who is granted full write privilege in the namespace.

FillAttributes

Data type: uint32
Access type: Read/write

Initial text and background colors, if a new console window is created in a console application. This property is ignored in a GUI application. The value can be any combination of the following values.

Value	Meaning
1 0x1	blue foreground
2 0x2	green foreground
4 0x4	red foreground
8 0x8	foreground intensity
16 0x10	blue background
32 0x20	green background
64 0x40	red background
128 0x80	background intensity

For example, the following combinations produce red text on a white background:

0x4 | 0x40 | 0x20 | 0x10

– or –

0x74

ForceOffFeedback

Data type: boolean
Access type: Read/write

If True, the feedback cursor is forced off while the process is starting. The normal cursor is displayed.

ForceOnFeedback

Data type: boolean
Access type: Read/write

If True, the cursor is in feedback mode for two seconds after CreateProcess is called. During those two seconds, if the process makes the first GUI call, the system gives five more seconds to the process. During those five seconds, if the process shows a window, the system gives another five seconds to the process to finish drawing the window.

KillTimeout

Data type: uint32
Access type: Read/write

Number, in seconds, that the WMI service waits before killing a process—0 (zero) indicates a process is not to be killed. Killing a process prevents a process from running indefinitely.

Name

Data type: string
Access type: Read/write
Qualifiers: Key

Unique name of a consumer.

Priority

Data type: sint32
Access type: Read/write

Scheduling priority level of the process threads. The following table lists the priority levels available.

Priority	Meaning
32 0x20	Indicates a normal process without scheduling needs.
64 0x40	Indicates a process whose threads 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.
128 0x80	Indicates a process that performs high-priority, time critical tasks. The threads of a high-priority class process preempts the threads of normal-priority or idle-priority class processes. An example is the Task List, which must respond quickly when called by the user—regardless of the load on the system. Use extreme care when using the high-priority class, because a CPU-bound application with a high-priority class can use nearly all available cycles.
256 0x100	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 operating system processes that perform important tasks. For example, a real-time process that executes for more than a brief interval can cause disk caches not to flush, or cause the mouse to be unresponsive.

RunInteractively

Data type: boolean
Access type: Read/write

If True, the process is launched in the interactive WinStation. If False, the process is launched in the default service WinStation. This property overrides the DesktopName property. This property is only used locally, and only if the interactive user is the same user who set up the consumer.

Starting with Windows Vista, the process running the CommandLineEventConsumer instance is started under the LocalSystem account and is in session 0. Services which run in session 0 cannot interact with user sessions.

Windows Server 2003, Windows XP, Windows 2000, and Windows NT 4.0:  If the user logon is through a terminal services connection, the CommandLineEventConsumer process does not run interactively.

ShowWindowCommand

Data type: uint32
Access type: Read/write

Window show state.

Value	Meaning
SW_HIDE 0 0x0	Hides a window and activates a different window.
SW_SHOWNORMAL 1 0x1	Activates and displays a window. If a window is minimized or maximized, the system restores it to its original size and position. An application should specify this flag when displaying a window for the first time.
SW_SHOWMINIMIZED 2 0x2	Activates a window and displays it as a minimized window.
SW_SHOWMAXIMIZED 3 0x3	Activates a window and displays it as a maximized window.
SW_SHOWNOACTIVATE 4 0x4	Displays a window in its most recent size and position. This value is similar to SW_SHOWNORMAL, except the window is not activated.
SW_SHOW 5 0x5	Activates a window and displays it in its current size and position.
SW_MINIMIZE 6 0x6	Minimizes a window and activates the next top-level window.
SW_SHOWMINNOACTIVE 7 0x7	Displays a window as a minimized window.
SW_SHOWNA 8 0x8	Displays a window in its current size and position. This value is similar to SW_SHOW, except the window is not activated.
SW_RESTORE 9 0x9	Activates and displays a window to its most recent size and position. An application should specify this value when restoring a minimized window.
SW_SHOWDEFAULT 10 0xA	Sets the show state based on the SW_ value specified in the STARTUPINFO structure passed to the CreateProcess function by the program that starts an application.

UseDefaultErrorMode

Data type: boolean
Access type: Read/write

If True, the default error mode is used.

WindowTitle

Data type: string
Access type: Read/write
Qualifiers: Template

Title that appears on the title bar of the process. This property is ignored for GUI applications.

WorkingDirectory

Data type: string
Access type: Read/write

Working directory for this process.

XCoordinate

Data type: uint32
Access type: Read/write

X-offset, in pixels, from the left edge of the screen to the left edge of the window, if a new window is created.

XNumCharacters

Data type: uint32
Access type: Read/write

Screen buffer width, in character columns, if a new console window is created. This property is ignored in a GUI process.

XSize

Data type: uint32
Access type: Read/write

Width, in pixels, of a new window, if a new window is created.

YCoordinate

Data type: uint32
Access type: Read/write

Y-offset, in pixels, from the top edge of the screen to the top edge of the window, if a new window is created.

YNumCharacters

Data type: uint32
Access type: Read/write

Screen buffer height, in character rows, if a new console window is created. This property is ignored in a GUI process.

YSize

Data type: uint32
Access type: Read/write

Height, in pixels, of the new window, if a new window is created.

Remarks

The CommandLineEventConsumer class is derived from the __EventConsumer abstract class.

The CreateSeparateWowVdm property indicates whether or not the new process runs in a private Virtual DOS Machine (VDM). The advantage of running separately is that a crash only terminates the single VDM. Programs running in distinct VDMs continue to function normally, and the 16-bit Windows-based applications running in separate VDMs have separate input queues. This means that if one application stops responding momentarily, the applications in separate VDMs continue to receive input. The disadvantage of running separately is that it takes significantly more memory to do so. You should set this property to True only if the user requests that 16-bit Windows-based applications run in their own VDM.

Note  The CommandLineEventConsumer uses the CreateProcess method internally, and passes the ExecutablePath and CommandLineTemplate properties as the lpApplicationName and lpCommandLine parameters. The following Managed Object Format (MOF) code example does not use CommandLineEventConsumer correctly.

instance of CommandLineEventConsumer
{
  ExecutablePath = "C:\\windows\\system32\\cscript.exe";
  CommandLineTemplate = "C:\\scripts\\MyScript.js param1 param2";
};

The CreateProcess method passes lpCommandLine as argv[0], argv[1], and so on. Because argv[0] for 16-bit applications used to be reserved for the executable file name, the previous MOF code results in the process being created as though the following command is entered at the command prompt: c:\windows\system32\cscript.exe param1 param2.

The previous command does not succeed because Cscript.exe does not look at argv[0], and so it does not recognize that it does not contain its own name, but something else (c:\\scripts\\MyScript.js). The following example identifies the recommended use of CommandLineEventConsumer.

instance of CommandLineEventConsumer
{
  ExecutablePath = "C:\\windows\\system32\\cscript.exe";
  CommandLineTemplate = "C:\\windows\\system32\\cscript.exe"
    "C:\\scripts\\MyScript.js param1 param2";
};

The previous use of CommandLineEventConsumer results in the process created as though the following command was entered at the command prompt: c:\windows\system32\cscript.exe c:\scripts\MyScript.js param1 param2

Because c:\\scripts\\MyScript.js is now argv[1], it is seen by Cscript.exe and the command succeeds.

For more information, see the CreateProcess function.

Examples

For script code examples, see WMI Tasks for Scripts and Applications and the TechNet ScriptCenter Script Repository.

For C++ code examples, see WMI C++ Application Examples.

Examples

For an example of using CommandLineEventConsumer to create a consumer, see Running a Program from the Command Line Based on an Event.

Requirements

See Also

Standard Consumer Classes
Monitoring and Responding to Events with Standard Consumers
Creating a Logical Consumer
Receiving Events At All Times
__EventConsumer

Send comments about this topic to Microsoft

Build date: 8/20/2008