Creating a Basic Application

The following steps are required in any client application using the Parallels Python API:

1. Import the prlsdkapi package. This is the main Parallels Python API package containing classes, functions, variables, and additional modules.
2. Initialize the API using the prlsdkapi.prlsdk.InitializeSDK() function. The function accepts a parameter specifying the type of the Parallels product that the application will be connecting to. For Parallels Server, the value must be prlsdkapi.prlsdk.consts.PAM_SERVER . For Parallels Desktop, the value is prlsdkapi.prlsdk.consts.PAM_DESKTOP . Failure to specify the correct product type may result in incorrect library initialization and inability to work with the API. By default, the library is initialized for Parallels Server operations.
3. Create an object of class prlsdkapi.Server . The Server object provides methods for logging in and for obtaining other object references (a virtual machine object in particular). Please note that prlsdkapi.Server is a descendant of the prlsdkapi.prlsdk.BaseServer class. Some of the methods (specifically the login methods described below) are inherited from the base class.
4. Perform a login operation using the Server.login() or Server.login_local() method. Use the proper method depending on the Parallels product type and your application specifics. Parallels Server allows local and remote logins, so both methods can be used. Parallels Desktop accepts local logins only, so only the Server.login_local() method is applicable. We will discuss login operations in greater detail in the Connecting and Logging In to a Host section .

To exit gracefully, the client application should perform the following steps:

1. Log off using the Server.logoff() method. The method does not accept any parameters and simply ends the client session.
2. Deinitialize the API using the DeinitializeSDK() function.

The following is a complete Python program that illustrates the implementation of the steps above. The program assumes that it will be run on the same machine where a Parallels Server or a Parallels Desktop is installed. If you are using Parallels Server and would like to run the program on a remote client, do the following: in the main() function, uncomment "# Initialize API library using the 'Parallels Server' mode" and "# Remote login" code blocks and comment out their "Desktop" and "local" counterparts.

#!/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 constants for easy referencing of the Parallels Python API modules.

prlsdk = prlsdkapi.prlsdk

consts = prlsdkapi.prlsdk.consts

# An exception class to use to terminate the 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:     User name.

@param password: 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

#######################################

# Main program.                       #

#######################################

def main():

# Initialize API library using the "Parallels Desktop" mode.

prlsdk.InitializeSDK(consts.PAM_DESKTOP)

# Initialize API library using the "Parallels Server" mode.

# prlsdk.InitializeSDK(consts.PAM_SERVER)

# Create a Server object.

server = prlsdkapi.Server()

# Local login.

login_server(server, "localhost", "", "", consts.PSL_NORMAL_SECURITY)

# Remote login. Use your own IP address, user name, and password.

# login_server(server, 10.30.20.19, "johndoe", "secret", consts.PSL_NORMAL_SECURITY)

# Now that the connection is established, the server object

# can be used for other operations, such as obtaining virtual machine

# object references and others.

# ......

# Log off and deinitialize the library.

server.logoff()

prlsdk. DeinitializeSDK ()

if __name__ == "__main__":

try:

sys.exit(main())

except Halt:

pass

To run the program, save it as a text file with the .py extension and then execute it from the command prompt as follows:

Python program_name.py

where program_name.py is the name of the file that you saved the program to.

Please send us your feedback on this help page