Name

Description

VixHandle
VixVM_Pause(VixHandle vmHandle,
            int options,
            VixHandle propertyListHandle,
            VixEventProc *callbackProc,
            void *clientData);

This function pauses a virtual machine. See Remarks section for pause behavior when used with different operations.

Parameters

vmHandle

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

options

Must be zero.

propertyListHandle

Must be VIX_INVALID_HANDLE.

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 stops execution of the virtual machine.
• Functions that invoke guest operations should not be called when the virtual machine is paused.
• Call VixVM_Unpause to continue execution of the virtual machine.
• Calling VixVM_Reset, VixVM_PowerOff, and VixVM_Suspend will successfully work when paused. The pause state is not preserved in a suspended virtual machine; a subsequent VixVM_PowerOn will not remember the previous pause state.
• Calling VixVM_BeginRecording when paused is legal. The actual recording will start when the virtual machine is unpaused.
• Do not call VixVM_BeginReplay when the virtual machine is paused. To do so, call VixVM_PowerOff first, which will reset the pause state. After the virtual machine is powered off, you can then call VixVM_BeginReplay.
• This function is not supported when using the VIX_SERVICEPROVIDER_VMWARE_PLAYER host type.

Side Effects

Requirements

Example

VixError err = VIX_OK;
VixHandle hostHandle = VIX_INVALID_HANDLE;
VixHandle jobHandle = VIX_INVALID_HANDLE;
VixHandle vmHandle = VIX_INVALID_HANDLE;
VixHandle snapshotHandle = 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;
}
// Release handle after use:
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;
}
// Release handle after use:
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;
}
// Release handle after use:
Vix_ReleaseHandle(jobHandle);

// Stop replaying the virtual machine.
jobHandle = VixVM_Pause(vmHandle,
                        0, // options
                        VIX_INVALID_HANDLE, // propertyListHandle
                        NULL, // callbackProc
                        NULL); // clientData
err = VixJob_Wait(jobHandle,
                  VIX_PROPERTY_JOB_RESULT_HANDLE,
                  &snapshotHandle,
                  VIX_PROPERTY_NONE);

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