Obtaining the Virtual Machine List

Before a virtual machine can be powered on, it must be registered with the Parallels Service. All new virtual machines created with Parallels management tools are registered by default. Some virtual machines can exist on the host without being registered. This can happen if the virtual machine files were copied from another location or computer or if the virtual machine was intentionally removed from the Parallels Service registry. The list of the machines that are registered with Parallels Service can be retrieved using the get_vm_list method of the prlsdkapi.Server class. The method obtains a prlsdkapi.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. Once we obtain the Result object, we will have to extract individual Vm objects from it using Result.get_params_count and Result.get_param methods. The first method returns the Vm object count. The second method returns a Vm object specified by its index inside the container.

The following example shows how obtain the virtual machine list. The sample functions accepts a prldsdkapi.Server object. Before passing it to the function, 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

"""

    Obtain a list of the existing virtual machines and print it

    on the screen.

    @param server: An instance of prlsdkapi.Server

                   identifying the Parallels Service.

"""

def get_vm_list(server):

    # Obtain the virtual machine list.

    # get_vm_list is an asynchronous method that returns

    # a prlsdkapi.Result object containing the list of virtual machines.

    job = server.get_vm_list()

    result = job.wait()

    print "Virtual Machine" + "                 " + "State"

    print "--------------------------------------------------"

    # Iterate through the Result object parameters.

    # Each parameter is an instance of the prlsdkapi.Vm class.

    for i in range(result.get_params_count()):

        vm = result.get_param_by_index(i)

        # Obtain the prlsdkapi.VmConfig object containing

        # the virtual machine

        # configuration information.

        vm_config = vm.get_config()

        # Get the name of the virtual machine.        

        vm_name = vm_config.get_name()

        # Obtain the VmInfo object containing the

        # virtual machine state info.

        # The object is obtained from the Result object returned by

        # the vm.get_state() method.

        try:

            state_result = vm.get_state().wait()

        except prlsdkapi.PrlSDKError, e:

            print "Error: %s" % e

            return

        # Now obtain the VmInfo object.

        vm_info = state_result.get_param()

        # Get the virtual machine state code.        

        state_code = vm_info.get_state()

        state_desc = "unknown status"

        # Translate the state code into a readable description.

        # For the complete list of states, see the

        # VMS_xxx constants in the Python API Reference guide.

        if state_code == consts.VMS_RUNNING:

            state_desc = "running"        

        elif state_code == consts.VMS_STOPPED:

            state_desc = "stopped"

        elif state_code == consts.VMS_PAUSED:

            state_desc = "paused"

        elif state_code == consts.VMS_SUSPENDED:

            state_desc = "suspended"

        # Print the virtual machine name and status on the screen.

        vm_name = vm_name + "                         "

        print vm_name[:25] + "\t" + state_desc

    print "--------------------------------------------------"