Previous page

Next page

Locate page in Contents

Print this page

Obtaining the Virtual Machine List

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:

  1. Using the 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.
  2. Using the 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

Please send us your feedback on this help page