Using the VIX API

Connecting to a Host

To work with a virtual machine, you must first connect the Vix client to the host where the virtual machine is stored. If the virtual machine is on a host running VMware Workstation, you can only connect to it from a client on the same host. If the virtual machine is on a host running VMware Server, then you can connect to that host whether it is a local or remote host. VMware Workstation currently allows you to manipulate virtual machines only from the local host.

In all cases, you connect to a host using the VixHost_Connect() function. You specify whether the host is using VMware Workstation or VMware Server with the hostType parameter for VixHost_Connect(). Pass the value VIX_SERVICEPROVIDER_VMWARE_SERVER if the host runs VMware Server, and VIX_SERVICEPROVIDER_VMWARE_WORKSTATION if the host runs VMware Workstation.

Note that the hostType parameter describes the VMware software running on the host where the virtual machine is located, regardless of where the client is running. If you are using VMware Server to connect to a remote host, it does not matter which VMware product (if any) is running on the local host.

If you do not know in advance which VMware product will be running on the host, you can pass the value VIX_SERVICEPROVIDER_DEFAULT for the hostType parameter. When you pass VIX_SERVICEPROVIDER_DEFAULT, the Vix library determines which VMware product is installed on the host. This lets you write a single program that can work with any VMware product on a local host.

VixHost_Connect() is an asynchronous function, so the function call must be completed with a callback function or a call to VixJob_Wait().

#include "vix.h"

int main(int argc, char * argv[])
{
   VixHandle hostHandle = VIX_INVALID_HANDLE;
   VixHandle jobHandle = VIX_INVALID_HANDLE;
   VixError err;

   // Connect to specified host.
   jobHandle = VixHost_Connect(VIX_API_VERSION,
                               VIX_SERVICEPROVIDER_VMWARE_SERVER,
                               argv[1], // hostName
                               0, // hostPort
                               argv[2], // userName
                               argv[3], // 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);
   // Other code goes here...
   
abort:
   VixHost_Disconnect(hostHandle);
}

#include "vix.h"

int main(int argc, char * argv[])
{
   VixHandle hostHandle = VIX_INVALID_HANDLE;
   VixHandle jobHandle = VIX_INVALID_HANDLE;
   VixError err;

   // Connect as specified user on local host.
   jobHandle = VixHost_Connect(VIX_API_VERSION,
                               VIX_SERVICEPROVIDER_VMWARE_SERVER,
                               NULL, // hostName
                               0, // hostPort
                               argv[1], // userName
                               argv[2], // 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);
   // Other code goes here...

abort:
   VixHost_Disconnect(hostHandle);
}

#include "vix.h"

int main(int argc, char * argv[])
{
   VixHandle hostHandle = VIX_INVALID_HANDLE;
   VixHandle jobHandle = VIX_INVALID_HANDLE;
   VixError err;

   // Connect as current user on local host.
   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);
   // Other code goes here...

abort:
   VixHost_Disconnect(hostHandle);
}

Registering and Unregistering Virtual Machines on VMware Server

VMware Server requires that a virtual machine be present in its "inventory" before using the virtual machine. The virtual machine inventory is a list of virtual machines that the local host is able to run.

This feature is supported only by VMware Server. VMware Workstation does not use or support registering virtual machines.

Conversely, if you remove a virtual machine from VMware Server's inventory, it is not available for any virtual machine operations. This is a convenient way to prevent virtual machines from being modified while they are not in regular use. You can also keep an unregistered virtual machine as a "gold" standard from which you can make copies as needed.

Registering or unregistering a virtual machine does not require a handle to the virtual machine, but it does require a path to the virtual machine's configuration (.vmx) file. The client must also provide a handle to the host machine where the virtual machine is to be registered or unregistered.

VixHost_RegisterVM() and VixHost_UnregisterVM() are asynchronous functions, so the function call must be completed with a callback function or a call to VixJob_Wait().

VixHandle jobHandle = VIX_INVALID_HANDLE;
char vmxFilePath[] = "c:\\Virtual Machines\\vm1\\win2000.vmx";
VixError err;

// Add virtual machine to host's inventory.
jobHandle = VixHost_RegisterVM(hostHandle,
                               vmxFilePath,
                               NULL, // callbackProc,
                               NULL); // clientData
err = VixJob_Wait(jobHandle, VIX_PROPERTY_NONE);
if (VIX_OK != err) {
   // Handle the error...
   goto abort;
}

Vix_ReleaseHandle(jobHandle);

VixHandle jobHandle = VIX_INVALID_HANDLE;
char vmxFilePath[] = "c:\\Virtual Machines\\vm1\\win2000.vmx";
VixError err;

// Remove virtual machine from host's inventory.
jobHandle = VixHost_UnregisterVM(hostHandle,
                                 vmxFilePath,
                                 NULL, // callbackProc,
                                 NULL); // clientData
                                 
err = VixJob_Wait(jobHandle, VIX_PROPERTY_NONE);
if (VIX_OK != err) {
   // Handle the error...
   goto abort;
}

Vix_ReleaseHandle(jobHandle);

Getting a Handle to a Virtual Machine

Most virtual machine operations require a handle to identify the virtual machine. The VixVM_Open() function converts a path name to a handle, which you can use in subsequent function calls. VixVM_Open() is an asynchronous function, so the function call must be completed with a callback function or a call to VixJob_Wait() .

To get a handle to a virtual machine:

1. Supply a handle to the host on which the virtual machine is located. Refer to Connecting to a Host.
2. On VMware Server only, ensure that the virtual machine is registered on the host. Refer to Registering and Unregistering Virtual Machines.
3. Use the host handle and the virtual machine's path name in the host's file system to open the virtual machine with VixVM_Open() .
4. Retrieve the virtual machine handle from the job object.

VixHandle jobHandle = VIX_INVALID_HANDLE;
char vmxFilePath[] = "c:\\Virtual Machines\\vm1\\win2000.vmx";
VixError err;

// Open virtual machine and get a handle.
jobHandle = VixVM_Open(hostHandle,
                       vmxFilePath,
                       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);
// ...Use vmHandle in subsequent code...

Starting or Resuming a Virtual Machine

The VixVM_PowerOn() function has two purposes:

• To start the guest operating system in a virtual machine previously in a powered-off state.
• To resume execution of a guest operating system in a suspended virtual machine.

There is no separate Resume function in the VIX API. The VixVM_PowerOn() function must be used instead.

VixVM_PowerOn() is an asynchronous function, so the function call must be completed with a callback function or a call to VixJob_Wait() .

For most purposes (especially if you want to do operations in the guest operating system) you must wait for VMware Tools to become active in the guest. Until the VMware Tools utility is ready, no guest operations using the VIX API can complete. Refer to Installing VMware Tools in a Virtual Machine for more information about VMware Tools.

The VixVM_WaitForToolsInGuest() function allows you to wait until the VMware Tools utility is responding. There is a timeout parameter available for the function. You should generally set the timeout somewhat longer than the typical time it takes the guest operating system to finish booting.

VixError err = VIX_OK;
VixHandle jobHandle = VIX_INVALID_HANDLE;

// Power on the virtual machine.
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 for VMware Tools to be active.
jobHandle = VixVM_WaitForToolsInGuest(vmHandle,
                                      120, // timeoutInSeconds,
                                      NULL, // callbackProc,
                                      NULL); // clientData

err = VixJob_Wait(jobHandle, VIX_PROPERTY_NONE);
if (VIX_OK != err) {
   // Handle the timeout...
}
Vix_ReleaseHandle(jobHandle);

VixError err = VIX_OK;
VixHandle jobHandle = VIX_INVALID_HANDLE;
int toolsState = 0;

// Resume suspended virtual machine.
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);

