Oracle VM VirtualBox编程指南与参考

5星 · 超过95%的资源需积分: 50 132 浏览量更新于2024-07-31 收藏 1.9MB PDF 举报

"Oracle VM VirtualBox Programming Guide and Reference 版本4.1.0是针对VirtualBox虚拟机的二次开发文档，由Oracle Corporation在2004-2011年间发布。该文档主要介绍了VirtualBox的模块化结构、两种形式的主要API（Web服务或COM/XPCOM）以及如何使用不同环境进行开发，包括Java、Python和PHP的Web服务对象接口，以及原始Web服务和COM/XPCOM接口的使用方法。" VirtualBox的二次开发涉及多个方面，首先文档强调了其设计的模块化特性，这是构建VirtualBox的基础。模块化允许开发者更灵活地对特定功能进行扩展和定制，同时保持系统的稳定性和可维护性。文档中提到，VirtualBox的主API有两种表现形式：Web服务和COM/XPCOM。Web服务是通过网络调用来访问和控制VirtualBox的一种方式，它既可以作为独立的服务运行，也可以与其他应用程序集成。而COM（Component Object Model）和XPCOM（Cross-Platform Component Object Model）则是面向对象的接口，主要在Windows和非Windows系统上用于组件间的通信。关于Web服务，文档提供了启动服务的命令行选项和认证流程，特别提到了在Solaris主机上通过SMF（Service Management Facility）启动服务的方法。此外，文档还区分了使用Web服务的不同环境，如使用JAX-WS的Java对象接口、Python对象接口和PHP对象接口。对于那些不依赖特定环境的开发者，文档提供了如何使用原始Web服务的示例，包括用Java的Axis库和Perl进行的示例，并讨论了在使用原始Web服务时需要注意的编程考虑。最后，文档深入探讨了直接使用COM/XPCOM进行开发，包括Python COM API、通用Python绑定层以及C++ COM API。在使用这些接口时，开发者需要理解事件队列处理，因为VirtualBox的异步性质意味着某些操作可能需要等待事件完成。 VirtualBox的二次开发文档是一份详尽的指南，涵盖了从基础API使用到高级编程技巧，旨在帮助开发者有效地利用VirtualBox的开放源代码特性来创建自定义解决方案或扩展功能。无论是Java、Python还是C++开发者，都能从中找到适用的工具和方法来实现他们的目标。

1 Introduction

VirtualBox comes with comprehensive support for third-party developers. This Software Devel-

opment Kit (SDK) contains all the documentation and interface ﬁles that are needed to write

code that interacts with VirtualBox.

1.1 Modularity: the building blocks of VirtualBox

VirtualBox is cleanly separated into several layers, which can be visualized like in the picture

below:

The orange area represents code that runs in kernel mode, the blue area represents userspace

code.

At the bottom of the stack resides the hypervisor – the core of the virtualization engine, con-

trolling execution of the virtual machines and making sure they do not conﬂict with each other

or whatever the host computer is doing otherwise.

On top of the hypervisor, additional internal modules provide extra functionality. For example,

the RDP server, which can deliver the graphical output of a VM remotely to an RDP client, is a

separate module that is only loosely tacked into the virtual graphics device. Live Migration and

Resource Monitor are additional modules currently in the process of being added to VirtualBox.

What is primarily of interest for purposes of the SDK is the API layer block that sits on top of

all the previously mentioned blocks. This API, which we call the “Main API”, exposes the entire

feature set of the virtualization engine below. It is completely documented in this SDK Reference

– see chapter 5, Classes (interfaces), page 44 and chapter 6, Enumerations (enums), page 260

– and available to anyone who wishes to control VirtualBox programmatically. We chose the

name “Main API” to differentiate it from other programming interfaces of VirtualBox that may

be publicly accessible.

With the Main API, you can create, conﬁgure, start, stop and delete virtual machines, retrieve

performance statistics about running VMs, conﬁgure the VirtualBox installation in general, and

