Name

Description

HRESULT
InstallTools([in] LONG options,
             [in] BSTR commandLineArgs,
             [in] ICallback* jobDoneCallback,
             [out,retval] IJob** installJob);

Prepares to install VMware Tools on the guest operating system.

Parameters

options

May be either VixCOM.Constants.VIX_INSTALLTOOLS_MOUNT_TOOLS_INSTALLER or VixCOM.Constants.VIX_INSTALLTOOLS_AUTO_UPGRADE. Either flag can be combined with the VixCOM.Constants.VIX_INSTALLTOOLS_RETURN_IMMEDIATELY flag using the bitwise inclusive OR operator (|). See remarks for more information.

commandLineArgs

Must be NULL (C++), null (C#), or Empty (VB).

jobDoneCallback

A callback function that will be invoked when the operation is complete.

installJob

Returns an IJob object that describes the state of this asynchronous operation.

Return Value

Remarks

• If the option VixCOM.Constants.VIX_INSTALLTOOLS_MOUNT_TOOLS_INSTALLER is provided, the function prepares an ISO image to install VMware Tools on the guest operating system. If autorun is enabled, as it often is on Windows, installation begins, otherwise you must initiate installation. If VMware Tools is already installed, this function prepares to upgrade it to the version matching the product.
• If the option VixCOM.Constants.VIX_INSTALLTOOLS_AUTO_UPGRADE is provided, the function attempts to automatically upgrade VMware Tools without any user interaction required, and then reboots the virtual machine. This option requires that a version of VMware Tools already be installed. If VMware Tools is not already installed, the function will fail.
• When the option VixCOM.Constants.VIX_INSTALLTOOLS_AUTO_UPGRADE is used on virtual machine with a Windows guest operating system, the upgrade process may cause the Windows guest to perform a controlled reset in order to load new device drivers. If you intend to perform additional guest operations after upgrading the VMware Tools, it is recommanded that after this task completes, that the guest be reset using VM::Reset() with the VIX_VMPOWEROP_FROM_GUEST flag, followed by calling VM::WaitForToolsInGuest() to ensure that the guest has reached a stable state.
• If the option VixCOM.Constants.VIX_INSTALLTOOLS_AUTO_UPGRADE is provided and the newest version of tools is already installed, the function will return VixCOM.Constants.VIX_OK. Some older versions of Vix may return VixCOM.Constants.VIX_E_TOOLS_INSTALL_ALREADY_UP_TO_DATE.
• If the VixCOM.Constants.VIX_INSTALLTOOLS_RETURN_IMMEDIATELY flag is set, this function will report completion to the IJob object immediately after mounting the VMware Tools ISO image.
• If the VixCOM.Constants.VIX_INSTALLTOOLS_RETURN_IMMEDIATELY flag is not set for an ESX host, this function will report completion to the IJob object immediately after mounting the VMware Tools ISO image.
• If the VixCOM.Constants.VIX_INSTALLTOOLS_RETURN_IMMEDIATELY flag is not set for a WS host, this function will report completion to the IJob object only after the installation successfully completes or is cancelled.
• The virtual machine must be powered on to do this operation.
• If the Workstation installer calls for an ISO file that is not downloaded, this function returns an error, rather than attempting to download the ISO file.

Side Effects

Requirements

Example

Dim lib
Dim job
Dim err
Dim results
Dim host
Dim vm

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)

Set results = Nothing

err = job.Wait(Array(VixCOM.Constants.VIX_PROPERTY_JOB_RESULT_HANDLE), results)
If lib.ErrorIndicatesFailure(err) Then
   WScript.Echo("Error: " & lib.GetErrorText(err, empty))
   WScript.Quit
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
   WScript.Echo("Error: " & lib.GetErrorText(err, empty))
   WScript.Quit
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
   WScript.Echo("Error: " & lib.GetErrorText(err, empty))
   WScript.Quit
End If

Set job = vm.InstallTools(VixCOM.Constants.VIX_INSTALLTOOLS_MOUNT_TOOLS_INSTALLER, Nothing, Nothing)
err = job.WaitWithoutResults()
If lib.ErrorIndicatesFailure(err) Then
   WScript.Echo("Error: " & lib.GetErrorText(err, empty))
   WScript.Quit
End If

Set job = vm.PowerOff(0, Nothing)
err = job.WaitWithoutResults()
If lib.ErrorIndicatesFailure(err) Then
   WScript.Echo("Error: " & lib.GetErrorText(err, empty))
   WScript.Quit
End If

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

host.Disconnect()