Name
RunProgramInGuest
Description
HRESULT
RunProgramInGuest([in] BSTR guestProgramName,
[in] BSTR commandLineArgs,
[in] LONG options,
[in] IVixHandle* propertyList,
[in] ICallback* jobDoneCallback,
[out,retval] IJob** runJob);
This function runs a program in the guest operating system. The program must
be stored on a file system available to the guest before calling this function.
Parameters
- guestProgramName
-
The path name of an executable file on the guest
operating system.
- commandLineArgs
-
A string to be passed as command line arguments to the
executable identified by guestProgramName.
- options
-
Run options for the program. See the remarks below.
- propertyListHandle
-
Must be NULL (C++), null (C#), or Nothing (VB).
- jobDoneCallback
-
An ICallback instance that will be called when the
operation is complete.
- runJob
-
Returns an IJob object that describes the state of this asynchronous operation.
Return Value
HRESULT
Remarks
- This function runs a program in the guest operating system. The program must
be stored on a file system available to the guest before calling this
function.
- The current working directory for the program in the guest is not defined.
Absolute paths should be used for files in the guest, including
guestProgramName and any command-line arguments.
- You must call VM::LoginInGuest() before calling this function.
- If the program to run in the guest is intended to be visible to the user in
the guest, such as an application with a graphical user interface, you must
call VM::LoginInGuest() with
VixCOM.Constants.VIX_LOGIN_IN_GUEST_REQUIRE_INTERACTIVE_ENVIRONMENT as
the option before calling this function. This will ensure that the
program is run within a graphical session that is visible to the user.
- If the options parameter is 0, this function will report completion to
the IJob object when the program exits in the guest operating system.
Alternatively, you can pass
VixCOM.Constants.VIX_RUNPROGRAM_RETURN_IMMEDIATELY as the value of the
options parameter, and this function reports completion to the IJob object
as soon as the program starts in the guest.
- For Windows guest operating systems, when running a program with a graphical
user interface, you can pass VixCOM.Constants.VIX_RUNPROGRAM_ACTIVATE_WINDOW
as the value of the options parameter. This option will ensure that the
application's window is visible and not minimized on the guest's screen.
This can be combined with the
VixCOM.Constants.VIX_RUNPROGRAM_RETURN_IMMEDIATELY
flag using the bitwise inclusive OR operator (|).
VixCOM.Constants.VIX_RUNPROGRAM_ACTIVATE_WINDOW has no effect on Linux
guest operating systems.
- On a Linux guest operating system, if you are running a program with a
graphical user interface, it must know what X Windows display to use,
for example host:0.0, so it can make the program visible on that display.
Do this by passing the -display argument to the program, if it supports
that argument, or by setting the DISPLAY environment variable on the guest.
See documentation on
WriteVariable.
- When the job is signaled, the following properties will be available on
the returned job handle:
- VIX_PROPERTY_JOB_RESULT_PROCESS_ID: the process id; however, if the guest
has an older version of Tools (those released with Workstation 6 and
earlier) and the VIX_RUNPROGRAM_RETURN_IMMEDIATELY
flag is used, then the process ID will not be returned from the guest and
this property will not be set on the job handle, so attempting to access
this property will result in VIX_E_UNRECOGNIZED_PROPERTY being returned;
- VIX_PROPERTY_JOB_RESULT_GUEST_PROGRAM_ELAPSED_TIME: the process elapsed time;
- VIX_PROPERTY_JOB_RESULT_GUEST_PROGRAM_EXIT_CODE: the process exit code.
If the option parameter is VIX_RUNPROGRAM_RETURN_IMMEDIATELY, the latter two will
both be 0.
Side Effects
None.
Requirements
VixCOM.h, since VMware Workstation 6.0
Example
VBScript:
Dim lib
Dim host
Dim job
Dim vm
Dim result
Set lib = CreateObject("VixCOM.VixLib")
' Connect to the local installation of Workstation. This also intializes the VIX API.
Set job = lib.Connect(VixCOM.Constants.VIX_API_VERSION, VixCOM.Constants.VIX_SERVICEPROVIDER_VMWARE_WORKSTATION, Empty, 0, Empty, Empty, 0, Nothing, Nothing)
' results needs to be initialized before it's used, even if it's just going to be overwritten.
Set results = Nothing
' Wait waits until the job started by an asynchronous function call has finished. It also
' can be used to get various properties from the job. The first argument is an array
' of VIX property IDs that specify the properties requested. When Wait returns, the
' second argument will be set to an array that holds the values for those properties,
' one for each ID requested.
err = job.Wait(Array(VixCOM.Constants.VIX_PROPERTY_JOB_RESULT_HANDLE), results)
If lib.ErrorIndicatesFailure(err) Then
' Handle the error...
End If
' The job result handle will be first element in the results array.
Set host = results(0)
' Open the virtual machine with the given .vmx file.
Set job = host.OpenVM("c:\Virtual Machines\vm1\win2000.vmx", Nothing)
err = job.Wait(Array(VixCOM.Constants.VIX_PROPERTY_JOB_RESULT_HANDLE), results)
If lib.ErrorIndicatesFailure(err) Then
' Handle the error...
End If
Set vm = results(0)
' Power on the virtual machine we just opened. This will launch Workstation if it hasn't
' already been started.
Set job = vm.PowerOn(VixCOM.Constants.VIX_VMPOWEROP_LAUNCH_GUI, Nothing, Nothing)
' WaitWithoutResults is just like Wait, except it does not get any properties.
err = job.WaitWithoutResults()
If lib.ErrorIndicatesFailure(err) Then
' Handle the error...
End If
' Wait until VMware Tools are running within the guest, with a 300 second timeout.
Set job = vm.WaitForToolsInGuest(300, Nothing)
err = job.WaitWithoutResults()
If lib.ErrorIndicatesFailure(err) Then
' Handle the error...
End If
Set job = vm.LoginInGuest("vixuser", "secret", 0, Nothing)
err = job.WaitWithoutResults()
If lib.ErrorIndicatesFailure(err) Then
' Handle the error...
End If
Set job = vm.RunProgramInGuest("c:\myProgram.exe", "/flag arg1 arg2", 0, Nothing, Nothing)
err = job.WaitWithoutResults()
If lib.ErrorIndicatesFailure(err) Then
' Handle the error...
End If
host.Disconnect()