Edit C:\Program Files (x86)\VMware\VMware VIX\doc\lang\c\functions\VixVM

Edit C:\Program Files (x86)\VMware\VMware VIX\doc\lang\c\functions\VixVM_LoginInGuest.html

<html>
<head>
<meta HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=ISO-8859-1">
<meta HTTP-EQUIV="Content-Style-Type" CONTENT="text/css">
<link rel="stylesheet" href="../../../foundrydoc.css" type="text/css" charset="ISO-8859-1">
<link rel="stylesheet" href="foundrydoc.css" type="text/css" charset="ISO-8859-1">
</head>
<body>
<h1>Name</h1>
<b>VixVM_LoginInGuest</b>
<h1>Description</h1>
<pre>
VixHandle
VixVM_LoginInGuest(VixHandle vmHandle,
                   char *userName,
                   char *password,
                   int options,
                   VixEventProc *callbackProc,
                   void *clientData);
</pre>
<p>
This function establishes a guest operating system authentication context
that can be used with guest functions for the given virtual machine handle.
<h1>Parameters</h1>
<dl>
<dt><i>vmHandle</i></dt>
<dd>
Identifies a virtual machine. Call VixVM_Open() to create a virtual machine handle.
</dd>
<dt><i>userName</i></dt>
<dd>
The name of a user account on the guest operating system.
</dd>
<dt><i>password</i></dt>
<dd>
The password of the account identified by userName.
</dd>
<dt><i>options</i></dt>
<dd>
Must be 0 or one of the following values:
<ul>
<li> VIX_LOGIN_IN_GUEST_REQUIRE_INTERACTIVE_ENVIRONMENT -
directs guest commands invoked after the call to
</ul>
VixVM_LoginInGuest() to be run from within the session of the
	     user who is interactively logged into the guest operating system. See the remarks
	     below for more information about
	     VIX_LOGIN_IN_GUEST_REQUIRE_INTERACTIVE_ENVIRONMENT.
</dd>
<dt><i>callbackProc</i></dt>
<dd>
A callback function that will be invoked when the
                  operation is complete.
</dd>
<dt><i>clientData</i></dt>
<dd>
A parameter that will be passed to the callbackProc function.
</dd>
<h1>Return Value</h1>
VixHandle. A job handle that describes the state of this asynchronous operation.
<h1>Remarks</h1>
<ul>
<li> This function validates the account name and password in the guest OS. You must 
call this function before calling functions that perform operations on the guest OS,
such as those below.  Otherwise you do not need to call this function.
<li> Logins are supported on Linux and Windows.  To log in as a Windows Domain user,
specify the 'userName' parameter in the form "domain\username".
<li> This function does not respect access permissions on Windows 95, Windows 98, and
Windows ME, due to limitations of the permissions model in those systems.
<li> Other guest operating systems are not supported for login, including Solaris,
FreeBSD, and Netware.
<li> The option
VIX_LOGIN_IN_GUEST_REQUIRE_INTERACTIVE_ENVIRONMENT
should be used to ensure that the functions
VixVM_CaptureScreenImage, VixVM_OpenUrlInGuest, and VixVM_RunProgramInGuest
work correctly.
<li> The following functions require that you call VixVM_LoginInGuest():
<ul>
<li> VixVM_RunProgramInGuest()
<li> VixVM_ListProcessesInGuest()
<li> VixVM_KillProcessInGuest()
<li> VixVM_RunScriptInGuest()
<li> VixVM_OpenUrlInGuest()
<li> VixVM_CopyFileFromHostToGuest()
<li> VixVM_CopyFileFromGuestToHost()
<li> VixVM_DeleteFileInGuest()
<li> VixVM_FileExistsInGuest()
<li> VixVM_RenameFileInGuest()
<li> VixVM_CreateTempFileInGuest()
<li> VixVM_ListDirectoryInGuest()
<li> VixVM_CreateDirectoryInGuest()
<li> VixVM_DeleteDirectoryInGuest()
<li> VixVM_DirectoryExistsInGuest()
<li> VixVM_WriteVariable() when writing a VIX_GUEST_ENVIRONMENT_VARIABLE value.
<li> VixVM_CaptureScreenImage()
</ul>
<li> 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.
<li> 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.
<li> You must call VixVM_LoginInGuest() for each VM handle that uses guest operations.
<li> The virtual machine must be powered on before calling this function.
<li> 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.
<li> Once VixVM_LoginInGuest() has succeeded, the user session remains valid until
<ul>
<li> VixVM_LogoutFromGuest() is called successfully,
<li> VixVM_LoginInGuest() is called successfully with different user credentials,
<li> the virtual machine handle's reference count reaches 0, or
<li> the client applications exits.
</ul>
<li> The special login type VIX_CONSOLE_USER_NAME is no longer supported.
<li> Calling VixVM_LoginInGuest() with 0 as 'options' can be done at any time
when the VMware Tools are running in the guest.
<li> Calling VixVM_LoginInGuest() with the
VIX_LOGIN_IN_GUEST_REQUIRE_INTERACTIVE_ENVIRONMENT flag can only be done when
there is an interactive user logged into the guest OS. Specifically, the
"interactive user" refers to the user who has
logged into the guest OS through the console (for instance, the user who
logged into the Windows log-in screen). The VIX user is the user whose
credentials are being provided in the call to VixVM_LoginInGuest(). With
VIX_LOGIN_IN_GUEST_REQUIRE_INTERACTIVE_ENVIRONMENT, there must be an
interactive user logged into the guest when the call to VixVM_LoginInGuest()
is made, and the VIX user must match the interactive user (they must have
same account in the guest OS).
<li> Using VIX_LOGIN_IN_GUEST_REQUIRE_INTERACTIVE_ENVIRONMENT will ensure that
the environment in which guest commands are executed is as close as possible
to the normal environment in which a user interacts with the guest OS.
Without VIX_LOGIN_IN_GUEST_REQUIRE_INTERACTIVE_ENVIRONMENT, commands
may be run in a more limited environment; however, omitting
VIX_LOGIN_IN_GUEST_REQUIRE_INTERACTIVE_ENVIRONMENT will ensure that commands
can be run regardless of whether an interactive user is present in the guest.
<li> On Linux guest operating systems, the
VIX_LOGIN_IN_GUEST_REQUIRE_INTERACTIVE_ENVIRONMENT flag requires that X11
be installed and running.
</ul>
<h1>Side Effects</h1>
None.
<h1>Requirements</h1>
vix.h, since VMware Server 1.0
<br>Minimum Supported Guest OS: Microsoft Windows NT Series, Linux<br><h1>Example</h1>
This example copies a compiled object file from a virtual machine to be
run on the host.
<pre>
VixError err = VIX_OK;
VixHandle hostHandle = VIX_INVALID_HANDLE;
VixHandle jobHandle = VIX_INVALID_HANDLE;
VixHandle vmHandle = VIX_INVALID_HANDLE;
int isLoggedIn = 0;