1 Introduction

more. In fact, internally, the front-end programs VirtualBox and VBoxManage use nothing but

this API as well – there are no hidden backdoors into the virtualization engine for our own front-

ends. This ensures the entire Main API is both well-documented and well-tested. (The same

applies to VBoxHeadless, which is not shown in the image.)

1.2 Two guises of the same “Main API”: the web service or

COM/XPCOM

There are several ways in which the Main API can be called by other code:

1. VirtualBox comes with a web service that maps nearly the entire Main API. The web ser-

vice ships in a stand-alone executable (vboxwebsrv) that, when running, acts as an HTTP

server, accepts SOAP connections and processes them.

Since the entire web service API is publicly described in a web service description ﬁle (in

WSDL format), you can write client programs that call the web service in any language with

a toolkit that understands WSDL. These days, that includes most programming languages

that are available: Java, C++, .NET, PHP, Python, Perl and probably many more.

All of this is explained in detail in subsequent chapters of this book.

There are two ways in which you can write client code that uses the web service:

a) For Java as well as Python, the SDK contains easy-to-use classes that allow you to use

the web service in an object-oriented, straightforward manner. We shall refer to this

as the “object-oriented web service (OOWS)“.

The OO bindings for Java are described in chapter 10, Using Java API, page 294, those

for Python in chapter 2.1.2, The object-oriented web service for Python, page 24.

b) Alternatively, you can use the web service directly, without the object-oriented client

layer. We shall refer to this as the “raw web service”.

You will then have neither native object orientation nor full type safety, since web

services are neither object-oriented nor stateful. However, in this way, you can write

client code even in languages for which we do not ship object-oriented client code; all

you need is a programming language with a toolkit that can parse WSDL and generate

client wrapper code from it.

We describe this further in chapter 2.2, Using the raw web service with any language,

page 25, with samples for Java and Perl.

2. Internally, for portability and easier maintenance, the Main API is implemented using the

Component Object Model (COM), an interprocess mechanism for software components

originally introduced by Microsoft for Microsoft Windows. On a Windows host, VirtualBox

will use Microsoft COM; on other hosts where COM is not present, it ships with XPCOM,

a free software implementation of COM originally created by the Mozilla project for their

browsers.

