# Name

VixVM_Pause

# 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

VixHandle. A job handle that describes the state of this asynchronous operation.

# 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

None.

# Requirements

vix.h, since VMware Workstation 6.5.

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

Copyright (C) 2007-2018 VMware, Inc. All rights reserved.