Name

Description

HRESULT
LoginInGuest([in] BSTR userName,
             [in] BSTR password,
             [in] LONG options,
             [in] ICallback* jobDoneCallback,
             [out,retval] IJob** loginJob);

This function establishes a guest operating system authentication context that can be used with guest functions for the given virtual machine handle.

Parameters

userName

The name of a user account on the guest operating system.

password

The password of the account identified by userName.

options

Must be 0.

jobDoneCallback

An ICallback instance that will be called when the operation is complete.

loginJob

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

Return Value

Remarks

• This function validates the account name and password in the guest OS. You must call this function before calling functions to perform operations on the guest operating system, such as VM::RunProgramInGuest(). If you do not call any guest functions, you do not need to call
• The following functions require that you call VMLoginInGuest().
  • VM::RunProgramInGuest()
  • VM::ListProcessesInGuest()
  • VM::KillProcessInGuest()
  • VM::RunScriptInGuest()
  • VM::OpenUrlInGuest()
  • VM::CopyFileFromHostToGuest()
  • VM::CopyFileFromGuestToHost()
  • VM::DeleteFileInGuest()
  • VM::FileExistsInGuest()
  • VM::RenameFileInGuest()
  • VM::CreateTempFileInGuest()
  • VM::ListDirectoryInGuest()
  • VM::CreateDirectoryInGuest()
  • VM::DeleteDirectoryInGuest()
  • VM::DirectoryExistsInGuest()
  • VM::WriteVariable() when writing a VIX_GUEST_ENVIRONMENT_VARIABLE value

• All guest operations for a particular VM handle will be done using the identity you provide to LoginInGuest(). As a result, guest operations will be restricted by file system priveleges in the guest OS that apply to the user specified in LoginInGuest(). For example, may fail if the user named in LoginInGuest(). does not have access permissions to the directory in the guest OS.

• LoginInGuest() changes the behavior of Vix functions to use a user account. It does not log in a user into a console session on the guest operating system. As a result, you may not see the user logged in from within the guest operating system. Moreover, operations such as rebooting the guest do not clear the guest credentials.

• You must call LoginInGuest() for each VM handle that uses guest operations.

• The virtual machine must be powered on before calling this function.

• VMware Tools must be installed and running on the guest operating system before calling this function. You can call VM::WaitForToolsInGuest() to wait for the tools to run.

• You can call VM::LogoutFromGuest() to remove the user information from the VMHandle.

• You can always explicitly login in the guest by providing a username and password that is valid on the guest. Then you will execute all guest operations as that user. This is the default mechanism and is encouraged.

• Optionally, you may call LoginInGuest() with the constant defined by VIX_CONSOLE_USER_NAME in vix.h as the userName, and NULL for the password. If there is a user currently logged into the guest at the console (through the MKS) then all guest operations will be run as the console user. This is enabled by default and must be explicitly disabled by setting the "guest.commands.anonGuestCommandsRunAsConsoleUser" config value to false. If no user is logged in at the guest console, the call to LoginInGuest() will block and wait for a user to log in to the console.

Side Effects

Requirements

Example

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

' 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
   WScript.Echo("Error: " & lib.GetErrorText(err, empty))
   WScript.Quit
End If

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

Set job = vm.CopyFileFromGuestToHost("c:\guestDir\helloworld.o", "c:\hostDir\helloworld.o", 0, Nothing, Nothing)
err = job.WaitWithoutResults()
If lib.ErrorIndicatesFailure(err) Then
   WScript.Echo("Error: " & lib.GetErrorText(err, empty))
   WScript.Quit
End If

host.Disconnect()