CreateProcess Function

CreateProcess

The CreateProcess function creates a new process and its primary thread. The new process runs the specified executable file in the security context of the calling process.

If the calling process is impersonating another user, the new process uses the token for the calling process, not the impersonation token. To run the new process in the security context of the user represented by the impersonation token, use the CreateProcessAsUser.

Long CreateProcess (flags, CommandLine)

Arguments:

flags
The flags parameter modify the default behavior of CreateProcess.
The flags parameter can be 0 to assume all defaults, or one or more of the following flags combined with the Or operator.

CP_HIDE Hides the window associated with the application.

CP_ASYNC Runs the process asynchronously.

CP_WAIT_IDLE The CP_WAIT_IDLE flag causes the script to wait until the specified process is waiting for user input with no input pending, or until and internal 15 second timeout occurs.
Note: Must be be used with CP_ASYNC.

CommandLine
String that specifies the command line to execute. The maximum length of this string is 32K characters.

The first white-space – delimited token of the command line specifies the module name. If you are using a long file name that contains a space, use quoted strings to indicate where the file name ends and the arguments begin. If the file name does not contain an extension, each of .com, .exe, .cmd, and .bat are tried in order. If the file name does not contain a directory path, the system searches for the executable file in the following sequence:

The directory from which the application loaded.

The current directory for the parent process.

The 32-bit Windows system directory.

The 16-bit Windows system directory.

The Windows directory.

The directories that are listed in the PATH environment variable.

Returns:

The return value from a synchronous CreateProcess (CP_ASYNC not specified in flags) is the exit status of the new process. The return value from an asynchronous CreateProcess (CP_ASYNC specified in flags) is zero if the process was successfully spawned.

The exit status is 0 if the process terminated normally. A spawned process can set the exit status to a nonzero value if the spawned process specifically calls the exit routine with a nonzero argument. If the new process did not explicitly set a positive exit status, a positive exit status indicates an abnormal exit with an abort or an interrupt. A return value of –1 indicates an error (the new process is not started).

Remarks:

When CreateProcess is called with the CP_ASYNC flag, CreateProcess does not wait for the new process to finish initialization before returning. This lag between the time a process is created and the time at which the new process is fully initialized can cause some problems if you are trying to initiate communication with the new process too soon.
If your script must communicate or otherwise interact with a freshly the spawned process, it is recommended you use the CP_WAIT_IDLE flag to insure the process has entered a quiescent state.

This script (CreateProcess.vbs) shows how to call CreateProcess and how to capture the return code.
Sub main(args)
    Dim commandline
    commandline = args
    Dim exit_code
    exit_code = TGCtrl.CreateProcess(0,commandline)
    If exit_code = -1 Then 
    	TGCtrl.Print("Process failed to start!") 
    Else 
	TGCtrl.Print("Process returned " & exit_code)
    End If
End Sub

Requirements:

Version 1.0

See Also:

CreateProcessAsUser, ImpersonateLoggedOnUser, LogonUser
CreateProcess.vbs and CreateProcessAsUser.vbs in the TaskGhost\Scripts directory.

CP_HIDE	Hides the window associated with the application.
CP_ASYNC	Runs the process asynchronously.
CP_WAIT_IDLE	The CP_WAIT_IDLE flag causes the script to wait until the specified process is waiting for user input with no input pending, or until and internal 15 second timeout occurs. Note: Must be be used with CP_ASYNC.