jobHandle = VixHost_Connect(VIX_API_VERSION,
                            VIX_SERVICEPROVIDER_VMWARE_WORKSTATION,
                            NULL, // hostName
                            0, // hostPort
                            NULL, // userName
                            NULL, // password
                            0, // options
                            VIX_INVALID_HANDLE, // propertyListHandle
                            NULL, // callbackProc
                            NULL); // clientData

err = VixJob_Wait(jobHandle,
                  VIX_PROPERTY_JOB_RESULT_HANDLE,
                  &hostHandle,
                  VIX_PROPERTY_NONE);

if (VIX_OK != err) {
   // Handle the error...
   goto abort;
}
Vix_ReleaseHandle(jobHandle);

jobHandle = VixVM_Open(hostHandle,
                       "c:\\Virtual Machines\\vm1\\win2000.vmx",
                       NULL, // callbackProc
                       NULL); // clientData
                       
err = VixJob_Wait(jobHandle,
                  VIX_PROPERTY_JOB_RESULT_HANDLE,
                  &vmHandle,
                  VIX_PROPERTY_NONE);
if (VIX_OK != err) {
   // Handle the error...
   goto abort;
}

Vix_ReleaseHandle(jobHandle);

// Power on the virtual machine before copying file.
jobHandle = VixVM_PowerOn(vmHandle,
                          0, // powerOnOptions
                          VIX_INVALID_HANDLE, // propertyListHandle
                          NULL, // callbackProc
                          NULL); // clientData

err = VixJob_Wait(jobHandle,VIX_PROPERTY_NONE);
if (VIX_OK != err) {
   // Handle the error...
   goto abort;
}

Vix_ReleaseHandle(jobHandle);

// Wait until guest is completely booted.
jobHandle = VixVM_WaitForToolsInGuest(vmHandle,
                                      300, // timeoutInSeconds
                                      NULL, // callbackProc
                                      NULL); // clientData

err = VixJob_Wait(jobHandle, VIX_PROPERTY_NONE);
if (VIX_OK != err) {
   // Handle the error...
   goto abort;
}

Vix_ReleaseHandle(jobHandle);

// Authenticate for guest operations.
jobHandle = VixVM_LoginInGuest(vmHandle,
                               "vixuser", // userName
                               "secret", // password
                               0, // options
                               NULL, // callbackProc
                               NULL); // clientData

err = VixJob_Wait(jobHandle, VIX_PROPERTY_NONE);
if (VIX_OK != err) {
   // Handle the error...
   goto abort;
}

isLoggedIn = 1;

Vix_ReleaseHandle(jobHandle);

// Copy the file.
jobHandle = VixVM_CopyFileFromGuestToHost(vmHandle,
                                          "c:\\guestDir\\helloworld.o",  // src name
                                          "c:\\hostDir\\helloworld.o", // dest name
                                          0, // options
                                          VIX_INVALID_HANDLE, // propertyListHan
                                          NULL, // callbackProc
                                          NULL); // clientData

err = VixJob_Wait(jobHandle, VIX_PROPERTY_NONE);
if (VIX_OK != err) {
   // Handle the error...
   goto abort;
}

abort:

if (isLoggedIn) {
   Vix_ReleaseHandle(jobHandle);
   // Clear the authentication
   jobHandle = VixVM_LogoutFromGuest(vmHandle,
                                     NULL, // callbackProc
                                     NULL); // clientData

err = VixJob_Wait(jobHandle, VIX_PROPERTY_NONE);
   if (VIX_OK != err) {
      // Handle the error, but do not go to abort.
   }
}

Ms-Dos/Windows Unix Write backup

jsp File Browser version 1.2 by www.vonloesch.de