Name

Description

VixHandle
VixVM_WaitForToolsInGuest(VixHandle vmHandle,
                          int timeoutInSeconds,
                          VixEventProc *callbackProc,
                          void *clientData);

This function signals the job handle when VMware Tools has successfully started in the guest operating system. VMware Tools is a collection of services that run in the guest.

Parameters

vmHandle

Identifies a virtual machine. Call VixVM_Open() to create a virtual machine handle.

timeoutInSeconds

The timeout in seconds. If VMware Tools has not started by this time, the operation completes with an error. If the value of this argument is zero or negative, then this operation will wait indefinitely until the VMware Tools start running in the guest operating system.

callbackProc

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

clientData

A parameter that will be passed to the callbackProc function.

Return Value

Remarks

• This function signals the job when VMware Tools has successfully started in the guest operating system. VMware Tools is a collection of services that run in the guest.
• VMware Tools must be installed and running for some Vix functions to operate correctly. If VMware Tools is not installed in the guest operating system, or if the virtual machine is not powered on, this function reports an error to the job object.
• The VIX_PROPERTY_VM_TOOLS_STATE property of the virtual machine handle is undefined until VixVM_WaitForToolsInGuest() reports that VMware Tools is running.
• This function should be called after calling any function that resets or reboots the state of the guest operating system, but before calling any functions that require VMware Tools to be running. Doing so assures that VMware Tools are once again up and running. Functions that reset the guest operating system in this way include:
  • VixVM_PowerOn
  • VixVM_Reset
  • VixVM_RevertToSnapshot

Side Effects

Requirements

Example

VixError err = VIX_OK;
VixHandle hostHandle = VIX_INVALID_HANDLE;
VixHandle jobHandle = VIX_INVALID_HANDLE;
VixHandle vmHandle = VIX_INVALID_HANDLE;

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

abort:
Vix_ReleaseHandle(jobHandle);
Vix_ReleaseHandle(vmHandle);
VixHost_Disconnect(hostHandle);