To start, stop, pause, reset, suspend, or resume a virtual machine, a prlsdkaspi.Vm
object must first be obtained. The prlsdkapi.Vm
class provides individual methods for each of the power operations, but it also provides a single wrapper method that can perform any power operation based on the specified code. This design is common in the Parallels Python API. You will see many wrapper methods or properties like that. Their purpose is to make the programming with the API even easier. Again, you can use individual methods if you find it more comfortable to work with.
Please note that powering off a virtual machine is not the same as performing an operating system shutdown. When a virtual machine is stopped, it is a cold stop (ie. it is the same as turning off the power to a computer). Any unsaved data will be lost. However, if the OS in the virtual machine supports ACPI (Advanced Configuration and Power Interface) then it can be used to shut down the virtual machine properly. ACPI is currently supported only with "stop" and "pause" operations. Corresponding functions have an additional parameter that can be used to instruct them to use ACPI.
The following sample function accepts a Vm
object identifying the target virtual machine, a code identifying the power operation to perform, and a boolean value specifying whether ACPI should be used or not. All power operations are performed asynchronously, so you should use the wait()
method with them.
def vm_action(vm, action, use_acpi):
# ACPI is used with "down" and "pause" operations only.
if action == "d" or action == "p":
try:
# Perform the specified operation.
vm.execution(action, use_acpi).wait()
except prlsdkapi.PrlSDKAsyncError, e:
print "Error: %s" % e
else:
try:
# Perform the specified operation.
vm.execution(action).wait()
except prlsdkapi.PrlSDKAsyncError, e:
print "Error: %s" % e
The following code snippet shows how to call the sample function displayed above from main()
. To obtain a Vm
object identifying the target virtual machine, we will use helper function search_vm()
that we've created in the Obtaining the Virtual Machine List section. The rest of the code (initializing API, logging in) is explained in the Creating a Basic Application section.
def main():
# Initialize API library using the "Parallels Desktop" mode.
prlsdk.InitializeSDK(consts.PAM_DESKTOP)
# Create a Server object and log on.
server = prlsdkapi.Server()
login_server(server, "localhost", "", "", prlsdk.consts.PSL_NORMAL_SECURITY);
# Obtain a handle to the Vm object for the specified virtual machine.
vm = search_vm(server, "Windows XP")
# If the virtual machine was found, perform a power operation on it.
# The operation codes (a character) are explained below.
# Uncomment a desired operation section to perform a
# particular operation.
if isinstance(vm, prlsdkapi.Vm):
print "Starting " + vm.name
vm_action(vm, "u", True)
#print "Stopping " + vm.name
#vm_action(vm, "d", False)
#print "Pausing " + vm.name
#vm_action(vm, "p", False)
#print "Resetting " + vm.name
#vm_action(vm, "r", False)
#print "Suspending " + vm.name
#vm_action(vm, "s", False)
#print "Resuming " + vm.name
#vm_action(vm, "e", False)
else: print "Virtual machine with specified name was not found."