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

Side Effects

None.

Requirements

VixCOM.h, since VMware Workstation 6.0
Minimum Supported Guest OS: Microsoft Windows NT Series, Linux

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 initializes 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

Set results = Nothing
Set job = Nothing
Set vm = Nothing

host.Disconnect()
C#:
class Program
{

   static void Main(string[] args)  
   {
      VixCOM.VixLibClass lib = new VixCOM.VixLibClass();
      UInt64 err;
      object results = null;
      
      // 
      VixCOM.IJob job = lib.Connect(VixCOM.Constants.VIX_API_VERSION,
                                    VixCOM.Constants.VIX_SERVICEPROVIDER_VMWARE_WORKSTATION,
                                    null,
                                    0,
                                    null,
                                    null,
                                    0,
                                    null,
                                    null);
      err = job.Wait(new int[] { VixCOM.Constants.VIX_PROPERTY_JOB_RESULT_HANDLE },
                     ref results);
      if (lib.ErrorIndicatesFailure(err)) {
         // Handle the error... 
      }     

      VixCOM.IHost host = (VixCOM.IHost)((object[])results)[0];
      CloseVixObject(job);

      job = host.OpenVM("c:\\Virtual Machines\\vm1\\win2000.vmx", null);

      err = job.Wait(new int[] { VixCOM.Constants.VIX_PROPERTY_JOB_RESULT_HANDLE }, 
                     ref results);
      if (lib.ErrorIndicatesFailure(err)) {
         // Handle the error... 
      }     

      VixCOM.IVM2 vm = (VixCOM.IVM2)((object[])results)[0];
      CloseVixObject(job);

      job = vm.PowerOn(VixCOM.Constants.VIX_VMPOWEROP_LAUNCH_GUI, null, null);
      job.WaitWithoutResults();
      if (lib.ErrorIndicatesFailure(err))
      {
         // Handle the error... 
      }
      CloseVixObject(job);

      // Wait up to 300 seconds for tools to start
      job = vm.WaitForToolsInGuest(300, null);
      err = job.WaitWithoutResults();
      if (lib.ErrorIndicatesFailure(err))
      {
         // Handle the error... 
      }
      CloseVixObject(job);

      job = vm.LoginInGuest("vixuser", "secret", 0, null);
      err = job.WaitWithoutResults();
      if (lib.ErrorIndicatesFailure(err))
      {
         // Handle the error...
      }
      CloseVixObject(job);

      job = vm.RunProgramInGuest("c:\\myProgram.exe", "/flag arg1 arg2", 0, null, null);
      err = job.WaitWithoutResults();
      if (lib.ErrorIndicatesFailure(err))
      {
         // Handle the error...
      }
      CloseVixObject(job);

      CloseVixObject(vm);
     
      host.Disconnect();
   }

   static void CloseVixObject(Object vixObject)
   {
      try
      {
         ((IVixHandle2)vixObject).Close();
      }
      catch(Exception)
      {
         //Close is not supported in this version of Vix COM - Ignore
      }
   }
}

Copyright (C) 2007-2011 VMware, Inc. All rights reserved.