// Check if VMware Tools active.
err = Vix_GetProperties(vmHandle,
                        VIX_PROPERTY_VM_TOOLS_STATE,
                        &toolsState,
                        VIX_PROPERTY_NONE);
if (VIX_OK != err) {
   // Handle the error...
   goto abort;
}

Vix_ReleaseHandle(jobHandle);

if (VIX_TOOLSSTATE_RUNNING != toolsState) {
   // Wait for VMware Tools to be active.
   jobHandle = VixVM_WaitForToolsInGuest(VixHandle vmHandle,
                                         120, // timeoutInSeconds,
                                         NULL, // callbackProc,
                                         NULL); // clientData
   err = VixJob_Wait(jobHandle, VIX_PROPERTY_NONE);
   if (VIX_OK != err) {
      // Handle the timeout...
   }

   Vix_ReleaseHandle(jobHandle);
}

VMware Tools

All functions that execute in a guest operating system require VMware Tools to be installed and running. Refer to Installing VMware Tools in a Virtual Machine for information on installing VMware Tools.

Authentication

All functions that modify a file system in the guest operating system or that execute code in a guest operating system require the client to authenticate as a user account known to the guest. The following functions require client authentication:

• VixVM_RunProgramInGuest()
• VixVM_CopyFileFromHostToGuest()
• VixVM_CopyFileFromGuestToHost()
• VixVM_RunProgramInGuest() (Workstation 6 or later)
• VixVM_ListProcessesInGuest() (Workstation 6 or later)
• VixVM_KillProcessInGuest() (Workstation 6 or later)
• VixVM_RunScriptInGuest() (Workstation 6 or later)
• VixVM_OpenUrlInGuest() (Workstation 6 or later)
• VixVM_CopyFileFromHostToGuest() (Workstation 6 or later)
• VixVM_CopyFileFromGuestToHost() (Workstation 6 or later)
• VixVM_DeleteFileInGuest() (Workstation 6 or later)
• VixVM_FileExistsInGuest() (Workstation 6 or later)
• VixVM_RenameFileInGuest() (Workstation 6 or later)
• VixVM_CreateTempFileInGuest() (Workstation 6 or later)
• VixVM_ListDirectoryInGuest() (Workstation 6 or later)
• VixVM_CreateDirectoryInGuest() (Workstation 6 or later)
• VixVM_DeleteDirectoryInGuest() (Workstation 6 or later)
• VixVM_DirectoryExistsInGuest() (Workstation 6 or later)