So, if you are familiar with COM and the C++ programming language (or with any other

programming language that can handle COM/XPCOM objects, such as Java, Visual Basic or

C#), then you can use the COM/XPCOM API directly. VirtualBox comes with all necessary

ﬁles and documentation to build fully functional COM applications. For an introduction,

please see chapter 2.3, Using COM/XPCOM directly, page 31 below.

The VirtualBox front-ends (the graphical user interfaces as well as the command line),

which are all written in C++, use COM/XPCOM to call the Main API. Technically, the web

service is another front-end to this COM API, mapping almost all of it to SOAP clients.

If you wonder which way to choose, here are a few comparisons:

1 Introduction

Web service COM/XPCOM

Pro: Easy to use with Java and Python with the

object-oriented web service; extensive support

even with other languages (C++, .NET, PHP,

Perl and others)

Con: Usable from languages where

COM bridge available (most languages

on Windows platform, Python and C++

on other hosts)

Pro: Client can be on remote machine Con: Client must be on the same host

where virtual machine is executed

Con: Signiﬁcant overhead due to XML

marshalling over the wire for each method call

Pro: Relatively low invocation overhead

In the following chapters, we will describe the different ways in which to program VirtualBox,

starting with the method that is easiest to use and then increase complexity as we go along.

1.3 About web services in general

Web services are a particular type of programming interface. Whereas, with “normal” program-

ming, a program calls an application programming interface (API) deﬁned by another program

or the operating system and both sides of the interface have to agree on the calling convention

and, in most cases, use the same programming language, web services use Internet standards

such as HTTP and XML to communicate.

In order to successfully use a web service, a number of things are required – primarily, a web

service accepting connections; service descriptions; and then a client that connects to that web

service. The connections are governed by the SOAP standard, which describes how messages

are to be exchanged between a service and its clients; the service descriptions are governed by

WSDL.

In the case of VirtualBox, this translates into the following three components:

1. The VirtualBox web service (the “server”): this is the vboxwebsrv executable shipped with

VirtualBox. Once you start this executable (which acts as a HTTP server on a speciﬁc

TCP/IP port), clients can connect to the web service and thus control a VirtualBox installa-

tion.

2. VirtualBox also comes with WSDL ﬁles that describe the services provided by the web ser-

vice. You can ﬁnd these ﬁles in the sdk/bindings/webservice/ directory. These ﬁles are

understood by the web service toolkits that are shipped with most programming languages

and enable you to easily access a web service even if you don’t use our object-oriented

client layers. VirtualBox is shipped with pregenerated web service glue code for several

languages (Python, Perl, Java).

3. A client that connects to the web service in order to control the VirtualBox installation.

Unless you play with some of the samples shipped with VirtualBox, this needs to be written

by you.

In some ways, web services promise to deliver the same thing as CORBA and DCOM did years ago. However, while

these previous technologies relied on speciﬁc binary protocols and thus proved to be difﬁcult to use between diverging

platforms, web services circumvent these incompatibilities by using text-only standards like HTTP and XML. On the

downside (and, one could say, typical of things related to XML), a lot of standards are involved before a web service

can be implemented. Many of the standards invented around XML are used one way or another. As a result, web

services are slow and verbose, and the details can be incredibly messy. The relevant standards here are called SOAP

and WSDL, where SOAP describes the format of the messages that are exchanged (an XML document wrapped in

an HTTP header), and WSDL is an XML format that describes a complete API provided by a web service. WSDL in

turn uses XML Schema to describe types, which is not exactly terse either. However, as you will see from the samples

provided in this chapter, the VirtualBox web service shields you from these details and is easy to use.

1 Introduction

1.4 Running the web service

The web service ships in an stand-alone executable, vboxwebsrv, that, when running, acts as

a HTTP server, accepts SOAP connections and processes them – remotely or from the same

machine.

Note: The web service executable is not contained with the VirtualBox SDK, but instead

ships with the standard VirtualBox binary package for your speciﬁc platform. Since the

SDK contains only platform-independent text ﬁles and documentation, the binaries are

instead shipped with the platform-speciﬁc packages.

The vboxwebsrv program, which implements the web service, is a text-mode (console) pro-

gram which, after being started, simply runs until it is interrupted with Ctrl-C or a kill command.

Once the web service is started, it acts as a front-end to the VirtualBox installation of the user

account that it is running under. In other words, if the web service is run under the user account

of user1, it will see and manipulate the virtual machines and other data represented by the

VirtualBox data of that user (e.g., on a Linux machine, under /home/user1/.VirtualBox; see

the VirtualBox User Manual for details on where this data is stored).

1.4.1 Command line options of vboxwebsrv

The web service supports the following command line options:

• --help (or -h): print a brief summary of command line options.

• --background (or -b): run the web service as a background daemon. This option is not

supported on Windows hosts.

• --host (or -H): This speciﬁes the host to bind to and defaults to “localhost”.

• --port (or -p): This speciﬁes which port to bind to on the host and defaults to 18083.

• --timeout (or -t): This speciﬁes the session timeout, in seconds, and defaults to 300 (ﬁve

minutes). A web service client that has logged on but makes no calls to the web service

will automatically be disconnected after the number of seconds speciﬁed here, as if it had

called the IWebSessionManager::logoff() method provided by the web service itself.

It is normally vital that each web service client call this method, as the web service can

accumulate large amounts of memory when running, especially if a web service client does

not properly release managed object references. As a result, this timeout value should not

be set too high, especially on machines with a high load on the web service, or the web

service may eventually deny service.

• --check-interval (or -i): This speciﬁes the interval in which the web service checks

for timed-out clients, in seconds, and defaults to 5. This normally does not need to be

changed.

• --verbose (or -v): Normally, the webservice outputs only brief messages to the console

each time a request is served. With this option, the webservice prints much more detailed

data about every request and the COM methods that those requests are mapped to inter-

nally, which can be useful for debugging client programs.

• --logfile (or -F) <file>: If this is speciﬁed, the webservice not only prints its output to

the console, but also writes it to the speciﬁed ﬁle. The ﬁle is created if it does not exist;

if it does exist, new output is appended to it. This is useful if you run the webservice

unattended and need to debug problems after they have occurred.

1 Introduction

1.4.2 Authenticating at web service logon

As opposed to the COM/XPCOM variant of the Main API, a client that wants to use the web ser-

vice must ﬁrst log on by calling the IWebsessionManager::logon() API (see chapter 5.105.3,

logon, page 259) that is speciﬁc to the web service. Logon is necessary for the web service to be

stateful; internally, it maintains a session for each client that connects to it.

The IWebsessionManager::logon() API takes a user name and a password as arguments,

which the web service then passes to a customizable authentication plugin that performs the

actual authentication.

For testing purposes, it is recommended that you ﬁrst disable authentication with this com-

mand:

VBoxManage setproperty websrvauthlibrary null

Warning: This will cause all logons to succeed, regardless of user name or password.

This should of course not be used in a production environment.

Generally, the mechanism by which clients are authenticated is conﬁgurable by way of the

VBoxManage command:

VBoxManage setproperty websrvauthlibrary default|null|<library>

This way you can specify any shared object/dynamic link module that conforms with the

speciﬁcations for VirtualBox external authentication modules as laid out in section VRDE au-

thentication of the VirtualBox User Manual; the web service uses the same kind of modules as

the VirtualBox VRDE server. For technical details on VirtualBox external authentication modules

see chapter 9, VirtualBox external authentication modules, page 292

By default, after installation, the web service uses the VBoxAuth module that ships with

VirtualBox. This module uses PAM on Linux hosts to authenticate users. Any valid user-

name/password combination is accepted, it does not have to be the username and password

of the user running the webservice daemon. Unless vboxwebsrv runs as root, PAM authenti-

cation can fail, because sometimes the ﬁle /etc/shadow, which is used by PAM, is not read-

able. On most Linux distribution PAM uses a suid root helper internally, so make sure you test

this before deploying it. One can override this behavior by setting the environment variable

VBOX

PAM

ALLOW

INACTIVE which will suppress failures when unable to read the shadow pass-

word ﬁle. Please use this variable carefully, and only if you fully understand what you’re doing.

1.4.3 Solaris host: starting the web service via SMF

On Solaris hosts, the VirtualBox web service daemon is integrated into the SMF framework. You

can change the parameters, but don’t have to if the defaults below already match your needs:

svccfg -s svc:/application/virtualbox/webservice:default setprop config/host=localhost

svccfg -s svc:/application/virtualbox/webservice:default setprop config/port=18083

svccfg -s svc:/application/virtualbox/webservice:default setprop config/user=root

If you made any change, don’t forget to run the following command to put the changes into

effect immediately:

svcadm refresh svc:/application/virtualbox/webservice:default

If you forget the above command then the previous settings will be used when enabling the

service. Check the current property settings with:

svcprop -p config svc:/application/virtualbox/webservice:default

剩余303页未读，继续阅读

aspirefhaha

粉丝: 1
资源: 6

Oracle VM VirtualBox编程指南与参考

VirtualBox SDK

VirtualBox编译步骤

virtualbox教程（中文）

为什么在Oracle VM VirtualBox中虚拟机复制第二次会失败

virtualbox api

ubuntu18.04安装virtualbox

VirtualBox为全局VirtualBox外部数据中的键赋值失败

linux系统virtualbox下载

virtualboxSDK

VirtualBox

最新资源