Name
LoginInGuest
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 or VixCOM.Constants.VIX_LOGIN_IN_GUEST_REQUIRE_INTERACTIVE_ENVIRONMENT.
- 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
HRESULT
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 OS,
such as those below. Otherwise you do not need to call this function.
- This function does not load system environment variables.
VixCOM.Constants.VIX_LOGIN_IN_GUEST_REQUIRE_INTERACTIVE_ENVIRONMENT
should be used to be sure the function
OpenUrlInGuest
works correctly.
- The following functions require that you call VixVM_LoginInGuest():
- VixVM_RunProgramInGuest()
- VixVM_ListProcessesInGuest()
- VixVM_KillProcessInGuest()
- VixVM_RunScriptInGuest()
- VixVM_OpenUrlInGuest()
- VixVM_CopyFileFromHostToGuest()
- VixVM_CopyFileFromGuestToHost()
- VixVM_DeleteFileInGuest()
- VixVM_FileExistsInGuest()
- VixVM_RenameFileInGuest()
- VixVM_CreateTempFileInGuest()
- VixVM_ListDirectoryInGuest()
- VixVM_CreateDirectoryInGuest()
- VixVM_DeleteDirectoryInGuest()
- VixVM_DirectoryExistsInGuest()
- VixVM_WriteVariable() when writing a VIX_GUEST_ENVIRONMENT_VARIABLE value.
- VixVM_CaptureScreenImage()
- All guest operations for a particular VM handle are done using the identity
you provide to VixVM_LoginInGuest(). As a result, guest operations are restricted
by file system privileges in the guest OS that apply to the user specified
in VixVM_LoginInGuest(). For example, VixVM_DeleteDirectoryInGuest() might fail
if the user named in VixVM_LoginInGuest() does not have access permissions
to the directory in the guest OS.
- VixVM_LoginInGuest() changes the behavior of Vix functions to use a user account.
It does not log a user into a console session on the guest OS. As a result,
you might not see the user logged in from within the guest OS.
Moreover, operations such as rebooting the guest do not clear the guest credentials.
- You must call VixVM_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 OS
before calling this function. You can call VixVM_WaitForToolsInGuest()
to wait for the tools to run.
- Once VixVM_LoginInGuest() has succeeded, the user session remains valid until
- VixVM_LogoutFromGuest() is called successfully,
- VixVM_LoginInGuest() is called successfully with different user credentials,
- the virtual machine handle's reference count reaches 0, or
- the client applications exits.
- The following functions require that you call VM::LoginInGuest():
- 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 object are done using the identity
you provide to VM::LoginInGuest(). As a result, guest operations are restricted
by file system privileges in the guest OS that apply to the user specified
in VM::LoginInGuest(). For example, VM::DeleteDirectoryInGuest() might fail
if the user named in VM::LoginInGuest() does not have access permissions
to the directory in the guest OS.
- VM::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 OS. As a result,
you might not see the user logged in from within the guest OS.
Moreover, operations such as rebooting the guest do not clear the guest credentials.
- You must call VM::LoginInGuest() for each VM object 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 OS
before calling this function. You can call VM::WaitForToolsInGuest()
to wait for the tools to run.
- Once VM::LoginInGuest() has succeeded, the user session remains valid until
- VM::LogoutFromGuest() is called successfully,
- VM::LoginInGuest() is called successfully with different user credentials,
- the virtual machine object's reference count reaches 0, or
- the client applications exits.
- To log in as a Windows Domain user, you should specify the 'userName' parameter
in the form "domain\username".
- The special login type VIX_CONSOLE_USER_NAME is no longer supported.
- This function does not respect access permissions on guest operating systems
Windows 95, Windows 98, and Windows ME, due to limitations of the
permissions model in those operating systems.
Side Effects
None.
Requirements
VixCOM.h, since VMware Workstation 6.0
Example
This example copies a compiled object file from a virtual machine to be
run on the host.
VBScript:
Dim lib
Dim host
Dim job
Dim vm
Dim results
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
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
' Change the username and password to match an account in the guest OS.
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
Set job = vm.LogoutFromGuest(Nothing)
err = job.WaitWithoutResults()
If lib.ErrorIndicatesFailure(err) Then
WScript.Echo("Error: " & lib.GetErrorText(err, empty))
WScript.Quit
End If
host.Disconnect()