A client uses VixVM_LoginInGuest() to authenticate with the guest operating system. Once authenticated, the client may continue to perform guest operations until one of the following takes place:

• The client calls VixVM_LogoutFromGuest().
• The client terminates, which ends the session.
• The client attempts to authenticate a second time, and the second attempt fails.
• The virtual machine shuts down.

If a virtual machine is suspended while a client is authenticated with the guest operating system, the client may resume guest operations after resuming virtual machine execution. However, this is true only if the client continues running while the virtual machine is suspended.

To authenticate with the guest operating system:

1. Connect to the host on which the virtual machine is located. Refer to Connecting to a Host.
2. Get a handle to the virtual machine. Refer to Getting a Handle to a Virtual Machine.
3. Power on the virtual machine and wait for VMware Tools to become active. Refer to Starting or Resuming a Virtual Machine.
4. Use the virtual machine handle, the user name, and the user password, to call VixVM_LoginInGuest() .

VixError err = VIX_OK;
VixHandle jobHandle = VIX_INVALID_HANDLE;

// Authenticate with guest operating system.
jobHandle = VixVM_LoginInGuest(vmHandle,
                               "Administrator", // 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;
}

Vix_ReleaseHandle(jobHandle);

Choosing Whether to Power Off or Suspend

You can stop virtual machine execution in two ways. Whether you choose to power off or to suspend a virtual machine depends on your purpose.

• VixVM_PowerOff() is equivalent to turning off the power switch of a physical machine. Some operations on a virtual machine, such as changing the virtual hardware configuration, require that the virtual machine be powered off.
• VixVM_Suspend() is similar to putting a laptop to sleep. The virtual machine stops running. When you resume operation, the virtual machine continues exactly from the point of suspension

Both functions are asynchronous, so either function call must be completed with a callback function or a call to VixJob_Wait() .

Powering Off a Virtual Machine

To power off a virtual machine:

1. Connect to the host on which the virtual machine is located. Refer to Connecting to a Host.
2. Get a handle to the virtual machine. Refer to Getting a Handle to a Virtual Machine.
3. Use the virtual machine handle in a call to VixVM_PowerOff() .
4. Check the power state of the virtual machine.

VixError err = VIX_OK;
VixHandle jobHandle = VIX_INVALID_HANDLE;

// Power off the virtual machine.
jobHandle = VixVM_PowerOff(vmHandle,
                           0, // powerOffOptions,
                           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);

Suspending a Virtual Machine

To suspend a virtual machine:

1. Connect to the host on which the virtual machine is located. Refer to Connecting to a Host.
2. Get a handle to the virtual machine. Refer to Getting a Handle to a Virtual Machine.
3. Use the virtual machine handle in a call to VixVM_Suspend() .
4. Check the power state of the virtual machine.

VixError err = VIX_OK;
VixHandle jobHandle = VIX_INVALID_HANDLE;

// Suspend the virtual machine.
jobHandle = VixVM_Suspend(vmHandle,
                          0, // powerOffOptions,
                          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);

Upgrading Virtual Hardware

When using legacy virtual machines, you can upgrade the virtual hardware by calling the VixVM_UpgradeVirtualHardware() function. This function upgrades the virtual hardware to the same level as virtual machines created with the current release.

To upgrade the virtual hardware version of your virtual machine:

1. Connect to the host on which the virtual machine is located. Refer to Connecting to a Host.
2. Get a handle to the virtual machine. Refer to Getting a Handle to a Virtual Machine.
3. Power off the virtual machine. Refer to Powering Off a Virtual Machine.
4. Use the virtual machine handle in a call to VixVM_UpgradeVirtualHardware() .

VixError err = VIX_OK;
VixHandle jobHandle = VIX_INVALID_HANDLE;

// Upgrade the virtual hardware.
jobHandle = VixVM_UpgradeVirtualHardware(vmHandle,
                                         0, // options
                                         NULL, // callbackProc
                                         NULL); // clientData
err = VixJob_Wait(jobHandle, VIX_PROPERTY_NONE);
if (VIX_OK != err) {
   // Handle the error...
   goto abort;
}

Vix_ReleaseHandle(jobHandle);