Bewerken

Delen via


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
Wbemcons.mof
DLL
Wbemcons.dll

See also

Standard Consumer Classes

Monitoring and Responding to Events with Standard Consumers

Creating a Logical Consumer

Receiving Events At All Times

__EventConsumer