CommandLineEventConsumer class
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.
Syntax
[AMENDMENT]
class CommandLineEventConsumer : __EventConsumer
{
uint8 CreatorSID[];
string MachineName;
uint32 MaximumQueueSize;
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;
uint32 FillAttribute;
};
Members
The CommandLineEventConsumer class has these types of members:
Properties
The CommandLineEventConsumer class has these properties.
-
CommandLineTemplate
-
-
Data type: string
-
Access type: Read-only
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-only
Not used. If a value is assigned to this property, a tracing message is generated. For more information, see Tracing WMI Activity.
-
-
CreateNewProcessGroup
-
-
Data type: boolean
-
Access type: Read-only
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-only
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-only
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.
-
-
CreatorSID
-
-
Data type: uint8 array
-
Access type: Read-only
Security identifier (SID) that uniquely identifies the user who creates a filter. WMI stores the SID of the user who creates an instance of __EventConsumer or the Administrator SID, depending on the operating system. For more information, see Binding an Event Filter with a Logical Consumer and Monitoring and Responding to Events with Standard Consumers.
This property is inherited from __EventConsumer.
-
-
DesktopName
-
-
Data type: string
-
Access type: Read-only
Not used. If a value is assigned to this property a tracing message is generated. For more information, see Tracing WMI Activity.
-
-
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 NULL ExecutablePath 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.
-
-
FillAttribute
-
-
Data type: uint32
-
Access type: Read-only
Specifies the initial text and background colors if a new console window is created in a console application
-
-
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.
-
-
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-only
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-only
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-only
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.
MachineName
-
Data type: string
-
Access type: Read-only
Name of the computer to which Windows Management Instrumentation (WMI) sends events.
This property is inherited from __EventConsumer.
MaximumQueueSize
-
Data type: uint32
-
Access type: Read-only
Maximum queue for a specific consumer, in bytes.
This property is inherited from __EventConsumer.
Name
-
Data type: string
-
Access type: Read-only
-
Qualifiers: key
Unique name of a consumer.
Priority
-
Data type: sint32
-
Access type: Read-only
Scheduling priority level of the process threads. The following list lists the priority levels available.
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-only
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.
ShowWindowCommand
-
Data type: uint32
-
Access type: Read-only
Window show state. It can be any of the values that can be specified in the nCmdShow parameter for the ShowWindow function.
UseDefaultErrorMode
-
Data type: boolean
-
Access type: Read-only
If True, the default error mode is used.
WindowTitle
-
Data type: string
-
Access type: Read-only
Title that appears on the title bar of the process. This property is ignored for GUI applications.
WorkingDirectory
-
Data type: string
-
Access type: Read-only
Working directory for this process.
XCoordinate
-
Data type: uint32
-
Access type: Read-only
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-only
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-only
Width, in pixels, of a new window, if a new window is created.
YCoordinate
-
Data type: uint32
-
Access type: Read-only
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-only
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-only
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 an example of using CommandLineEventConsumer to create a consumer, see Running a Program from the Command Line Based on an Event.
Requirements
| Requirement | Value |
|---|---|
| Minimum supported client |
Windows Vista |
| Minimum supported server |
Windows Server 2008 |
| Namespace |
Root\subscription |
| MOF |
|
| DLL |
|