Before a virtual machine can be powered on, it must be registered with the Parallels Service. The list of the machines that are already registered can be retrieved using the prlsdkapi.Server
class. The class provides two ways of obtaining this information:
Server.get_vm_list()
method. The method obtains a prlsdkapi.prlsdk.Result
object containing a list of prlsdkapi.Vm
objects, each of which can be used to obtain a complete information about an individual virtual machine.Server.vm_list
iterator/sequence. This property allows to iterate through the virtual machine list without the need to deal with the Result
object (it actually uses the get_vm_list
method transparently to the programmer).The examples below demonstrate both ways of obtain the virtual machine list. Using the vm_list
property is simpler, but get_vm_list()
can probably provide some additional flexibility. You can use either technique in your applications depending on your preferences.
Both sample functions below accept a prldsdkapi.Server
object. Before passing it to these functions, the object must be properly created, the API library must be initialized, and a connection with the Parallels Service must be established. Please see the Creating a Basic Application section for more information and code samples.
Example 1
In this example, we obtain the virtual machine list using the vm_list
property.
def get_vm_list(server):
# The vm_list property contains a list of Vm object.
# Iterate through it, determine virtual machine name and
# status and print them on the screen.
for vm in server.vm_list:
# vm.state is an instance of prlsdkapi.VmInfo
vm_info = vm.state
state_code = vm_info.state
state_desc = "unknown status"
# Determine the virtual machine state.
# For the complete list of states, see VMS_xxx constants.
if state_code == prlsdk.consts.VMS_RUNNING:
state_desc = "running"
elif state_code == prlsdk.consts.VMS_STOPPED:
state_desc = "stopped"
elif state_code == prlsdk.consts.VMS_PAUSED:
state_desc = "paused"
elif state_code == prlsdk.consts.VMS_SUSPENDED:
state_desc = "suspended"
print vm.name + " - " + state_desc
Example 2
In this example, the same goal is accomplished using the Server.get_vm_list
method. The method returns an instance of prlsdkapi.prlsdk.Result
class, which is a container containing a list of prlsdkapi.Vm
objects. Once we obtain the Result
object, we will have to extract individual Vm
objects from it using its own methods: get_params_count
and get_param
. The first method returns the Vm
object count. The second method returns a Vm
object specified by its index inside the container.
def get_vm_list_v2(server):
try:
result = server.get_vm_list().wait()
except prlsdkapi.PrlSDKAsyncError, e:
print "Error: %s" % e
count = result.get_params_count()
for i in range(0, count):
vm = result.get_param(i)
print vm.name + " - " vm.state.state
Example 3
This example does not really demonstrate anything new, but we will use it in later sections of this chapter. Here, we are going to write a simple helper function that accepts a virtual machine name (or a part of the name starting from the beginning) and returns a prlsdkapi.Vm
object identifying the virtual machine. This will be useful for performing tasks on a particular virtual machine, like starting and stopping it, retrieving and modifying its configuration information, etc. The function retrieves the list of the virtual machines, examines each machine name, and returns a Vm
object if the match is found.
def search_vm(server, vm_name):
for vm in server.vm_list:
if vm.name.startswith(vm_name):
return vm
Main Program Example
The following sample shows how to test the sample functions above with the sample program provided in the Creating a Basic Application section. You can save this program into a text file with the .py
extension and run it from the command line.
#!/usr/bin/env python
# -*- coding: utf-8 -*-
#
# (c) Parallels Software International, Inc. 2005-2008
#
# Example of Parallels Python API usage.
#
# Import the main Parallels Python API package.
import prlsdkapi
# Import some of the standard Python modules.
# We will not use all of them in this sample, but
# we will use them in other samples later.
import sys, time, getopt, operator, re
# Define Parallels Python API module constants for easy referencing.
prlsdk = prlsdkapi.prlsdk
consts = prlsdkapi.prlsdk.consts
# Define an exception to use to terminate our program.
class Halt(Exception):
pass
"""
Log in to Parallels Service.
@param server: A new prlsdkapi.Server object.
@param host: The host IP address. For local login specify "localhost".
@param user: A name of the host server user.
@param password: The user password.
@param security_level: Connection security level. For available options,
see consts.PSL_xxx.
"""
def login_server(server, host, user, password, security_level):
# Depending on the value of the host parameter,
# perform local or remote login.
if host=="localhost":
try:
result = server.login_local(0, security_level).wait()
except prlsdkapi.prlsdk.ParallelsError, e:
print "Login error: %s" % e
raise Halt
else:
try:
result = server.login(host, user, password, 0, security_level).wait()
except prlsdkapi.prlsdk.ParallelsError, e:
print "Login error: %s" % e
raise Halt
# Both login() and login_local() methods return an instance of
# the prlsdkapi.LoginResponse class. We can obtain some
# information about the host from it.
print "Login successful."
print "Parallels product version: " + result.product_version
print "Host OS version: " + result.host_os_version
print "Host UUID: " + result.server_uuid
# Obtain the virtual machine list.
def get_vm_list_v2(server):
try:
result = server.get_vm_list().wait()
except prlsdkapi.PrlSDKAsyncError, e:
print "Error: %s" % e
count = result.get_params_count()
for i in range(0, count):
vm = result.get_param(i)
print vm.name + " - " vm.state.state
#######################################
# Main program. #
#######################################
def main():
# Initialize API library using the "Parallels Desktop" mode.
prlsdk.InitializeSDK(consts.PAM_DESKTOP)
# Create a Server object.
server = prlsdkapi.Server()
# Log in.
login_server(server, "localhost", "", "", consts.PSL_NORMAL_SECURITY)
# Obtain the virtual machine list.
get_vm_list_v2(server)
# Log off and deinitialize the library.
server.logoff()
prlsdk.DeinitializeSDK
()
if __name__ == "__main__":
try:
sys.exit(main())
except Halt:
pass