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

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;
};

Members

The CommandLineEventConsumer class has these types of members:

Properties

The CommandLineEventConsumer class has these 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 and Windows XP:  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 and Windows XP:  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 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.

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.

ValueMeaning
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.

PriorityMeaning
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 and Windows XP:  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.

ValueMeaning
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.

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

Requirements

Minimum supported client

Windows XP

Minimum supported server

Windows Server 2003

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

 

 

Show:
© 2014 Microsoft. All rights reserved.