Transcription
ParallelsVirtualization SDKProgrammer's GuideCopyright 1999-2009 Parallels Holdings, Ltd.
ISBN: N/AParallels Holdings, Ltd.c/o Parallels Software, Inc.13755 Sunrise Valley DriveSuite 600Herndon, VA 20171USATel: 1 (703) 815 5670Fax: 1 (703) 815 5675Copyright 1999-2009 Parallels Holdings, Ltd. and its affiliates. All rights reserved.Parallels, Coherence, Parallels Transporter, Parallels Compressor, Parallels Desktop, and Parallels Explorerare registered trademarks of Parallels Software International, Inc. Virtuozzo, Plesk, HSPcomplete, andcorresponding logos are trademarks of Parallels Holdings, Ltd. The Parallels logo is a trademark of ParallelsHoldings, Ltd.This product is based on a technology that is the subject matter of a number of patent pending applications.Virtuozzo is a patented virtualization technology protected by U.S. patents 7,099,948; 7,076,633; 6,961,868 andhaving patents pending in the U.S.Plesk and HSPcomplete are patented hosting technologies protected by U.S. patents 7,099,948; 7,076,633 andhaving patents pending in the U.S.Distribution of this work or derivative of this work in any form is prohibited unless prior written permission isobtained from the copyright holder.Apple, Bonjour, Finder, Mac, Macintosh, and Mac OS are trademarks of Apple Inc.Microsoft, Windows, Microsoft Windows, MS-DOS, Windows NT, Windows 95, Windows 98, Windows 2000,Windows XP, Windows Server 2003, Windows Vista, Windows Server 2008, Microsoft SQL Server, MicrosoftDesktop Engine (MSDE), and Microsoft Management Console are trademarks or registered trademarks ofMicrosoft Corporation.Linux is a registered trademark of Linus Torvalds.Red Hat is a registered trademark of Red Hat Software, Inc.SUSE is a registered trademark of Novell, Inc.Solaris is a registered trademark of Sun Microsystems, Inc.X Window System is a registered trademark of X Consortium, Inc.UNIX is a registered trademark of The Open Group.IBM DB2 is a registered trademark of International Business Machines Corp.SSH and Secure Shell are trademarks of SSH Communications Security, Inc.MegaRAID is a registered trademark of American Megatrends, Inc.PowerEdge is a trademark of Dell Computer Corporation.eComStation is a trademark of Serenity Systems International.FreeBSD is a registered trademark of the FreeBSD Foundation.Intel, Pentium, Celeron, and Intel Core are trademarks or registered trademarks of Intel Corporation.OS/2 Warp is a registered trademark of International Business Machines Corporation.VMware is a registered trademark of VMware, Inc.All other marks and names mentioned herein may be trademarks of their respective owners.
3ContentsGetting Started5Overview. 5System Requirements. 6Mac OS X Clients . 6Windows Clients. 6Linux Clients. 7Common Network Requirements. 7Parallels C API Concepts8Compiling Client Applications. 8Mac OS X . 8Windows . 18Linux. 19Handles . 20Synchronous Functions . 21Asynchronous Functions. 22Strings as Return Values . 26Error Handling . 28Parallels C API by Example30Obtaining Server Handle and Logging In . 31Host Operations. 35Retrieving Host Configuration Information. 36Managing Parallels Service Preferences . 39Searching for Parallels Servers . 42Managing Parallels Service Users. 45Managing Files In The Host OS . 50Managing Licenses . 53Obtaining a Problem Report . 55Virtual Machine Operations . 57Obtaining the Virtual Machines List. 58Searching for Virtual Machine by Name . 61Obtaining Virtual Machine Configuration Information . 63Determining Virtual Machine State . 65Starting, Stopping, Resetting a Virtual Machine. 68Suspending and Pausing a Virtual Machine. 69Creating a New Virtual Machine . 71Searching for Virtual Machines . 74Adding an Existing Virtual Machine . 78Cloning a Virtual Machine. 81Deleting a Virtual Machine. 83Modifying Virtual Machine Configuration. 84Managing User Access Rights . 98Working with Virtual Machine Templates . 100Events. 109Receiving and Handling Events. 110Responding to Parallels Service Questions. 113Performance Statistics. 120Obtaining Performance Report . 121
Contents4Performance Monitoring. 124Parallels Python API Concepts129Package and Modules. 130Classes. 131Class Methods . 131Synchronous Methods. 131Asynchronous Methods . 132Error Handling . 134Parallels Python API by Example135Creating a Basic Application. 136Connecting to Parallels Service and Logging In . 139Host Operations. 142Retrieving Host Configuration Info . 142Managing Parallels Service Preferences . 144Virtual Machine Operations . 145Obtaining the Virtual Machine List . 146Searching for a Virtual Machine. 148Performing Power Operations. 149Creating a New Virtual Machine . 150Obtaining Virtual Machine Configuration Data. 152Modifying Virtual Machine Configuration. 155Adding an Existing Virtual Machine . 162Removing an Existing Virtual Machine. 163Cloning a Virtual Machine. 164Remote Desktop Access. 165Creating a Simple OS Installation Program . 166Index170
5CHAPTER 1Getting StartedIn This ChapterOverview . 5System Requirements. 6OverviewParallels Virtualization SDK is a development kit used to create and integrate custom softwaresolutions with Parallels virtualization products. The SDK provides cross-platform ANSI C andPython APIs. The SDK can be used to develop software for any hypervisor-based Parallelsvirtualization product such as Parallels Server, Parallels Workstation, and Parallels Desktop.The SDK comprises the following components: C header files. Dynamic libraries. Python package for developing client applications in Python. Parallels command line tools (prlctl, prlsrvctl) -- a command line utility that canbe used to perform a full range of host and virtual machine operations. Parallels Virtualization SDK Programmer's Guide (this document). Parallels C API Reference Guide. Parallels Python API Reference Guide. Parallels Command Line Reference Guide.
Getting Started6System RequirementsMac OS X ClientsHardware Requirements Intel-powered Core Duo or Core Solo Mac Mini, iMac , MacBook , MacBook Pro,MacBook Air, Mac Pro, or Xserve. Ethernet or WiFi network adapter.Software Requirements Mac OS X Tiger 10.4.8 or later. Mac OS X Leopard 10.5.2 or later. Parallels Python API requires Python 2.5. Other versions of Python are not officiallysupported.Windows ClientsHardware Requirements Intel-compatible x86 (32-bit) or x64 (64-bit) processor. Ethernet or WiFi network adapter.Software Requirements Windows 2000 or higher. The Parallels Python API requires Python 2.5. Other versions of Python are not officiallysupported.
Getting Started7Linux ClientsHardware Requirements Intel-compatible x86 (32-bit) or x64 (64-bit) processor. Ethernet network adapter.Software Requirements Red Hat Enterprise Linux WS4 (x32, x64). Red Hat Enterprise Linux AS4 (x32, x64). Red Hat Enterprise Linux ES4 (x32, x64). Red Hat Enterprise Linux 5 (x32, x64) CentOS 4.x (x32, x64). CentOS 5.0 (x32, x64). CentOS 5.1 (x32, x64). Ubuntu Server 7.10 (x32, x64). SUSE Linux Enterprise Server 10 SP1 (x32, x64).Common Network RequirementsParallels ServerWhen creating client applications for Parallels Server, your client computer must be able toestablish a network connection with the host computer running the server. The client computercan be connected to a local area network via a wired or a wireless interface. Clientscommunicate with a server via TCP/IP. The server is listening on port 6400. Please make surethat the port is not blocked by a firewall.Parallels Desktop and Parallels WorkstationRemote connections to the Parallels Service are not allowed with Parallels Desktop or ParallelsWorkstation. With these products, you can run your client applications on the host computeronly.
8CHAPTER 2Parallels C API ConceptsIn This ChapterCompiling Client Applications . 8Handles. 20Synchronous Functions . 21Asynchronous Functions. 22Strings as Return Values . 26Error Handling . 28Compiling Client ApplicationsMac OS XParallels Virtualization SDK for Mac OS X is provided as a framework. The framework isinstalled in the following ionSDK.frameworkYou can use the framework just like any other Apple framework when creating developmentprojects and compiling applications. Alternately, you can compile and build your applicationswithout using the framework. In such a case, you will have to specify all the necessary paths tothe SDK source files manually.When using the framework, the dynamic library, which is supplied with the SDK, will bedirectly linked to the application. If you would like to load the dynamic library at runtime, theParallels Virtualization SDK includes a convenient dlopen wrapper for this purpose calledSdkWrap. Using the wrapper, you can load and unload the library symbols at any time with onesimple call. Please note that in order to use SdkWrap, you must compile your applicationwithout using the framework. The wrapper source files are located in the Helpers/SdkWrapdirectory, which is located in the main SDK installation directory.The following subsections describe various compilation scenarios in detail and provide codesamples.
Parallels C API Concepts9Compiling with SdkWrapWhen using SdkWrap, your program must contain the following: The #include "SdkWrap.h" directive. This header file defines the wrapper functions. The #define SDK LIB NAME "libprl sdk.dylib" directive. This is the name ofthe dynamic library included in the SDK. The SdkWrap Load(SDK LIB NAME) function call that will load the dynamic librarysymbols. The SdkWrap Unload() function call that will unload the dynamic library when it is nolonger needed.To compile a program, the following compiler options and instructions must be used: The DYN API WRAP preprocessor macro must be defined. Full paths to the Headers and the Helpers/SdkWrap directories must be specified.Both directories are located in the main SDK installation directory. The SdkWrap.cpp file must be included in the project and must be built together with themain target. The libdl library must be linked to the application. This is the standard dynamic linkinginterface library needed to load the SDK library.Using MakefileThe following is a sample Makefile that demonstrates the implementation of the requirementsdescribed above. To compile a program and to build an executable, type make in the Terminalwindow. To clean up the project, type make clean. Please note that the SOURCE variablemust contain the name of your source file name.# Source file name.# Substitute the file name with your own.SOURCE HelloWorld# Target executable file name.# Here we are using the same name as the source file name.TARGET (SOURCE)# Path to the Parallels Virtualization SDK files.SDK PATH mework# Relative path to the SdkWrap directory containing# the SDK helper files. The files are used to load# the dynamic library.SDK WRAP PATH Helpers/SdkWrapOBJS SdkWrap.o (SOURCE).oCXX g CXXFLAGS -DDYN API WRAP -I (SDK PATH)/Headers -I (SDK PATH)/ (SDK WRAP PATH)LDFLAGS -ldlall : (TARGET) (TARGET) : (OBJS) (CXX) -o @ (LDFLAGS) (OBJS) (SOURCE).o : (SOURCE).cpp (CXX) -c -o @ (CXXFLAGS) (SOURCE).cpp
Parallels C API Concepts10SdkWrap.o : (SDK PATH)/ (SDK WRAP PATH)/SdkWrap.cpp (CXX) -c -o @ (CXXFLAGS) (SDK PATH)/ (SDK WRAP PATH)/SdkWrap.cppclean:@rm -f (OBJS) (TARGET).PHONY : all cleanUsing Xcode IDEIf you are using the Xcode IDE, follow these steps to set up your project:1 Add the SdkWrap.h and the SdkWrap.cpp files to your project.2 In the Search Paths collection, specify: a full path to the Helpers/SdkWrap directory (contains the wrapper source files). a full path to the Headers directory (contains the SDK he
When creating client applications for Parallels Server, your client computer must be able to establish a network connection with the host computer running the server. The client computer can be connected to a local area network via a wired or a wireless interface. Clients communicate with a server via TCP/I
