summaryrefslogtreecommitdiffstats
path: root/doc/manual/en_US/SDKRef.xml
diff options
context:
space:
mode:
Diffstat (limited to 'doc/manual/en_US/SDKRef.xml')
-rw-r--r--doc/manual/en_US/SDKRef.xml6324
1 files changed, 6324 insertions, 0 deletions
diff --git a/doc/manual/en_US/SDKRef.xml b/doc/manual/en_US/SDKRef.xml
new file mode 100644
index 00000000..307d13f6
--- /dev/null
+++ b/doc/manual/en_US/SDKRef.xml
@@ -0,0 +1,6324 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+ Copyright (C) 2006-2023 Oracle and/or its affiliates.
+
+ This file is part of VirtualBox base platform packages, as
+ available from https://www.virtualbox.org.
+
+ This program is free software; you can redistribute it and/or
+ modify it under the terms of the GNU General Public License
+ as published by the Free Software Foundation, in version 3 of the
+ License.
+
+ This program is distributed in the hope that it will be useful, but
+ WITHOUT ANY WARRANTY; without even the implied warranty of
+ MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
+ General Public License for more details.
+
+ You should have received a copy of the GNU General Public License
+ along with this program; if not, see <https://www.gnu.org/licenses>.
+
+ SPDX-License-Identifier: GPL-3.0-only
+-->
+<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
+ "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"[
+<!ENTITY % all.entities SYSTEM "all-entities.ent">
+%all.entities;
+]>
+
+<book>
+ <bookinfo>
+ <title>&VBOX_PRODUCT;</title>
+
+ <subtitle>Programming Guide and Reference</subtitle>
+
+ <edition>Version &VBOX_VERSION_STRING;</edition>
+
+ <corpauthor>&VBOX_VENDOR;</corpauthor>
+
+ <address>http://www.virtualbox.org</address>
+
+ <copyright>
+ <year>2004-&VBOX_C_YEAR;</year>
+
+ <holder>&VBOX_VENDOR;</holder>
+ </copyright>
+ </bookinfo>
+
+ <chapter>
+ <title>Introduction</title>
+
+ <para>VirtualBox comes with comprehensive support for third-party
+ developers. This Software Development Kit (SDK) contains all the
+ documentation and interface files that are needed to write code that
+ interacts with VirtualBox.</para>
+
+ <sect1>
+ <title>Modularity: the building blocks of VirtualBox</title>
+
+ <para>VirtualBox is cleanly separated into several layers, which can be
+ visualized like in the picture below:</para>
+
+ <mediaobject>
+ <imageobject>
+ <imagedata align="center" fileref="images/vbox-components.png"
+ width="12cm"/>
+ </imageobject>
+ </mediaobject>
+
+ <para>The orange area represents code that runs in kernel mode, the blue
+ area represents userspace code.</para>
+
+ <para>At the bottom of the stack resides the hypervisor -- the core of
+ the virtualization engine, controlling execution of the virtual machines
+ and making sure they do not conflict with each other or whatever the
+ host computer is doing otherwise.</para>
+
+ <para>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.</para>
+
+ <para>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 <emphasis role="bold">"Main API"</emphasis>,
+ exposes the entire feature set of the virtualization engine below. It is
+ completely documented in this SDK Reference -- see <xref
+ linkend="sdkref_classes"/> and <xref linkend="sdkref_enums"/> -- 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.</para>
+
+ <para>With the Main API, you can create, configure, start, stop and
+ delete virtual machines, retrieve performance statistics about running
+ VMs, configure the VirtualBox installation in general, and more. In
+ fact, internally, the front-end programs
+ <computeroutput>VirtualBox</computeroutput> and
+ <computeroutput>VBoxManage</computeroutput> 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
+ <computeroutput>VBoxHeadless</computeroutput>, which is not shown in the
+ image.)</para>
+ </sect1>
+
+ <sect1 id="webservice-or-com">
+ <title>Two guises of the same "Main API": the web service or
+ COM/XPCOM</title>
+
+ <para>There are several ways in which the Main API can be called by
+ other code:<orderedlist>
+ <listitem>
+ <para>VirtualBox comes with a <emphasis role="bold">web
+ service</emphasis> that maps nearly the entire Main API. The web
+ service ships in a stand-alone executable
+ (<computeroutput>vboxwebsrv</computeroutput>) that, when running,
+ acts as an HTTP server, accepts SOAP connections and processes
+ them.</para>
+
+ <para>Since the entire web service API is publicly described in a
+ web service description file (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.</para>
+
+ <para>All of this is explained in detail in subsequent chapters of
+ this book.</para>
+
+ <para>There are two ways in which you can write client code that
+ uses the web service:<orderedlist>
+ <listitem>
+ <para>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 <emphasis role="bold">"object-oriented web
+ service (OOWS)"</emphasis>.</para>
+
+ <para>The OO bindings for Java are described in <xref
+ linkend="javaapi"/>, those for Python in <xref
+ linkend="glue-python-ws"/>.</para>
+ </listitem>
+
+ <listitem>
+ <para>Alternatively, you can use the web service directly,
+ without the object-oriented client layer. We shall refer to
+ this as the <emphasis role="bold">"raw web
+ service"</emphasis>.</para>
+
+ <para>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.</para>
+
+ <para>We describe this further in <xref
+ linkend="raw-webservice"/>, with samples for Java and
+ Perl.</para>
+ </listitem>
+ </orderedlist></para>
+ </listitem>
+
+ <listitem>
+ <para>Internally, for portability and easier maintenance, the Main
+ API is implemented using the <emphasis role="bold">Component
+ Object Model (COM), </emphasis> 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.</para>
+
+ <para>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 files and documentation to build fully functional COM
+ applications. For an introduction, please see <xref
+ linkend="api_com"/> below.</para>
+
+ <para>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.</para>
+ </listitem>
+ </orderedlist></para>
+
+ <para>If you wonder which way to choose, here are a few
+ comparisons:<table>
+ <title>Comparison web service vs. COM/XPCOM</title>
+
+ <tgroup cols="2">
+ <tbody>
+ <row>
+ <entry><emphasis role="bold">Web service</emphasis></entry>
+
+ <entry><emphasis role="bold">COM/XPCOM</emphasis></entry>
+ </row>
+
+ <row>
+ <entry><emphasis role="bold">Pro:</emphasis> 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)</entry>
+
+ <entry><emphasis role="bold">Con:</emphasis> Usable from
+ languages where COM bridge available (most languages on
+ Windows platform, Python and C++ on other hosts)</entry>
+ </row>
+
+ <row>
+ <entry><emphasis role="bold">Pro:</emphasis> Client can be on
+ remote machine</entry>
+
+ <entry><emphasis role="bold">Con: </emphasis>Client must be on
+ the same host where virtual machine is executed</entry>
+ </row>
+
+ <row>
+ <entry><emphasis role="bold">Con: </emphasis>Significant
+ overhead due to XML marshalling over the wire for each method
+ call</entry>
+
+ <entry><emphasis role="bold">Pro: </emphasis>Relatively low
+ invocation overhead</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table></para>
+
+ <para>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.</para>
+ </sect1>
+
+ <sect1 id="api_soap_intro">
+ <title>About web services in general</title>
+
+ <para>Web services are a particular type of programming interface.
+ Whereas, with "normal" programming, a program calls an application
+ programming interface (API) defined 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.<footnote>
+ <para>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 specific binary protocols and thus proved to
+ be difficult 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.</para>
+ </footnote></para>
+
+ <para>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.</para>
+
+ <para>In the case of VirtualBox, this translates into the following
+ three components:<orderedlist>
+ <listitem>
+ <para>The VirtualBox web service (the "server"): this is the
+ <computeroutput>vboxwebsrv</computeroutput> executable shipped
+ with VirtualBox. Once you start this executable (which acts as a
+ HTTP server on a specific TCP/IP port), clients can connect to the
+ web service and thus control a VirtualBox installation.</para>
+ </listitem>
+
+ <listitem>
+ <para>VirtualBox also comes with WSDL files that describe the
+ services provided by the web service. You can find these files in
+ the <computeroutput>sdk/bindings/webservice/</computeroutput>
+ directory. These files 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).</para>
+ </listitem>
+
+ <listitem>
+ <para>A client that connects to the web service in order to
+ control the VirtualBox installation.</para>
+
+ <para>Unless you play with some of the samples shipped with
+ VirtualBox, this needs to be written by you.</para>
+ </listitem>
+ </orderedlist></para>
+ </sect1>
+
+ <sect1 id="runvboxwebsrv">
+ <title>Running the web service</title>
+
+ <para>The web service ships in an stand-alone executable,
+ <computeroutput>vboxwebsrv</computeroutput>, that, when running, acts as
+ a HTTP server, accepts SOAP connections and processes them -- remotely
+ or from the same machine.<note>
+ <para>The web service executable is not contained with the
+ VirtualBox SDK, but instead ships with the standard VirtualBox
+ binary package for your specific platform. Since the SDK contains
+ only platform-independent text files and documentation, the binaries
+ are instead shipped with the platform-specific packages. For this
+ reason the information how to run it as a service is included in the
+ VirtualBox documentation.</para>
+ </note></para>
+
+ <para>The <computeroutput>vboxwebsrv</computeroutput> program, which
+ implements the web service, is a text-mode (console) program which,
+ after being started, simply runs until it is interrupted with Ctrl-C or
+ a kill command.</para>
+
+ <para>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
+ <computeroutput>user1</computeroutput>, it will see and manipulate the
+ virtual machines and other data represented by the VirtualBox data of
+ that user (for example, on a Linux machine, under
+ <computeroutput>/home/user1/.config/VirtualBox</computeroutput>; see the
+ VirtualBox User Manual for details on where this data is stored).</para>
+
+ <sect2 id="vboxwebsrv-ref">
+ <title>Command line options of vboxwebsrv</title>
+
+ <para>The web service supports the following command line
+ options:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para><computeroutput>--help</computeroutput> (or
+ <computeroutput>-h</computeroutput>): print a brief summary of
+ command line options.</para>
+ </listitem>
+
+ <listitem>
+ <para><computeroutput>--background</computeroutput> (or
+ <computeroutput>-b</computeroutput>): run the web service as a
+ background daemon. This option is not supported on Windows
+ hosts.</para>
+ </listitem>
+
+ <listitem>
+ <para><computeroutput>--host</computeroutput> (or
+ <computeroutput>-H</computeroutput>): This specifies the host to
+ bind to and defaults to "localhost".</para>
+ </listitem>
+
+ <listitem>
+ <para><computeroutput>--port</computeroutput> (or
+ <computeroutput>-p</computeroutput>): This specifies which port to
+ bind to on the host and defaults to 18083.</para>
+ </listitem>
+
+ <listitem>
+ <para><computeroutput>--ssl</computeroutput> (or
+ <computeroutput>-s</computeroutput>): This enables SSL
+ support.</para>
+ </listitem>
+
+ <listitem>
+ <para><computeroutput>--keyfile</computeroutput> (or
+ <computeroutput>-K</computeroutput>): This specifies the file name
+ containing the server private key and the certificate. This is a
+ mandatory parameter if SSL is enabled.</para>
+ </listitem>
+
+ <listitem>
+ <para><computeroutput>--passwordfile</computeroutput> (or
+ <computeroutput>-a</computeroutput>): This specifies the file name
+ containing the password for the server private key. If unspecified
+ or an empty string is specified this is interpreted as an empty
+ password (i.e. the private key is not protected by a password). If
+ the file name <computeroutput>-</computeroutput> is specified then
+ then the password is read from the standard input stream, otherwise
+ from the specified file. The user is responsible for appropriate
+ access rights to protect the confidential password.</para>
+ </listitem>
+
+ <listitem>
+ <para><computeroutput>--cacert</computeroutput> (or
+ <computeroutput>-c</computeroutput>): This specifies the file name
+ containing the CA certificate appropriate for the server
+ certificate.</para>
+ </listitem>
+
+ <listitem>
+ <para><computeroutput>--capath</computeroutput> (or
+ <computeroutput>-C</computeroutput>): This specifies the directory
+ containing several CA certificates appropriate for the server
+ certificate.</para>
+ </listitem>
+
+ <listitem>
+ <para><computeroutput>--dhfile</computeroutput> (or
+ <computeroutput>-D</computeroutput>): This specifies the file name
+ containing the DH key. Alternatively it can contain the number of
+ bits of the DH key to generate. If left empty, RSA is used.</para>
+ </listitem>
+
+ <listitem>
+ <para><computeroutput>--randfile</computeroutput> (or
+ <computeroutput>-r</computeroutput>): This specifies the file name
+ containing the seed for the random number generator. If left empty,
+ an operating system specific source of the seed.</para>
+ </listitem>
+
+ <listitem>
+ <para><computeroutput>--timeout</computeroutput> (or
+ <computeroutput>-t</computeroutput>): This specifies the session
+ timeout, in seconds, and defaults to 300 (five 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 specified here, as if it had called the
+ <computeroutput>IWebSessionManager::logoff()</computeroutput>
+ method provided by the web service itself.</para>
+
+ <para>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.</para>
+ </listitem>
+
+ <listitem>
+ <para><computeroutput>--check-interval</computeroutput> (or
+ <computeroutput>-i</computeroutput>): This specifies 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.</para>
+ </listitem>
+
+ <listitem>
+ <para><computeroutput>--threads</computeroutput> (or
+ <computeroutput>-T</computeroutput>): This specifies the maximum
+ number or worker threads, and defaults to 100. This normally does
+ not need to be changed.</para>
+ </listitem>
+
+ <listitem>
+ <para><computeroutput>--keepalive</computeroutput> (or
+ <computeroutput>-k</computeroutput>): This specifies the maximum
+ number of requests which can be sent in one web service connection,
+ and defaults to 100. This normally does not need to be
+ changed.</para>
+ </listitem>
+
+ <listitem>
+ <para><computeroutput>--authentication</computeroutput> (or
+ <computeroutput>-A</computeroutput>): This specifies the desired
+ web service authentication method. If the parameter is not
+ specified or the empty string is specified it does not change the
+ authentication method, otherwise it is set to the specified value.
+ Using this parameter is a good measure against accidental
+ misconfiguration, as the web service ensures periodically that it
+ isn't changed.</para>
+ </listitem>
+
+ <listitem>
+ <para><computeroutput>--verbose</computeroutput> (or
+ <computeroutput>-v</computeroutput>): Normally, the web service
+ outputs only brief messages to the console each time a request is
+ served. With this option, the web service prints much more detailed
+ data about every request and the COM methods that those requests
+ are mapped to internally, which can be useful for debugging client
+ programs.</para>
+ </listitem>
+
+ <listitem>
+ <para><computeroutput>--pidfile</computeroutput> (or
+ <computeroutput>-P</computeroutput>): Name of the PID file which is
+ created when the daemon was started.</para>
+ </listitem>
+
+ <listitem>
+ <para><computeroutput>--logfile</computeroutput> (or
+ <computeroutput>-F</computeroutput>)
+ <computeroutput>&lt;file&gt;</computeroutput>: If this is
+ specified, the web service not only prints its output to the
+ console, but also writes it to the specified file. The file is
+ created if it does not exist; if it does exist, new output is
+ appended to it. This is useful if you run the web service
+ unattended and need to debug problems after they have
+ occurred.</para>
+ </listitem>
+
+ <listitem>
+ <para><computeroutput>--logrotate</computeroutput> (or
+ <computeroutput>-R</computeroutput>): Number of old log files to
+ keep, defaults to 10. Log rotation is disabled if set to 0.</para>
+ </listitem>
+
+ <listitem>
+ <para><computeroutput>--logsize</computeroutput> (or
+ <computeroutput>-S</computeroutput>): Maximum size of log file in
+ bytes, defaults to 100MB. Log rotation is triggered if the file
+ grows beyond this limit.</para>
+ </listitem>
+
+ <listitem>
+ <para><computeroutput>--loginterval</computeroutput> (or
+ <computeroutput>-I</computeroutput>): Maximum time interval to be
+ put in a log file before rotation is triggered, in seconds, and
+ defaults to one day.</para>
+ </listitem>
+ </itemizedlist>
+ </sect2>
+
+ <sect2 id="websrv_authenticate">
+ <title>Authenticating at web service logon</title>
+
+ <para>As opposed to the COM/XPCOM variant of the Main API, a client
+ that wants to use the web service must first log on by calling the
+ <link linkend="IWebsessionManager__logon">IWebsessionManager::logon()</link>
+ API that is specific 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.</para>
+
+ <para>The <computeroutput>IWebsessionManager::logon()</computeroutput>
+ 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.</para>
+
+ <para>For testing purposes, it is recommended that you first disable
+ authentication with this command:
+ <screen>VBoxManage setproperty websrvauthlibrary null</screen></para>
+
+ <para><warning>
+ <para>This will cause all logons to succeed, regardless of user
+ name or password. This should of course not be used in a
+ production environment.</para>
+ </warning>Generally, the mechanism by which clients are
+ authenticated is configurable by way of the
+ <computeroutput>VBoxManage</computeroutput> command:</para>
+
+ <para><screen>VBoxManage setproperty websrvauthlibrary default|null|&lt;library&gt;</screen></para>
+
+ <para>This way you can specify any shared object/dynamic link module
+ that conforms with the specifications for VirtualBox external
+ authentication modules as laid out in section <emphasis
+ role="bold">VRDE authentication</emphasis> 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 <xref linkend="vbox-auth"/></para>
+
+ <para>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 username/password
+ combination is accepted, it does not have to be the username and
+ password of the user running the web service daemon. Unless
+ <computeroutput>vboxwebsrv</computeroutput> runs as root, PAM
+ authentication can fail, because sometimes the file
+ <computeroutput>/etc/shadow</computeroutput>, which is used by PAM, is
+ not readable. 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
+ <computeroutput>VBOX_PAM_ALLOW_INACTIVE</computeroutput> which will
+ suppress failures when unable to read the shadow password file. Please
+ use this variable carefully, and only if you fully understand what
+ you're doing.</para>
+ </sect2>
+ </sect1>
+ </chapter>
+
+ <chapter>
+ <title>Environment-specific notes</title>
+
+ <para>The Main API described in <xref linkend="sdkref_classes"/> and
+ <xref linkend="sdkref_enums"/> is mostly identical in all the supported
+ programming environments which have been briefly mentioned in the
+ introduction of this book. As a result, the Main API's general concepts
+ described in <xref linkend="concepts"/> are the same whether you use the
+ object-oriented web service (OOWS) for JAX-WS or a raw web service
+ connection via, say, Perl, or whether you use C++ COM bindings.</para>
+
+ <para>Some things are different depending on your environment, however.
+ These differences are explained in this chapter.</para>
+
+ <sect1 id="glue">
+ <title>Using the object-oriented web service (OOWS)</title>
+
+ <para>As explained in <xref linkend="webservice-or-com"/>, VirtualBox
+ ships with client-side libraries for Java, Python and PHP that allow you
+ to use the VirtualBox web service in an intuitive, object-oriented way.
+ These libraries shield you from the client-side complications of managed
+ object references and other implementation details that come with the
+ VirtualBox web service. (If you are interested in these complications,
+ have a look at <xref linkend="raw-webservice"/>).</para>
+
+ <para>We recommend that you start your experiments with the VirtualBox
+ web service by using our object-oriented client libraries for JAX-WS, a
+ web service toolkit for Java, which enables you to write code to
+ interact with VirtualBox in the simplest manner possible.</para>
+
+ <para>As "interfaces", "attributes" and "methods" are COM concepts,
+ please read the documentation in <xref linkend="sdkref_classes"/> and
+ <xref linkend="sdkref_enums"/> with the following notes in mind.</para>
+
+ <para>The OOWS bindings attempt to map the Main API as closely as
+ possible to the Java, Python and PHP languages. In other words, objects
+ are objects, interfaces become classes, and you can call methods on
+ objects as you would on local objects.</para>
+
+ <para>The main difference remains with attributes: to read an attribute,
+ call a "getXXX" method, with "XXX" being the attribute name with a
+ capitalized first letter. So when the Main API Reference says that
+ <computeroutput>IMachine</computeroutput> has a "name" attribute (see
+ <link linkend="IMachine__name">IMachine::name</link>), call
+ <computeroutput>getName()</computeroutput> on an IMachine object to
+ obtain a machine's name. Unless the attribute is marked as read-only in
+ the documentation, there will also be a corresponding "set"
+ method.</para>
+
+ <sect2 id="glue-jax-ws">
+ <title>The object-oriented web service for JAX-WS</title>
+
+ <para>JAX-WS is a powerful toolkit by Sun Microsystems to build both
+ server and client code with Java. It is part of Java 6 (JDK 1.6), but
+ can also be obtained separately for Java 5 (JDK 1.5). The VirtualBox
+ SDK comes with precompiled OOWS bindings working with both Java 5 and
+ 6.</para>
+
+ <para>The following sections explain how to get the JAX-WS sample code
+ running and explain a few common practices when using the JAX-WS
+ object-oriented web service.</para>
+
+ <sect3>
+ <title>Preparations</title>
+
+ <para>Since JAX-WS is already integrated into Java 6, no additional
+ preparations are needed for Java 6.</para>
+
+ <para>If you are using Java 5 (JDK 1.5.x), you will first need to
+ download and install an external JAX-WS implementation, as Java 5
+ does not support JAX-WS out of the box; for example, you can
+ download one from here: <ulink
+ url="https://jax-ws.dev.java.net/2.1.4/JAXWS2.1.4-20080502.jar">https://jax-ws.dev.java.net/2.1.4/JAXWS2.1.4-20080502.jar</ulink>.
+ Then perform the installation (<computeroutput>java -jar
+ JAXWS2.1.4-20080502.jar</computeroutput>).</para>
+ </sect3>
+
+ <sect3>
+ <title>Getting started: running the sample code</title>
+
+ <para>To run the OOWS for JAX-WS samples that we ship with the SDK,
+ perform the following steps: <orderedlist>
+ <listitem>
+ <para>Open a terminal and change to the directory where the
+ JAX-WS samples reside.<footnote>
+ <para>In
+ <computeroutput>sdk/bindings/glue/java/</computeroutput>.</para>
+ </footnote> Examine the header of
+ <computeroutput>Makefile</computeroutput> to see if the
+ supplied variables (Java compiler, Java executable) and a few
+ other details match your system settings.</para>
+ </listitem>
+
+ <listitem>
+ <para>To start the VirtualBox web service, open a second
+ terminal and change to the directory where the VirtualBox
+ executables are located. Then type:
+ <screen>./vboxwebsrv -v</screen></para>
+
+ <para>The web service now waits for connections and will run
+ until you press Ctrl+C in this second terminal. The -v
+ argument causes it to log all connections to the terminal.
+ (See <xref linkend="runvboxwebsrv"/> for details on how
+ to run the web service.)</para>
+ </listitem>
+
+ <listitem>
+ <para>Back in the first terminal and still in the samples
+ directory, to start a simple client example just type:
+ <screen>make run16</screen></para>
+
+ <para>if you're on a Java 6 system; on a Java 5 system, run
+ <computeroutput>make run15</computeroutput> instead.</para>
+
+ <para>This should work on all Unix-like systems such as Linux
+ and Solaris. For Windows systems, use commands similar to what
+ is used in the Makefile.</para>
+
+ <para>This will compile the
+ <computeroutput>clienttest.java</computeroutput> code on the
+ first call and then execute the resulting
+ <computeroutput>clienttest</computeroutput> class to show the
+ locally installed VMs (see below).</para>
+ </listitem>
+ </orderedlist></para>
+
+ <para>The <computeroutput>clienttest</computeroutput> sample
+ imitates a few typical command line tasks that
+ <computeroutput>VBoxManage</computeroutput>, VirtualBox's regular
+ command-line front-end, would provide (see the VirtualBox User
+ Manual for details). In particular, you can run:<itemizedlist>
+ <listitem>
+ <para><computeroutput>java clienttest show
+ vms</computeroutput>: show the virtual machines that are
+ registered locally.</para>
+ </listitem>
+
+ <listitem>
+ <para><computeroutput>java clienttest list
+ hostinfo</computeroutput>: show various information about the
+ host this VirtualBox installation runs on.</para>
+ </listitem>
+
+ <listitem>
+ <para><computeroutput>java clienttest startvm
+ &lt;vmname|uuid&gt;</computeroutput>: start the given virtual
+ machine.</para>
+ </listitem>
+ </itemizedlist></para>
+
+ <para>The <computeroutput>clienttest.java</computeroutput> sample
+ code illustrates common basic practices how to use the VirtualBox
+ OOWS for JAX-WS, which we will explain in more detail in the
+ following chapters.</para>
+ </sect3>
+
+ <sect3>
+ <title>Logging on to the web service</title>
+
+ <para>Before a web service client can do anything useful, two
+ objects need to be created, as can be seen in the
+ <computeroutput>clienttest</computeroutput> constructor:<orderedlist>
+ <listitem>
+ <para>An instance of
+ <link linkend="IWebsessionManager">IWebsessionManager</link>,
+ which is an interface provided by the web service to manage
+ "web sessions" -- that is, stateful connections to the web
+ service with persistent objects upon which methods can be
+ invoked.</para>
+
+ <para>In the OOWS for JAX-WS, the IWebsessionManager class
+ must be constructed explicitly, and a URL must be provided in
+ the constructor that specifies where the web service (the
+ server) awaits connections. The code in
+ <computeroutput>clienttest.java</computeroutput> connects to
+ "http://localhost:18083/", which is the default.</para>
+
+ <para>The port number, by default 18083, must match the port
+ number given to the
+ <computeroutput>vboxwebsrv</computeroutput> command line; see
+ <xref linkend="vboxwebsrv-ref"/>.</para>
+ </listitem>
+
+ <listitem>
+ <para>After that, the code calls
+ <link linkend="IWebsessionManager__logon">IWebsessionManager::logon()</link>,
+ which is the first call that actually communicates with the
+ server. This authenticates the client with the web service and
+ returns an instance of
+ <link linkend="IVirtualBox">IVirtualBox</link>,
+ the most fundamental interface of the VirtualBox web service,
+ from which all other functionality can be derived.</para>
+
+ <para>If logon doesn't work, please take another look at <xref
+ linkend="websrv_authenticate"/>.</para>
+ </listitem>
+ </orderedlist></para>
+ </sect3>
+
+ <sect3>
+ <title>Object management</title>
+
+ <para>The current OOWS for JAX-WS has certain memory management
+ related limitations. When you no longer need an object, call its
+ <link linkend="IManagedObjectRef__release">IManagedObjectRef::release()</link>
+ method explicitly, which
+ frees appropriate managed reference, as is required by the raw
+ web service; see <xref linkend="managed-object-references"/> for
+ details. This limitation may be reconsidered in a future version of
+ the VirtualBox SDK.</para>
+ </sect3>
+ </sect2>
+
+ <sect2 id="glue-python-ws">
+ <title>The object-oriented web service for Python</title>
+
+ <para>VirtualBox comes with two flavors of a Python API: one for web
+ service, discussed here, and one for the COM/XPCOM API discussed in
+ <xref linkend="pycom"/>. The client code is mostly similar, except
+ for the initialization part, so it is up to the application developer
+ to choose the appropriate technology. Moreover, a common Python glue
+ layer exists, abstracting out concrete platform access details, see
+ <xref linkend="glue-python"/>.</para>
+
+ <para>The minimum supported Python version is 2.6.</para>
+
+ <para>As indicated in <xref linkend="webservice-or-com"/>, the
+ COM/XPCOM API gives better performance without the SOAP overhead, and
+ does not require a web server to be running. On the other hand, the
+ COM/XPCOM Python API requires a suitable Python bridge for your Python
+ installation (VirtualBox ships the most important ones for each
+ platform<footnote>
+ <para>On On Mac OS X only the Python versions bundled with the OS
+ are officially supported. This means 2.6 and 2.7 for 10.9 and later.</para>
+ </footnote>). On Windows, you can use the Main API from Python if the
+ Win32 extensions package for Python<footnote>
+ <para>See <ulink
+ url="http://sourceforge.net/project/showfiles.php?group_id=78018">http://sourceforge.net/project/showfiles.php?group_id=78018</ulink>.</para>
+ </footnote> is installed. Versions of Python Win32 extensions earlier
+ than 2.16 are known to have bugs, leading to issues with VirtualBox
+ Python bindings, so please make sure to use latest available Python
+ and Win32 extensions.</para>
+
+ <para>The VirtualBox OOWS for Python relies on the Python ZSI SOAP
+ implementation (see <ulink
+ url="http://pywebsvcs.sourceforge.net/zsi.html">http://pywebsvcs.sourceforge.net/zsi.html</ulink>),
+ which you will need to install locally before trying the examples.
+ Most Linux distributions come with package for ZSI, such as
+ <computeroutput>python-zsi</computeroutput> in Ubuntu.</para>
+
+ <para>To get started, open a terminal and change to the
+ <computeroutput>bindings/glue/python/sample</computeroutput>
+ directory, which contains an example of a simple interactive shell
+ able to control a VirtualBox instance. The shell is written using the
+ API layer, thereby hiding different implementation details, so it is
+ actually an example of code share among XPCOM, MSCOM and web services.
+ If you are interested in how to interact with the web services layer
+ directly, have a look at
+ <computeroutput>install/vboxapi/__init__.py</computeroutput> which
+ contains the glue layer for all target platforms (i.e. XPCOM, MSCOM
+ and web services).</para>
+
+ <para>To start the shell, perform the following commands:
+ <screen>/opt/VirtualBox/vboxwebsrv -t 0
+ # start web service with object autocollection disabled
+export VBOX_PROGRAM_PATH=/opt/VirtualBox
+ # your VirtualBox installation directory
+export VBOX_SDK_PATH=/home/youruser/vbox-sdk
+ # where you've extracted the SDK
+./vboxshell.py -w </screen>
+ See <xref linkend="vboxshell"/> for more
+ details on the shell's functionality. For you, as a VirtualBox
+ application developer, the vboxshell sample could be interesting as an
+ example of how to write code targeting both local and remote cases
+ (COM/XPCOM and SOAP). The common part of the shell is the same -- the
+ only difference is how it interacts with the invocation layer. You can
+ use the <computeroutput>connect</computeroutput> shell command to
+ connect to remote VirtualBox servers; in this case you can skip
+ starting the local web server.</para>
+ </sect2>
+
+ <sect2>
+ <title>The object-oriented web service for PHP</title>
+
+ <para>VirtualBox also comes with object-oriented web service (OOWS)
+ wrappers for PHP5. These wrappers rely on the PHP SOAP
+ Extension<footnote>
+ <para>See
+ <ulink url="https://www.php.net/soap">https://www.php.net/soap</ulink>.</para>
+ </footnote>, which can be installed by configuring PHP with
+ <computeroutput>--enable-soap</computeroutput>.</para>
+ </sect2>
+ </sect1>
+
+ <sect1 id="raw-webservice">
+ <title>Using the raw web service with any language</title>
+
+ <para>The following examples show you how to use the raw web service,
+ without the object-oriented client-side code that was described in the
+ previous chapter.</para>
+
+ <para>Generally, when reading the documentation in <xref
+ linkend="sdkref_classes"/> and <xref linkend="sdkref_enums"/>, due to
+ the limitations of SOAP and WSDL lined out in <xref
+ linkend="rawws-conventions"/>, please have the following notes in
+ mind:</para>
+
+ <para><orderedlist>
+ <listitem>
+ <para>Any COM method call becomes a <emphasis role="bold">plain
+ function call</emphasis> in the raw web service, with the object
+ as an additional first parameter (before the "real" parameters
+ listed in the documentation). So when the documentation says that
+ the <computeroutput>IVirtualBox</computeroutput> interface
+ supports the <computeroutput>createMachine()</computeroutput>
+ method (see
+ <link linkend="IVirtualBox__createMachine">IVirtualBox::createMachine()</link>),
+ the web service operation is
+ <computeroutput>IVirtualBox_createMachine(...)</computeroutput>,
+ and a managed object reference to an
+ <computeroutput>IVirtualBox</computeroutput> object must be passed
+ as the first argument.</para>
+ </listitem>
+
+ <listitem>
+ <para>For <emphasis role="bold">attributes</emphasis> in
+ interfaces, there will be at least one "get" function; there will
+ also be a "set" function, unless the attribute is "readonly". The
+ attribute name will be appended to the "get" or "set" prefix, with
+ a capitalized first letter. So, the "version" readonly attribute
+ of the <computeroutput>IVirtualBox</computeroutput> interface can
+ be retrieved by calling
+ <computeroutput>IVirtualBox_getVersion(vbox)</computeroutput>,
+ with <computeroutput>vbox</computeroutput> being the VirtualBox
+ object.</para>
+ </listitem>
+
+ <listitem>
+ <para>Whenever the API documentation says that a method (or an
+ attribute getter) returns an <emphasis
+ role="bold">object</emphasis>, it will returned a managed object
+ reference in the web service instead. As said above, managed
+ object references should be released if the web service client
+ does not log off again immediately!</para>
+ </listitem>
+ </orderedlist></para>
+
+ <para></para>
+
+ <sect2 id="webservice-java-sample">
+ <title>Raw web service example for Java with Axis</title>
+
+ <para>Axis is an older web service toolkit created by the Apache
+ foundation. If your distribution does not have it installed, you can
+ get a binary from <ulink
+ url="http://www.apache.org">http://www.apache.org</ulink>. The
+ following examples assume that you have Axis 1.4 installed.</para>
+
+ <para>The VirtualBox SDK ships with an example for Axis that, again,
+ is called <computeroutput>clienttest.java</computeroutput> and that
+ imitates a few of the commands of
+ <computeroutput>VBoxManage</computeroutput> over the wire.</para>
+
+ <para>Then perform the following steps:<orderedlist>
+ <listitem>
+ <para>Create a working directory somewhere. Under your
+ VirtualBox installation directory, find the
+ <computeroutput>sdk/webservice/samples/java/axis/</computeroutput>
+ directory and copy the file
+ <computeroutput>clienttest.java</computeroutput> to your working
+ directory.</para>
+ </listitem>
+
+ <listitem>
+ <para>Open a terminal in your working directory. Execute the
+ following command:
+ <screen>java org.apache.axis.wsdl.WSDL2Java /path/to/vboxwebService.wsdl</screen></para>
+
+ <para>The <computeroutput>vboxwebService.wsdl</computeroutput>
+ file should be located in the
+ <computeroutput>sdk/webservice/</computeroutput>
+ directory.</para>
+
+ <para>If this fails, your Apache Axis may not be located on your
+ system classpath, and you may have to adjust the CLASSPATH
+ environment variable. Something like this:
+ <screen>export CLASSPATH="/path-to-axis-1_4/lib/*":$CLASSPATH</screen></para>
+
+ <para>Use the directory where the Axis JAR files are located.
+ Mind the quotes so that your shell passes the "*" character to
+ the java executable without expanding. Alternatively, add a
+ corresponding <computeroutput>-classpath</computeroutput>
+ argument to the "java" call above.</para>
+
+ <para>If the command executes successfully, you should see an
+ "org" directory with subdirectories containing Java source files
+ in your working directory. These classes represent the
+ interfaces that the VirtualBox web service offers, as described
+ by the WSDL file.</para>
+
+ <para>This is the bit that makes using web services so
+ attractive to client developers: if a language's toolkit
+ understands WSDL, it can generate large amounts of support code
+ automatically. Clients can then easily use this support code and
+ can be done with just a few lines of code.</para>
+ </listitem>
+
+ <listitem>
+ <para>Next, compile the
+ <computeroutput>clienttest.java</computeroutput>
+ source:<screen>javac clienttest.java </screen></para>
+
+ <para>This should yield a "clienttest.class" file.</para>
+ </listitem>
+
+ <listitem>
+ <para>To start the VirtualBox web service, open a second
+ terminal and change to the directory where the VirtualBox
+ executables are located. Then type:
+ <screen>./vboxwebsrv -v</screen></para>
+
+ <para>The web service now waits for connections and will run
+ until you press Ctrl+C in this second terminal. The -v argument
+ causes it to log all connections to the terminal. (See <xref
+ linkend="runvboxwebsrv"/> for details on how to run the
+ web service.)</para>
+ </listitem>
+
+ <listitem>
+ <para>Back in the original terminal where you compiled the Java
+ source, run the resulting binary, which will then connect to the
+ web service:<screen>java clienttest</screen></para>
+
+ <para>The client sample will connect to the web service (on
+ localhost, but the code could be changed to connect remotely if
+ the web service was running on a different machine) and make a
+ number of method calls. It will output the version number of
+ your VirtualBox installation and a list of all virtual machines
+ that are currently registered (with a bit of seemingly random
+ data, which will be explained later).</para>
+ </listitem>
+ </orderedlist></para>
+ </sect2>
+
+ <sect2 id="raw-webservice-perl">
+ <title>Raw web service example for Perl</title>
+
+ <para>We also ship a small sample for Perl. It uses the SOAP::Lite
+ perl module to communicate with the VirtualBox web service.</para>
+
+ <para>The
+ <computeroutput>sdk/bindings/webservice/perl/lib/</computeroutput>
+ directory contains a pre-generated Perl module that allows for
+ communicating with the web service from Perl. You can generate such a
+ module yourself using the "stubmaker" tool that comes with SOAP::Lite,
+ but since that tool is slow as well as sometimes unreliable, we are
+ shipping a working module with the SDK for your convenience.</para>
+
+ <para>Perform the following steps:<orderedlist>
+ <listitem>
+ <para>If SOAP::Lite is not yet installed on your system, you
+ will need to install the package first. On Debian-based systems,
+ the package is called
+ <computeroutput>libsoap-lite-perl</computeroutput>; on Gentoo,
+ it's <computeroutput>dev-perl/SOAP-Lite</computeroutput>.</para>
+ </listitem>
+
+ <listitem>
+ <para>Open a terminal in the
+ <computeroutput>sdk/bindings/webservice/perl/samples/</computeroutput>
+ directory.</para>
+ </listitem>
+
+ <listitem>
+ <para>To start the VirtualBox web service, open a second
+ terminal and change to the directory where the VirtualBox
+ executables are located. Then type:
+ <screen>./vboxwebsrv -v</screen></para>
+
+ <para>The web service now waits for connections and will run
+ until you press Ctrl+C in this second terminal. The -v argument
+ causes it to log all connections to the terminal. (See <xref
+ linkend="runvboxwebsrv"/> for details on how to run the
+ web service.)</para>
+ </listitem>
+
+ <listitem>
+ <para>In the first terminal with the Perl sample, run the
+ clienttest.pl script:
+ <screen>perl -I ../lib clienttest.pl</screen></para>
+ </listitem>
+ </orderedlist></para>
+ </sect2>
+
+ <sect2>
+ <title>Programming considerations for the raw web service</title>
+
+ <para>If you use the raw web service, you need to keep a number of
+ things in mind, or you will sooner or later run into issues that are
+ not immediately obvious. By contrast, the object-oriented client-side
+ libraries described in <xref linkend="glue"/> take care of these
+ things automatically and thus greatly simplify using the web
+ service.</para>
+
+ <sect3 id="rawws-conventions">
+ <title>Fundamental conventions</title>
+
+ <para>If you are familiar with other web services, you may find the
+ VirtualBox web service to behave a bit differently to accommodate
+ for the fact that VirtualBox web service more or less maps the
+ VirtualBox Main COM API. The following main differences had to be
+ taken care of:<itemizedlist>
+ <listitem>
+ <para>Web services, as expressed by WSDL, are not
+ object-oriented. Even worse, they are normally stateless (or,
+ in web services terminology, "loosely coupled"). Web service
+ operations are entirely procedural, and one cannot normally
+ make assumptions about the state of a web service between
+ function calls.</para>
+
+ <para>In particular, this normally means that you cannot work
+ on objects in one method call that were created by another
+ call.</para>
+ </listitem>
+
+ <listitem>
+ <para>By contrast, the VirtualBox Main API, being expressed in
+ COM, is object-oriented and works entirely on objects, which
+ are grouped into public interfaces, which in turn have
+ attributes and methods associated with them.</para>
+ </listitem>
+ </itemizedlist> For the VirtualBox web service, this results in
+ three fundamental conventions:<orderedlist>
+ <listitem>
+ <para>All <emphasis role="bold">function names</emphasis> in
+ the VirtualBox web service consist of an interface name and a
+ method name, joined together by an underscore. This is because
+ there are only functions ("operations") in WSDL, but no
+ classes, interfaces, or methods.</para>
+
+ <para>In addition, all calls to the VirtualBox web service
+ (except for logon, see below) take a <emphasis
+ role="bold">managed object reference</emphasis> as the first
+ argument, representing the object upon which the underlying
+ method is invoked. (Managed object references are explained in
+ detail below; see <xref
+ linkend="managed-object-references"/>.)</para>
+
+ <para>So, when one would normally code, in the pseudo-code of
+ an object-oriented language, to invoke a method upon an
+ object:<screen>IMachine machine;
+result = machine.getName();</screen></para>
+
+ <para>In the VirtualBox web service, this looks something like
+ this (again, pseudo-code):<screen>IMachineRef machine;
+result = IMachine_getName(machine);</screen></para>
+ </listitem>
+
+ <listitem>
+ <para>To make the web service stateful, and objects persistent
+ between method calls, the VirtualBox web service introduces a
+ <emphasis role="bold">session manager</emphasis> (by way of the
+ <link linkend="IWebsessionManager">IWebsessionManager</link>
+ interface), which manages object references. Any client wishing
+ to interact with the web service must first log on to the
+ session manager and in turn receives a managed object reference
+ to an object that supports the
+ <link linkend="IVirtualBox">IVirtualBox</link>
+ interface (the basic interface in the Main API).</para>
+ </listitem>
+ </orderedlist></para>
+
+ <para>In other words, as opposed to other web services, <emphasis
+ role="bold">the VirtualBox web service is both object-oriented and
+ stateful.</emphasis></para>
+ </sect3>
+
+ <sect3>
+ <title>Example: A typical web service client session</title>
+
+ <para>A typical short web service session to retrieve the version
+ number of the VirtualBox web service (to be precise, the underlying
+ Main API version number) looks like this:<orderedlist>
+ <listitem>
+ <para>A client logs on to the web service by calling
+ <link linkend="IWebsessionManager__logon">IWebsessionManager::logon()</link>
+ with a valid user name and password. See
+ <xref linkend="websrv_authenticate"/>
+ for details about how authentication works.</para>
+ </listitem>
+
+ <listitem>
+ <para>On the server side,
+ <computeroutput>vboxwebsrv</computeroutput> creates a session,
+ which persists until the client calls
+ <link linkend="IWebsessionManager__logoff">IWebsessionManager::logoff()</link>
+ or the session times out after a configurable period of
+ inactivity (see <xref linkend="vboxwebsrv-ref"/>).</para>
+
+ <para>For the new session, the web service creates an instance
+ of <link linkend="IVirtualBox">IVirtualBox</link>.
+ This interface is the most central one in the Main API and
+ allows access to all other interfaces, either through
+ attributes or method calls. For example, IVirtualBox contains
+ a list of all virtual machines that are currently registered
+ (as they would be listed on the left side of the VirtualBox
+ main program).</para>
+
+ <para>The web service then creates a managed object reference
+ for this instance of IVirtualBox and returns it to the calling
+ client, which receives it as the return value of the logon
+ call. Something like this:</para>
+
+ <screen>string oVirtualBox;
+oVirtualBox = webservice.IWebsessionManager_logon("user", "pass");</screen>
+
+ <para>(The managed object reference "oVirtualBox" is just a
+ string consisting of digits and dashes. However, it is a
+ string with a meaning and will be checked by the web service.
+ For details, see below. As hinted above,
+ <link linkend="IWebsessionManager__logon">IWebsessionManager::logon()</link>
+ is the <emphasis>only</emphasis> operation provided by the web
+ service which does not take a managed object reference as the
+ first argument!)</para>
+ </listitem>
+
+ <listitem>
+ <para>The VirtualBox Main API documentation says that the
+ <computeroutput>IVirtualBox</computeroutput> interface has a
+ <link linkend="IVirtualBox__version">version</link>
+ attribute, which is a string. For each attribute, there is a
+ "get" and a "set" method in COM, which maps to according
+ operations in the web service. So, to retrieve the "version"
+ attribute of this <computeroutput>IVirtualBox</computeroutput>
+ object, the web service client does this:
+ <screen>string version;
+version = webservice.IVirtualBox_getVersion(oVirtualBox);
+
+print version;</screen></para>
+
+ <para>And it will print
+ "&VBOX_VERSION_MAJOR;.&VBOX_VERSION_MINOR;.&VBOX_VERSION_BUILD;".</para>
+ </listitem>
+
+ <listitem>
+ <para>The web service client calls
+ <link linkend="IWebsessionManager__logoff">IWebsessionManager::logoff()</link>
+ with the VirtualBox managed object reference. This will clean
+ up all allocated resources.</para>
+ </listitem>
+ </orderedlist></para>
+ </sect3>
+
+ <sect3 id="managed-object-references">
+ <title>Managed object references</title>
+
+ <para>To a web service client, a managed object reference looks like
+ a string: two 64-bit hex numbers separated by a dash. This string,
+ however, represents a COM object that "lives" in the web service
+ process. The two 64-bit numbers encoded in the managed object
+ reference represent a session ID (which is the same for all objects
+ in the same web service session, i.e. for all objects after one
+ logon) and a unique object ID within that session.</para>
+
+ <para>Managed object references are created in two
+ situations:<orderedlist>
+ <listitem>
+ <para>When a client logs on, by calling
+ <link linkend="IWebsessionManager__logon">IWebsessionManager::logon()</link>.</para>
+
+ <para>Upon logon, the websession manager creates one instance
+ of <link linkend="IVirtualBox">IVirtualBox</link>,
+ which can be used for directly performing calls to its
+ methods, or used as a parameter for calling some methods of
+ <link linkend="IWebsessionManager">IWebsessionManager</link>.
+ Creating Main API session objects is performed using
+ <link linkend="IWebsessionManager__getSessionObject">IWebsessionManager::getSessionObject()</link>.</para>
+
+ <para>(Technically, there is always only one
+ <link linkend="IVirtualBox">IVirtualBox</link> object, which
+ is shared between all websessions and clients, as it is a COM
+ singleton. However, each session receives its own managed
+ object reference to it.)</para>
+ </listitem>
+
+ <listitem>
+ <para>Whenever a web service clients invokes an operation
+ whose COM implementation creates COM objects.</para>
+
+ <para>For example,
+ <link linkend="IVirtualBox__createMachine">IVirtualBox::createMachine()</link>
+ creates a new instance of
+ <link linkend="IMachine">IMachine</link>;
+ the COM object returned by the COM method call is then wrapped
+ into a managed object reference by the web server, and this
+ reference is returned to the web service client.</para>
+ </listitem>
+ </orderedlist></para>
+
+ <para>Internally, in the web service process, each managed object
+ reference is simply a small data structure, containing a COM pointer
+ to the "real" COM object, the web session ID and the object ID. This
+ structure is allocated on creation and stored efficiently in hashes,
+ so that the web service can look up the COM object quickly whenever
+ a web service client wishes to make a method call. The random
+ session ID also ensures that one web service client cannot intercept
+ the objects of another.</para>
+
+ <para>Managed object references are not destroyed automatically and
+ must be released by explicitly calling
+ <link linkend="IManagedObjectRef__release">IManagedObjectRef::release()</link>.
+ This is important, as
+ otherwise hundreds or thousands of managed object references (and
+ corresponding COM objects, which can consume much more memory!) can
+ pile up in the web service process and eventually cause it to deny
+ service.</para>
+
+ <para>To reiterate: The underlying COM object, which the reference
+ points to, is only freed if the managed object reference is
+ released. It is therefore vital that web service clients properly
+ clean up after the managed object references that are returned to
+ them.</para>
+
+ <para>When a web service client calls
+ <link linkend="IWebsessionManager__logoff">IWebsessionManager::logoff()</link>,
+ all managed object references created during the session are
+ automatically freed. For short-lived sessions that do not create a
+ lot of objects, logging off may therefore be sufficient, although it
+ is certainly not "best practice".</para>
+ </sect3>
+
+ <sect3>
+ <title>Some more detail about web service operation</title>
+
+ <sect4 id="soap">
+ <title>SOAP messages</title>
+
+ <para>Whenever a client makes a call to a web service, this
+ involves a complicated procedure internally. These calls are
+ remote procedure calls. Each such procedure call typically
+ consists of two "message" being passed, where each message is a
+ plain-text HTTP request with a standard HTTP header and a special
+ XML document following. This XML document encodes the name of the
+ procedure to call and the argument names and values passed to
+ it.</para>
+
+ <para>To give you an idea of what such a message looks like,
+ assuming that a web service provides a procedure called
+ "SayHello", which takes a string "name" as an argument and returns
+ "Hello" with a space and that name appended, the request message
+ could look like this:</para>
+
+ <para><screen>&lt;?xml version="1.0" encoding="UTF-8"?&gt;
+&lt;SOAP-ENV:Envelope
+ xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
+ xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/"
+ xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ xmlns:xsd="http://www.w3.org/2001/XMLSchema"
+ xmlns:test="http://test/"&gt;
+&lt;SOAP-ENV:Body&gt;
+ &lt;test:SayHello&gt;
+ &lt;name&gt;Peter&lt;/name&gt;
+ &lt;/test:SayHello&gt;
+ &lt;/SOAP-ENV:Body&gt;
+&lt;/SOAP-ENV:Envelope&gt;</screen>A similar message -- the "response" message
+ -- would be sent back from the web service to the client,
+ containing the return value "Hello Peter".</para>
+
+ <para>Most programming languages provide automatic support to
+ generate such messages whenever code in that programming language
+ makes such a request. In other words, these programming languages
+ allow for writing something like this (in pseudo-C++ code):</para>
+
+ <para><screen>webServiceClass service("localhost", 18083); // server and port
+string result = service.SayHello("Peter"); // invoke remote procedure</screen>
+ and would, for these two pseudo-lines, automatically perform these
+ steps:</para>
+
+ <para><orderedlist>
+ <listitem>
+ <para>prepare a connection to a web service running on port
+ 18083 of "localhost";</para>
+ </listitem>
+
+ <listitem>
+ <para>for the <computeroutput>SayHello()</computeroutput>
+ function of the web service, generate a SOAP message like in
+ the above example by encoding all arguments of the remote
+ procedure call (which could involve all kinds of type
+ conversions and complex marshalling for arrays and
+ structures);</para>
+ </listitem>
+
+ <listitem>
+ <para>connect to the web service via HTTP and send that
+ message;</para>
+ </listitem>
+
+ <listitem>
+ <para>wait for the web service to send a response
+ message;</para>
+ </listitem>
+
+ <listitem>
+ <para>decode that response message and put the return value
+ of the remote procedure into the "result" variable.</para>
+ </listitem>
+ </orderedlist></para>
+ </sect4>
+
+ <sect4 id="wsdl">
+ <title>Service descriptions in WSDL</title>
+
+ <para>In the above explanations about SOAP, it was left open how
+ the programming language learns about how to translate function
+ calls in its own syntax into proper SOAP messages. In other words,
+ the programming language needs to know what operations the web
+ service supports and what types of arguments are required for the
+ operation's data in order to be able to properly serialize and
+ deserialize the data to and from the web service. For example, if
+ a web service operation expects a number in "double" floating
+ point format for a particular parameter, the programming language
+ cannot send to it a string instead.</para>
+
+ <para>For this, the Web Service Definition Language (WSDL) was
+ invented, another XML substandard that describes exactly what
+ operations the web service supports and, for each operation, which
+ parameters and types are needed with each request and response
+ message. WSDL descriptions can be incredibly verbose, and one of
+ the few good things that can be said about this standard is that
+ it is indeed supported by most programming languages.</para>
+
+ <para>So, if it is said that a programming language "supports" web
+ services, this typically means that a programming language has
+ support for parsing WSDL files and somehow integrating the remote
+ procedure calls into the native language syntax -- for example,
+ like in the Java sample shown in <xref
+ linkend="webservice-java-sample"/>.</para>
+
+ <para>For details about how programming languages support web
+ services, please refer to the documentation that comes with the
+ individual languages. Here are a few pointers:</para>
+
+ <orderedlist>
+ <listitem>
+ <para>For <emphasis role="bold">C++, </emphasis> among many
+ others, the gSOAP toolkit is a good option. Parts of gSOAP are
+ also used in VirtualBox to implement the VirtualBox web
+ service.</para>
+ </listitem>
+
+ <listitem>
+ <para>For <emphasis role="bold">Java, </emphasis> there are
+ several implementations already described in this document
+ (see <xref linkend="glue-jax-ws"/> and <xref
+ linkend="webservice-java-sample"/>).</para>
+ </listitem>
+
+ <listitem>
+ <para><emphasis role="bold">Perl</emphasis> supports WSDL via
+ the SOAP::Lite package. This in turn comes with a tool called
+ <computeroutput>stubmaker.pl</computeroutput> that allows you
+ to turn any WSDL file into a Perl package that you can import.
+ (You can also import any WSDL file "live" by having it parsed
+ every time the script runs, but that can take a while.) You
+ can then code (again, assuming the above example):
+ <screen>my $result = servicename-&gt;sayHello("Peter");</screen>
+ </para>
+
+ <para>A sample that uses SOAP::Lite was described in <xref
+ linkend="raw-webservice-perl"/>.</para>
+ </listitem>
+ </orderedlist>
+ </sect4>
+ </sect3>
+ </sect2>
+ </sect1>
+
+ <sect1 id="api_com">
+ <title>Using COM/XPCOM directly</title>
+
+ <para>If you do not require <emphasis>remote</emphasis> procedure calls
+ such as those offered by the VirtualBox web service, and if you know
+ Python or C++ as well as COM, you might find it preferable to program
+ VirtualBox's Main API directly via COM.</para>
+
+ <para>COM stands for "Component Object Model" and is a standard
+ originally introduced by Microsoft in the 1990s for Microsoft Windows.
+ It allows for organizing software in an object-oriented way and across
+ processes; code in one process may access objects that live in another
+ process.</para>
+
+ <para>COM has several advantages: it is language-neutral, meaning that
+ even though all of VirtualBox is internally written in C++, programs
+ written in other languages could communicate with it. COM also cleanly
+ separates interface from implementation, so that external programs need
+ not know anything about the messy and complicated details of VirtualBox
+ internals.</para>
+
+ <para>On a Windows host, all parts of VirtualBox will use the COM
+ functionality that is native to Windows. On other hosts (including
+ Linux), VirtualBox comes with a built-in implementation of XPCOM, as
+ originally created by the Mozilla project, which we have enhanced to
+ support interprocess communication on a level comparable to Microsoft
+ COM. Internally, VirtualBox has an abstraction layer that allows the
+ same VirtualBox code to work both with native COM as well as our XPCOM
+ implementation.</para>
+
+ <sect2 id="pycom">
+ <title>Python COM API</title>
+
+ <para>On Windows, Python scripts can use COM and VirtualBox interfaces
+ to control almost all aspects of virtual machine execution. As an
+ example, use the following commands to instantiate the VirtualBox
+ object and start a VM: <screen>
+ vbox = win32com.client.Dispatch("VirtualBox.VirtualBox")
+ session = win32com.client.Dispatch("VirtualBox.Session")
+ mach = vbox.findMachine("uuid or name of machine to start")
+ progress = mach.launchVMProcess(session, "gui", "")
+ progress.waitForCompletion(-1)
+ </screen> Also, see
+ <computeroutput>/bindings/glue/python/samples/vboxshell.py</computeroutput>
+ for more advanced usage scenarious. However, unless you have specific
+ requirements, we strongly recommend to use the generic glue layer
+ described in the next section to access MS COM objects.</para>
+ </sect2>
+
+ <sect2 id="glue-python">
+ <title>Common Python bindings layer</title>
+
+ <para>As different wrappers ultimately provide access to the same
+ underlying API, and to simplify porting and development of Python
+ application using the VirtualBox Main API, we developed a common glue
+ layer that abstracts out most platform-specific details from the
+ application and allows the developer to focus on application logic.
+ The VirtualBox installer automatically sets up this glue layer for the
+ system default Python installation.</para>
+
+ <para>See <xref linkend="glue-python-setup"/> for details on how to
+ set up the glue layer if you want to use a different Python installation,
+ or if the VirtualBox installer failed to detect and set it up accordingly.</para>
+
+ <para>The minimum supported Python version is 2.6.</para>
+
+ <para>In this layer, the class
+ <computeroutput>VirtualBoxManager</computeroutput> hides most
+ platform-specific details. It can be used to access both the local
+ (COM) and the web service based API. The following code can be used by
+ an application to use the glue layer.</para>
+
+ <screen># This code assumes vboxapi.py from VirtualBox distribution
+# being in PYTHONPATH, or installed system-wide
+from vboxapi import VirtualBoxManager
+
+# This code initializes VirtualBox manager with default style
+# and parameters
+virtualBoxManager = VirtualBoxManager(None, None)
+
+# Alternatively, one can be more verbose, and initialize
+# glue with web service backend, and provide authentication
+# information
+virtualBoxManager = VirtualBoxManager("WEBSERVICE",
+ {'url':'http://myhost.com::18083/',
+ 'user':'me',
+ 'password':'secret'}) </screen>
+
+ <para>We supply the <computeroutput>VirtualBoxManager</computeroutput>
+ constructor with 2 arguments: style and parameters. Style defines
+ which bindings style to use (could be "MSCOM", "XPCOM" or
+ "WEBSERVICE"), and if set to <computeroutput>None</computeroutput>
+ defaults to usable platform bindings (MS COM on Windows, XPCOM on
+ other platforms). The second argument defines parameters, passed to
+ the platform-specific module, as we do in the second example, where we
+ pass username and password to be used to authenticate against the web
+ service.</para>
+
+ <para>After obtaining the
+ <computeroutput>VirtualBoxManager</computeroutput> instance, one can
+ perform operations on the IVirtualBox class. For example, the
+ following code will a start virtual machine by name or ID:</para>
+
+ <screen>from vboxapi import VirtualBoxManager
+mgr = VirtualBoxManager(None, None)
+vbox = mgr.getVirtualBox()
+name = "Linux"
+mach = vbox.findMachine(name)
+session = mgr.getSessionObject(vbox)
+progress = mach.launchVMProcess(session, "gui", "")
+progress.waitForCompletion(-1)
+mgr.closeMachineSession(session)
+ </screen>
+ <para>
+ Following code will print all registered machines and their log
+ folders
+ </para>
+ <screen>from vboxapi import VirtualBoxManager
+mgr = VirtualBoxManager(None, None)
+vbox = mgr.getVirtualBox()
+
+for m in mgr.getArray(vbox, 'machines'):
+ print "Machine '%s' logs in '%s'" %(m.name, m.logFolder)
+ </screen>
+
+ <para>Code above demonstrates cross-platform access to array properties
+ (certain limitations prevent one from using
+ <computeroutput>vbox.machines</computeroutput> to access a list of
+ available virtual machines in case of XPCOM), and a mechanism of
+ uniform session creation and closing
+ (<computeroutput>mgr.getSessionObject()</computeroutput>).</para>
+
+ <sect3 id="glue-python-setup">
+ <title>Manual or subsequent setup</title>
+
+ <para>In case you want to use the glue layer with a different Python
+ installation or the installer failed to set it up, use these steps
+ in a shell to install the necessary files:</para>
+
+ <screen> # cd VBOX_INSTALL_PATH/sdk/installer
+ # PYTHON vboxapisetup.py install</screen>
+
+ <note> <para>On Windows hosts, a Python distribution along with the
+ win32api bindings package need to be installed as a prerequisite. </para></note>
+ </sect3>
+
+ </sect2>
+
+ <sect2 id="cppcom">
+ <title>C++ COM API</title>
+
+ <para>C++ is the language that VirtualBox itself is written in, so C++
+ is the most direct way to use the Main API -- but it is not
+ necessarily the easiest, as using COM and XPCOM has its own set of
+ complications.</para>
+
+ <para>VirtualBox ships with sample programs that demonstrate how to
+ use the Main API to implement a number of tasks on your host platform.
+ These samples can be found in the
+ <computeroutput>/bindings/xpcom/samples</computeroutput> directory for
+ Linux, Mac OS X and Solaris and
+ <computeroutput>/bindings/mscom/samples</computeroutput> for Windows.
+ The two samples are actually different, because the one for Windows
+ uses native COM, whereas the other uses our XPCOM implementation, as
+ described above.</para>
+
+ <para>Since COM and XPCOM are conceptually very similar but vary in
+ the implementation details, we have created a "glue" layer that
+ shields COM client code from these differences. All VirtualBox uses is
+ this glue layer, so the same code written once works on both Windows
+ hosts (with native COM) as well as on other hosts (with our XPCOM
+ implementation). It is recommended to always use this glue code
+ instead of using the COM and XPCOM APIs directly, as it is very easy
+ to make your code completely independent from the platform it is
+ running on.<!-- A third sample,
+ <computeroutput>tstVBoxAPIGlue.cpp</computeroutput>, illustrates how to
+ use the glue layer.
+--></para>
+
+ <para>In order to encapsulate platform differences between Microsoft
+ COM and XPCOM, the following items should be kept in mind when using
+ the glue layer:</para>
+
+ <para><orderedlist>
+ <listitem>
+ <para><emphasis role="bold">Attribute getters and
+ setters.</emphasis> COM has the notion of "attributes" in
+ interfaces, which roughly compare to C++ member variables in
+ classes. The difference is that for each attribute declared in
+ an interface, COM automatically provides a "get" method to
+ return the attribute's value. Unless the attribute has been
+ marked as "readonly", a "set" attribute is also provided.</para>
+
+ <para>To illustrate, the IVirtualBox interface has a "version"
+ attribute, which is read-only and of the "wstring" type (the
+ standard string type in COM). As a result, you can call the
+ "get" method for this attribute to retrieve the version number
+ of VirtualBox.</para>
+
+ <para>Unfortunately, the implementation differs between COM and
+ XPCOM. Microsoft COM names the "get" method like this:
+ <computeroutput>get_Attribute()</computeroutput>, whereas XPCOM
+ uses this syntax:
+ <computeroutput>GetAttribute()</computeroutput> (and accordingly
+ for "set" methods). To hide these differences, the VirtualBox
+ glue code provides the
+ <computeroutput>COMGETTER(attrib)</computeroutput> and
+ <computeroutput>COMSETTER(attrib)</computeroutput> macros. So,
+ <computeroutput>COMGETTER(version)()</computeroutput> (note, two
+ pairs of brackets) expands to
+ <computeroutput>get_Version()</computeroutput> on Windows and
+ <computeroutput>GetVersion()</computeroutput> on other
+ platforms.</para>
+ </listitem>
+
+ <listitem>
+ <para><emphasis role="bold">Unicode conversions.</emphasis>
+ While the rest of the modern world has pretty much settled on
+ encoding strings in UTF-8, COM, unfortunately, uses UCS-16
+ encoding. This requires a lot of conversions, in particular
+ between the VirtualBox Main API and the Qt GUI, which, like the
+ rest of Qt, likes to use UTF-8.</para>
+
+ <para>To facilitate these conversions, VirtualBox provides the
+ <computeroutput>com::Bstr</computeroutput> and
+ <computeroutput>com::Utf8Str</computeroutput> classes, which
+ support all kinds of conversions back and forth.</para>
+ </listitem>
+
+ <listitem>
+ <para><emphasis role="bold">COM autopointers.</emphasis>
+ Possibly the greatest pain of using COM -- reference counting --
+ is alleviated by the
+ <computeroutput>ComPtr&lt;&gt;</computeroutput> template
+ provided by the <computeroutput>ptr.h</computeroutput> file in
+ the glue layer.</para>
+ </listitem>
+ </orderedlist></para>
+ </sect2>
+
+ <sect2 id="event-queue">
+ <title>Event queue processing</title>
+
+ <para>Both VirtualBox client programs and frontends should
+ periodically perform processing of the main event queue, and do that
+ on the application's main thread. In case of a typical GUI Windows/Mac
+ OS application this happens automatically in the GUI's dispatch loop.
+ However, for CLI only application, the appropriate actions have to be
+ taken. For C++ applications, the VirtualBox SDK provided glue method
+ <screen>
+ int EventQueue::processEventQueue(uint32_t cMsTimeout)
+ </screen> can be used for both blocking and non-blocking operations.
+ For the Python bindings, a common layer provides the method <screen>
+ VirtualBoxManager.waitForEvents(ms)
+ </screen> with similar semantics.</para>
+
+ <para>Things get somewhat more complicated for situations where an
+ application using VirtualBox cannot directly control the main event
+ loop and the main event queue is separated from the event queue of the
+ programming librarly (for example in case of Qt on Unix platforms). In
+ such a case, the application developer is advised to use a
+ platform/toolkit specific event injection mechanism to force event
+ queue checks either based on periodical timer events delivered to the
+ main thread, or by using custom platform messages to notify the main
+ thread when events are available. See the VBoxSDL and Qt (VirtualBox)
+ frontends as examples.</para>
+ </sect2>
+
+ <sect2 id="vbcom">
+ <title>Visual Basic and Visual Basic Script (VBS) on Windows
+ hosts</title>
+
+ <para>On Windows hosts, one can control some of the VirtualBox Main
+ API functionality from VBS scripts, and pretty much everything from
+ Visual Basic programs.<footnote>
+ <para>The difference results from the way VBS treats COM
+ safearrays, which are used to keep lists in the Main API. VBS
+ expects every array element to be a
+ <computeroutput>VARIANT</computeroutput>, which is too strict a
+ limitation for any high performance API. We may lift this
+ restriction for interface APIs in a future version, or
+ alternatively provide conversion APIs.</para>
+ </footnote></para>
+
+ <para>VBS is scripting language available in any recent Windows
+ environment. As an example, the following VBS code will print
+ VirtualBox version: <screen>
+ set vb = CreateObject("VirtualBox.VirtualBox")
+ Wscript.Echo "VirtualBox version " &amp; vb.version
+ </screen> See
+ <computeroutput>bindings/mscom/vbs/sample/vboxinfo.vbs</computeroutput>
+ for the complete sample.</para>
+
+ <para>Visual Basic is a popular high level language capable of
+ accessing COM objects. The following VB code will iterate over all
+ available virtual machines:<screen>
+ Dim vb As VirtualBox.IVirtualBox
+
+ vb = CreateObject("VirtualBox.VirtualBox")
+ machines = ""
+ For Each m In vb.Machines
+ m = m &amp; " " &amp; m.Name
+ Next
+ </screen> See
+ <computeroutput>bindings/mscom/vb/sample/vboxinfo.vb</computeroutput>
+ for the complete sample.</para>
+ </sect2>
+
+ <sect2 id="cbinding">
+ <title>C binding to VirtualBox API</title>
+
+ <para>The VirtualBox API originally is designed as object oriented,
+ using XPCOM or COM as the middleware, which translates natively to C++.
+ This means that in order to use it from C there needs to be some
+ helper code to bridge the language differences and reduce the
+ differences between platforms.</para>
+
+ <sect3 id="capi_glue">
+ <title>Cross-platform C binding to VirtualBox API</title>
+
+ <para>Starting with version 4.3, VirtualBox offers a C binding
+ which allows using the same C client sources for all platforms,
+ covering Windows, Linux, Mac OS X and Solaris. It is the
+ preferred way to write API clients, even though the old style
+ is still available.</para>
+
+ </sect3>
+
+ <sect3 id="c-gettingstarted">
+ <title>Getting started</title>
+
+ <para>The following sections describe how to use the VirtualBox API
+ in a C program. The necessary files are included in the SDK, in the
+ directories <computeroutput>sdk/bindings/c/include</computeroutput>
+ and <computeroutput>sdk/bindings/c/glue</computeroutput>.</para>
+
+ <para>As part of the SDK, a sample program
+ <computeroutput>tstCAPIGlue.c</computeroutput> is provided in the
+ directory <computeroutput>sdk/bindings/c/samples</computeroutput>
+ which demonstrates
+ using the C binding to initialize the API, get handles for
+ VirtualBox and Session objects, make calls to list and start virtual
+ machines, monitor events, and uninitialize resources when done. The
+ sample program is trying to illustrate all relevant concepts, so it
+ is a great source of detail information. Among many other generally
+ useful code sequences it contains a function which shows how to
+ retrieve error details in C code if they are available from the API
+ call.</para>
+
+ <para>The sample program <computeroutput>tstCAPIGlue</computeroutput>
+ can be built using the provided
+ <computeroutput>Makefile</computeroutput> and can be run without
+ arguments.</para>
+
+ <para>It uses the VBoxCAPIGlue library (source code is in directory
+ <computeroutput>sdk/bindings/c/glue</computeroutput>, to be used in
+ your API client code) to open the C binding layer during runtime,
+ which is preferred to other means as it isolates the code which
+ locates the necessary dynamic library, using a known working way
+ which works on all platforms. If you encounter problems with this
+ glue code in <computeroutput>VBoxCAPIGlue.c</computeroutput>, let the
+ VirtualBox developers know, rather than inventing incompatible
+ solutions.</para>
+
+ <para>The following sections document the important concepts needed
+ to correctly use the C binding, as it is vital for developing API
+ client code which manages memory correctly, updates the reference
+ counters correctly, avoiding crashes and memory leaks. Often API
+ clients need to handle events, so the C API specifics are also
+ described below.</para>
+ </sect3>
+
+ <sect3 id="c-initialization">
+ <title>VirtualBox C API initialization</title>
+
+ <para>Just like in C++, the API and the underlying middleware needs
+ to be initialized before it can be used. The
+ <computeroutput>VBoxCAPI_v4_3.h</computeroutput> header provides the
+ interface to the C binding, but you can alternatively and more
+ conveniently also include
+ <computeroutput>VBoxCAPIGlue.h</computeroutput>,
+ as this avoids the VirtualBox version dependent header file name and
+ makes sure the global variable <code>g_pVBoxFuncs</code> contains a
+ pointer to the structure which contains the helper function pointers.
+ Here's how to initialize the C API:<screen>#include "VBoxCAPIGlue.h"
+...
+IVirtualBoxClient *vboxclient = NULL;
+IVirtualBox *vbox = NULL;
+ISession *session = NULL;
+HRESULT rc;
+ULONG revision;
+
+/*
+ * VBoxCGlueInit() loads the necessary dynamic library, handles errors
+ * (producing an error message hinting what went wrong) and gives you
+ * the pointer to the function table (g_pVBoxFuncs).
+ *
+ * Once you get the function table, then how and which functions
+ * to use is explained below.
+ *
+ * g_pVBoxFuncs-&gt;pfnClientInitialize does all the necessary startup
+ * action and provides us with pointers to an IVirtualBoxClient instance.
+ * It should be matched by a call to g_pVBoxFuncs-&gt;pfnClientUninitialize()
+ * when done.
+ */
+
+if (VBoxCGlueInit())
+{
+ fprintf(stderr, "s: FATAL: VBoxCGlueInit failed: %s\n",
+ argv[0], g_szVBoxErrMsg);
+ return EXIT_FAILURE;
+}
+
+g_pVBoxFuncs-&gt;pfnClientInitialize(NULL, &amp;vboxclient);
+if (!vboxclient)
+{
+ fprintf(stderr, "%s: FATAL: could not get VirtualBoxClient reference\n",
+ argv[0]);
+ return EXIT_FAILURE;
+}</screen></para>
+
+ <para>If <computeroutput>vboxclient</computeroutput> is still
+ <computeroutput>NULL</computeroutput> this means the initializationi
+ failed and the VirtualBox C API cannot be used.</para>
+
+ <para>It is possible to write C applications using multiple threads
+ which all use the VirtualBox API, as long as you're initializing
+ the C API in each thread which your application creates. This is done
+ with <code>g_pVBoxFuncs->pfnClientThreadInitialize()</code> and
+ likewise before the thread is terminated the API must be
+ uninitialized with
+ <code>g_pVBoxFuncs->pfnClientThreadUninitialize()</code>. You don't
+ have to use these functions in worker threads created by COM/XPCOM
+ (which you might observe if your code uses active event handling),
+ everything is initialized correctly already. On Windows the C
+ bindings create a marshaller which supports a wide range of COM
+ threading models, from STA to MTA, so you don't have to worry about
+ these details unless you plan to use active event handlers. See
+ the sample code how to get this to work reliably (in other words
+ think twice if passive event handling isn't the better solution after
+ you looked at the sample code).</para>
+ </sect3>
+
+ <sect3 id="c-invocation">
+ <title>C API attribute and method invocation</title>
+
+ <para>Method invocation is straightforward. It looks pretty much
+ like the C++ way, by using a macro which internally accesses the
+ vtable, and additionally needs to be passed a pointer to the objecti
+ as the first argument to serve as the
+ <computeroutput>this</computeroutput> pointer.</para>
+
+ <para>Using the C binding, all method invocations return a numeric
+ result code of type <code>HRESULT</code> (with a few exceptions
+ which normally are not relevant).</para>
+
+ <para>If an interface is specified as returning an object, a pointer
+ to a pointer to the appropriate object must be passed as the last
+ argument. The method will then store an object pointer in that
+ location.</para>
+
+ <para>Likewise, attributes (properties) can be queried or set using
+ method invocations, using specially named methods. For each
+ attribute there exists a getter method, the name of which is composed
+ of <computeroutput>get_</computeroutput> followed by the capitalized
+ attribute name. Unless the attribute is read-only, an analogous
+ <computeroutput>set_</computeroutput> method exists. Let's apply
+ these rules to get the <computeroutput>IVirtualBox</computeroutput>
+ reference, an <computeroutput>ISession</computeroutput> instance
+ reference and read the
+ <link linkend="IVirtualBox__revision">IVirtualBox::revision</link>
+ attribute:
+ <screen>rc = IVirtualBoxClient_get_VirtualBox(vboxclient, &amp;vbox);
+if (FAILED(rc) || !vbox)
+{
+ PrintErrorInfo(argv[0], "FATAL: could not get VirtualBox reference", rc);
+ return EXIT_FAILURE;
+}
+rc = IVirtualBoxClient_get_Session(vboxclient, &amp;session);
+if (FAILED(rc) || !session)
+{
+ PrintErrorInfo(argv[0], "FATAL: could not get Session reference", rc);
+ return EXIT_FAILURE;
+}
+
+rc = IVirtualBox_get_Revision(vbox, &amp;revision);
+if (SUCCEEDED(rc))
+{
+ printf("Revision: %u\n", revision);
+}</screen></para>
+
+ <para>The convenience macros for calling a method are named by
+ prepending the method name with the interface name (using
+ <code>_</code>as the separator).</para>
+
+ <para>So far only attribute getters were illustrated, but generic
+ method calls are straightforward, too:
+ <screen>IMachine *machine = NULL;
+BSTR vmname = ...;
+...
+/*
+ * Calling IMachine::findMachine(...)
+ */
+rc = IVirtualBox_FindMachine(vbox, vmname, &amp;machine);</screen></para>
+
+ <para>As a more complicated example of a method invocation, let's
+ call
+ <link linkend="IMachine__launchVMProcess">IMachine::launchVMProcess</link>
+ which returns an IProgress object. Note again that the method name is
+ capitalized:
+ <screen>IProgress *progress;
+...
+rc = IMachine_LaunchVMProcess(
+ machine, /* this */
+ session, /* arg 1 */
+ sessionType, /* arg 2 */
+ env, /* arg 3 */
+ &amp;progress /* Out */
+);</screen></para>
+
+ <para>All objects with their methods and attributes are documented
+ in <xref linkend="sdkref_classes"/>.</para>
+ </sect3>
+
+ <sect3 id="c-string-handling">
+ <title>String handling</title>
+
+ <para>When dealing with strings you have to be aware of a string's
+ encoding and ownership.</para>
+
+ <para>Internally, the API uses UTF-16 encoded strings. A set of
+ conversion functions is provided to convert other encodings to and
+ from UTF-16. The type of a UTF-16 character is
+ <computeroutput>BSTR</computeroutput> (or its constant counterpart
+ <computeroutput>CBSTR</computeroutput>), which is an array type,
+ represented by a pointer to the start of the zero-terminated string.
+ There are functions for converting between UTF-8 and UTF-16 strings
+ available through <code>g_pVBoxFuncs</code>:
+ <screen>int (*pfnUtf16ToUtf8)(CBSTR pwszString, char **ppszString);
+int (*pfnUtf8ToUtf16)(const char *pszString, BSTR *ppwszString);</screen></para>
+
+ <para>The ownership of a string determines who is responsible for
+ releasing resources associated with the string. Whenever the API
+ creates a string (essentially for output parameters), ownership is
+ transferred to the caller. To avoid resource leaks, the caller
+ should release resources once the string is no longer needed.
+ There are plenty of examples in the sample code.</para>
+ </sect3>
+
+ <sect3 id="c-safearray">
+ <title>Array handling</title>
+
+ <para>Arrays are handled somewhat similarly to strings, with the
+ additional information of the number of elements in the array. The
+ exact details of string passing depends on the platform middleware
+ (COM/XPCOM), and therefore the C binding offers helper functions to
+ gloss over these differences.</para>
+
+ <para>Passing arrays as input parameters to API methods is usually
+ done by the following sequence, calling a hypothetical
+ <code>IArrayDemo_PassArray</code> API method:
+ <screen>static const ULONG aElements[] = { 1, 2, 3, 4 };
+ULONG cElements = sizeof(aElements) / sizeof(aElements[0]);
+SAFEARRAY *psa = NULL;
+psa = g_pVBoxFuncs->pfnSafeArrayCreateVector(VT_I4, 0, cElements);
+g_pVBoxFuncs->pfnSafeArrayCopyInParamHelper(psa, aElements, sizeof(aElements));
+IArrayDemo_PassArray(pThis, ComSafeArrayAsInParam(psa));
+g_pVBoxFuncs->pfnSafeArrayDestroy(psa);</screen></para>
+
+ <para>Likewise, getting arrays results from output parameters is done
+ using helper functions which manage memory allocations as part of
+ their other functionality:
+ <screen>SAFEARRAY *psa = g_pVBoxFuncs->pfnSafeArrayOutParamAlloc();
+ULONG *pData;
+ULONG cElements;
+IArrayDemo_ReturnArray(pThis, ComSafeArrayAsOutTypeParam(psa, ULONG));
+g_pVBoxFuncs->pfnSafeArrayCopyOutParamHelper((void **)&amp;pData, &amp;cElements, VT_I4, psa);
+g_pVBoxFuncs->pfnSafeArrayDestroy(psa);</screen></para>
+
+ <para>This covers the necessary functionality for all array element
+ types except interface references. These need special helpers to
+ manage the reference counting correctly. The following code snippet
+ gets the list of VMs, and passes the first IMachine reference to
+ another API function (assuming that there is at least one element
+ in the array, to simplify the example):
+ <screen>SAFEARRAY psa = g_pVBoxFuncs->pfnSafeArrayOutParamAlloc();
+IMachine **machines = NULL;
+ULONG machineCnt = 0;
+ULONG i;
+IVirtualBox_get_Machines(virtualBox, ComSafeArrayAsOutIfaceParam(machinesSA, IMachine *));
+g_pVBoxFuncs->pfnSafeArrayCopyOutIfaceParamHelper((IUnknown ***)&amp;machines, &amp;machineCnt, machinesSA);
+g_pVBoxFuncs->pfnSafeArrayDestroy(machinesSA);
+/* Now "machines" contains the IMachine references, and machineCnt the
+ * number of elements in the array. */
+...
+SAFEARRAY *psa = g_pVBoxFuncs->pfnSafeArrayCreateVector(VT_IUNKNOWN, 0, 1);
+g_pVBoxFuncs->pfnSafeArrayCopyInParamHelper(psa, (void *)&amp;machines[0], sizeof(machines[0]));
+IVirtualBox_GetMachineStates(ComSafeArrayAsInParam(psa), ...);
+...
+g_pVBoxFuncs->pfnSafeArrayDestroy(psa);
+for (i = 0; i &lt; machineCnt; ++i)
+{
+ IMachine *machine = machines[i];
+ IMachine_Release(machine);
+}
+free(machines);</screen></para>
+
+ <para>Handling output parameters needs more special effort than
+ input parameters, thus only for the former there are special helpers,
+ and the latter is handled through the generic array support.</para>
+ </sect3>
+
+ <sect3 id="c-eventhandling">
+ <title>Event handling</title>
+
+ <para>The VirtualBox API offers two types of event handling, active
+ and passive, and consequently there is support for both with the
+ C API binding. Active event handling (based on asynchronous
+ callback invocation for event delivery) is more difficult, as it
+ requires the construction of valid C++ objects in C, which is
+ inherently platform and compiler dependent. Passive event handling
+ is much simpler, it relies on an event loop, fetching events and
+ triggering the necessary handlers explicitly in the API client code.
+ Both approaches depend on an event loop to make sure that events
+ get delivered in a timely manner, with differences what exactly needs
+ to be done.</para>
+
+ <para>The C API sample contains code for both event handling styles,
+ and one has to modify the appropriate <code>#define</code> to select
+ which style is actually used by the compiled program. It allows a
+ good comparison between the two variants, and the code sequences are
+ probably worth reusing without much change in other API clients
+ with only minor adaptions.</para>
+
+ <para>Active event handling needs to ensure that the following helper
+ function is called frequently enough in the primary thread:
+ <screen>g_pVBoxFuncs->pfnProcessEventQueue(cTimeoutMS);</screen></para>
+
+ <para>The actual event handler implementation is quite tedious, as
+ it has to implement a complete API interface. Especially on Windows
+ it is a lot of work to implement the complicated
+ <code>IDispatch</code> interface, requiring to load COM type
+ information and using it in the <code>IDispatch</code> method
+ implementation. Overall this is quite tedious compared to passive
+ event handling.</para>
+
+ <para>Passive event handling uses a similar event loop structure,
+ which requires calling the following function in a loop, and
+ processing the returned event appropriately:
+ <screen>rc = IEventSource_GetEvent(pEventSource, pListener, cTimeoutMS, &amp;pEvent);</screen></para>
+
+ <para>After processing the event it needs to be marked as processed
+ with the following method call:
+ <screen>rc = IEventSource_EventProcessed(pEventSource, pListener, pEvent);</screen></para>
+
+ <para>This is vital for vetoable events, as they would be stuck
+ otherwise, waiting whether the veto comes or not. It does not do any
+ harm for other event types, and in the end is cheaper than checking
+ if the event at hand is vetoable or not.</para>
+
+ <para>The general event handling concepts are described in the API
+ specification (see <xref linkend="events"/>), including how to
+ aggregate multiple event sources for processing in one event loop.
+ As mentioned, the sample illustrates the practical aspects of how to
+ use both types of event handling, active and passive, from a C
+ application. Additional hints are in the comments documenting
+ the helper methods in
+ <computeroutput>VBoxCAPI_v4_3.h</computeroutput>. The code complexity
+ of active event handling (and its inherenly platform/compiler
+ specific aspects) should be motivation to use passive event handling
+ whereever possible.</para>
+ </sect3>
+
+ <sect3 id="c-uninitialization">
+ <title>C API uninitialization</title>
+
+ <para>Uninitialization is performed by
+ <computeroutput>g_pVBoxFuncs-&gt;pfnClientUninitialize().</computeroutput>
+ If your program can exit from more than one place, it is a good idea
+ to install this function as an exit handler with Standard C's
+ <computeroutput>atexit()</computeroutput> just after calling
+ <computeroutput>g_pVBoxFuncs-&gt;pfnClientInitialize()</computeroutput>
+ , e.g. <screen>#include &lt;stdlib.h&gt;
+#include &lt;stdio.h&gt;
+
+...
+
+/*
+ * Make sure g_pVBoxFuncs-&gt;pfnClientUninitialize() is called at exit, no
+ * matter if we return from the initial call to main or call exit()
+ * somewhere else. Note that atexit registered functions are not
+ * called upon abnormal termination, i.e. when calling abort() or
+ * signal().
+ */
+
+if (atexit(g_pVBoxFuncs-&gt;pfnClientUninitialize()) != 0) {
+ fprintf(stderr, "failed to register g_pVBoxFuncs-&gt;pfnClientUninitialize()\n");
+ exit(EXIT_FAILURE);
+}</screen></para>
+
+ <para>Another idea would be to write your own <computeroutput>void
+ myexit(int status)</computeroutput> function, calling
+ <computeroutput>g_pVBoxFuncs-&gt;pfnClientUninitialize()</computeroutput>
+ followed by the real <computeroutput>exit()</computeroutput>, and
+ use it instead of <computeroutput>exit()</computeroutput> throughout
+ your program and at the end of
+ <computeroutput>main.</computeroutput></para>
+
+ <para>If you expect the program to be terminated by a signal (e.g.
+ user types CTRL-C sending SIGINT) you might want to install a signal
+ handler setting a flag noting that a signal was sent and then
+ calling
+ <computeroutput>g_pVBoxFuncs-&gt;pfnClientUninitialize()</computeroutput>
+ later on, <emphasis>not</emphasis> from the handler itself.</para>
+
+ <para>That said, if a client program forgets to call
+ <computeroutput>g_pVBoxFuncs-&gt;pfnClientUninitialize()</computeroutput>
+ before it terminates, there is a mechanism in place which will
+ eventually release references held by the client. On Windows it can
+ take quite a while, in the order of 6-7 minutes.</para>
+ </sect3>
+
+ <sect3 id="c-linking">
+ <title>Compiling and linking</title>
+
+ <para>A program using the C binding has to open the library during
+ runtime using the help of glue code provided and as shown in the
+ example <computeroutput>tstCAPIGlue.c</computeroutput>.
+ Compilation and linking can be achieved with a makefile fragment
+ similar to:<screen># Where is the SDK directory?
+PATH_SDK = ../../..
+CAPI_INC = -I$(PATH_SDK)/bindings/c/include
+ifdef ProgramFiles
+PLATFORM_INC = -I$(PATH_SDK)/bindings/mscom/include
+PLATFORM_LIB = $(PATH_SDK)/bindings/mscom/lib
+else
+PLATFORM_INC = -I$(PATH_SDK)/bindings/xpcom/include
+PLATFORM_LIB = $(PATH_SDK)/bindings/xpcom/lib
+endif
+GLUE_DIR = $(PATH_SDK)/bindings/c/glue
+GLUE_INC = -I$(GLUE_DIR)
+
+# Compile Glue Library
+VBoxCAPIGlue.o: $(GLUE_DIR)/VBoxCAPIGlue.c
+ $(CC) $(CFLAGS) $(CAPI_INC) $(PLATFORM_INC) $(GLUE_INC) -o $@ -c $&lt;
+
+# Compile interface ID list
+VirtualBox_i.o: $(PLATFORM_LIB)/VirtualBox_i.c
+ $(CC) $(CFLAGS) $(CAPI_INC) $(PLATFORM_INC) $(GLUE_INC) -o $@ -c $&lt;
+
+# Compile program code
+program.o: program.c
+ $(CC) $(CFLAGS) $(CAPI_INC) $(PLATFORM_INC) $(GLUE_INC) -o $@ -c $&lt;
+
+# Link program.
+program: program.o VBoxCAPICGlue.o VirtualBox_i.o
+ $(CC) -o $@ $^ -ldl -lpthread</screen></para>
+ </sect3>
+
+ <sect3 id="capi_conversion">
+ <title>Conversion of code using legacy C binding</title>
+
+ <para>This section aims to make the task of converting code using
+ the legacy C binding to the new style a breeze, by pointing out some
+ key steps.</para>
+
+ <para>One necessary change is adjusting your Makefile to reflect the
+ different include paths. See above. There are now 3 relevant include
+ directories, and most of it is pointing to the C binding directory.
+ The XPCOM include directory is still relevant for platforms where
+ the XPCOM middleware is used, but most of the include files live
+ elsewhere now, so it's good to have it last. Additionally the
+ <computeroutput>VirtualBox_i.c</computeroutput> file needs to be
+ compiled and linked to the program, it contains the IIDs relevant
+ for the VirtualBox API, making sure they are not replicated endlessly
+ if the code refers to them frequently.</para>
+
+ <para>The C API client code should include
+ <computeroutput>VBoxCAPIGlue.h</computeroutput> instead of
+ <computeroutput>VBoxXPCOMCGlue.h</computeroutput> or
+ <computeroutput>VBoxCAPI_v4_3.h</computeroutput>, as this makes sure
+ the correct macros and internal translations are selected.</para>
+
+ <para>All API method calls (anything mentioning <code>vtbl</code>)
+ should be rewritten using the convenience macros for calling methods,
+ as these hide the internal details, are generally easier to use and
+ shorter to type. You should remove as many as possible
+ <code>(nsISupports **)</code> or similar typecasts, as the new style
+ should use the correct type in most places, increasing the type
+ safety in case of an error in the source code.</para>
+
+ <para>To gloss over the platform differences, API client code should
+ no longer rely on XPCOM specific interface names such as
+ <code>nsISupports</code>, <code>nsIException</code> and
+ <code>nsIEventQueue</code>, and replace them by the platform
+ independent interface names <code>IUnknown</code> and
+ <code>IErrorInfo</code> for the first two respectively. Event queue
+ handling should be replaced by using the platform independent way
+ described in <xref linkend="c-eventhandling"/>.</para>
+
+ <para>Finally adjust the string and array handling to use the new
+ helpers, as these make sure the code works without changes with
+ both COM and XPCOM, which are significantly different in this area.
+ The code should be double checked if it uses the correct way to
+ manage memory, and is freeing it only after the last use.</para>
+ </sect3>
+
+ <sect3 id="xpcom_cbinding">
+ <title>Legacy C binding to VirtualBox API for XPCOM</title>
+
+ <note>
+ <para>This section applies to Linux, Mac OS X and Solaris
+ hosts only and describes deprecated use of the API from C.</para>
+ </note>
+
+ <para>Starting with version 2.2, VirtualBox offers a C binding for
+ its API which works only on platforms using XPCOM. Refer to the
+ old SDK documentation (included in the SDK packages for version 4.3.6
+ or earlier), it still applies unchanged. The fundamental concepts are
+ similar (but the syntactical details are quite different) to the
+ newer cross-platform C binding which should be used for all new code,
+ as the support for the old C binding will go away in a major release
+ after version 4.3.</para>
+ </sect3>
+ </sect2>
+ </sect1>
+ </chapter>
+
+ <chapter id="concepts">
+ <title>Basic VirtualBox concepts; some examples</title>
+
+ <para>The following explains some basic VirtualBox concepts such as the
+ VirtualBox object, sessions and how virtual machines are manipulated and
+ launched using the Main API. The coding examples use a pseudo-code style
+ closely related to the object-oriented web service (OOWS) for JAX-WS.
+ Depending on which environment you are using, you will need to adjust the
+ examples.</para>
+
+ <sect1>
+ <title>Obtaining basic machine information. Reading attributes</title>
+
+ <para>Any program using the Main API will first need access to the
+ global VirtualBox object (see
+ <link linkend="IVirtualBox">IVirtualBox</link>), from which all other
+ functionality of the API is derived. With the OOWS for JAX-WS, this is
+ returned from the
+ <link linkend="IWebsessionManager__logon">IWebsessionManager::logon()</link>
+ call.</para>
+
+ <para>To enumerate virtual machines, one would look at the "machines"
+ array attribute in the VirtualBox object (see
+ <link linkend="IVirtualBox__machines">IVirtualBox::machines</link>).
+ This array contains all virtual machines currently registered with the
+ host, each of them being an instance of
+ <link linkend="IMachine">IMachine</link>.
+ From each such instance, one can query additional information, such as
+ the UUID, the name, memory, operating system and more by looking at the
+ attributes; see the attributes list in
+ <link linkend="IMachine">IMachine</link> documentation.</para>
+
+ <para>As mentioned in the preceding chapters, depending on your
+ programming environment, attributes are mapped to corresponding "get"
+ and (if the attribute is not read-only) "set" methods. So when the
+ documentation says that IMachine has a
+ "<link linkend="IMachine__name">name</link>" attribute, this means you
+ need to code something
+ like the following to get the machine's name:
+ <screen>IMachine machine = ...;
+String name = machine.getName();</screen>
+ Boolean attribute getters can sometimes be called
+ <computeroutput>isAttribute()</computeroutput> due to JAX-WS naming
+ conventions.</para>
+ </sect1>
+
+ <sect1>
+ <title>Changing machine settings: Sessions</title>
+
+ <para>As said in the previous section, to read a machine's attribute,
+ one invokes the corresponding "get" method. One would think that to
+ change settings of a machine, it would suffice to call the corresponding
+ "set" method -- for example, to set a VM's memory to 1024 MB, one would
+ call <computeroutput>setMemorySize(1024)</computeroutput>. Try that, and
+ you will get an error: "The machine is not mutable."</para>
+
+ <para>So unfortunately, things are not that easy. VirtualBox is a
+ complicated environment in which multiple processes compete for possibly
+ the same resources, especially machine settings. As a result, machines
+ must be "locked" before they can either be modified or started. This is
+ to prevent multiple processes from making conflicting changes to a
+ machine: it should, for example, not be allowed to change the memory
+ size of a virtual machine while it is running. (You can't add more
+ memory to a real computer while it is running either, at least not to an
+ ordinary PC.) Also, two processes must not change settings at the same
+ time, or start a machine at the same time.</para>
+
+ <para>These requirements are implemented in the Main API by way of
+ "sessions", in particular, the <link linkend="ISession">ISession</link>
+ interface. Each process which talks to
+ VirtualBox needs its own instance of ISession. In the web service, you
+ can request the creation of such an object by calling
+ <link linkend="IWebsessionManager__getSessionObject">IWebsessionManager::getSessionObject()</link>.
+ More complex management tasks might need multiple instances of ISession,
+ and each call returns a new one.</para>
+
+ <para>This session object must then be used like a mutex semaphore in
+ common programming environments. Before you can change machine settings,
+ you must write-lock the machine by calling
+ <link linkend="IMachine__lockMachine">IMachine::lockMachine()</link>
+ with your process's session object.</para>
+
+ <para>After the machine has been locked, the
+ <link linkend="ISession__machine">ISession::machine</link> attribute
+ contains a copy of the original IMachine object upon which the session
+ was opened, but this copy is "mutable": you can invoke "set" methods on
+ it.</para>
+
+ <para>When done making the changes to the machine, you must call
+ <link linkend="IMachine__saveSettings">IMachine::saveSettings()</link>,
+ which will copy the changes you have made from your "mutable" machine
+ back to the real machine and write them out to the machine settings XML
+ file. This will make your changes permanent.</para>
+
+ <para>Finally, it is important to always unlock the machine again, by
+ calling
+ <link linkend="ISession__unlockMachine">ISession::unlockMachine()</link>.
+ Otherwise, when the calling process end, the machine will receive the
+ "aborted" state, which can lead to loss of data.</para>
+
+ <para>So, as an example, the sequence to change a machine's memory to
+ 1024 MB is something like this:<screen>IWebsessionManager mgr ...;
+IVirtualBox vbox = mgr.logon(user, pass);
+...
+IMachine machine = ...; // read-only machine
+ISession session = mgr.getSessionObject();
+machine.lockMachine(session, LockType.Write); // machine is now locked for writing
+IMachine mutable = session.getMachine(); // obtain the mutable machine copy
+mutable.setMemorySize(1024);
+mutable.saveSettings(); // write settings to XML
+session.unlockMachine();</screen></para>
+ </sect1>
+
+ <sect1>
+ <title>Launching virtual machines</title>
+
+ <para>To launch a virtual machine, you call
+ <link linkend="IMachine__launchVMProcess">IMachine::launchVMProcess()</link>.
+ In doing so, the caller instructs the VirtualBox engine to start a new
+ process with the virtual machine in it, since to the host, each virtual
+ machine looks like single process, even if it has hundreds of its own
+ processes inside. (This new VM process in turn obtains a write lock on
+ the machine, as described above, to prevent conflicting changes from
+ other processes; this is why opening another session will fail while the
+ VM is running.)</para>
+
+ <para>Starting a machine looks something like this:
+ <screen>IWebsessionManager mgr ...;
+IVirtualBox vbox = mgr.logon(user, pass);
+...
+IMachine machine = ...; // read-only machine
+ISession session = mgr.getSessionObject();
+IProgress prog = machine.launchVMProcess(session,
+ "gui", // session type
+ ""); // possibly environment setting
+prog.waitForCompletion(10000); // give the process 10 secs
+if (prog.getResultCode() != 0) // check success
+ System.out.println("Cannot launch VM!")</screen></para>
+
+ <para>The caller's session object can then be used as a sort of remote
+ control to the VM process that was launched. It contains a "console"
+ object (see <link linkend="ISession__console">ISession::console</link>)
+ with which the VM can be paused,
+ stopped, snapshotted or other things.</para>
+ </sect1>
+
+ <sect1 id="events">
+ <title>VirtualBox events</title>
+
+ <para>In VirtualBox, "events" provide a uniform mechanism to register
+ for and consume specific events. A VirtualBox client can register an
+ "event listener" (represented by the
+ <link linkend="IEventListener">IEventListener</link> interface), which
+ will then get notified by the server when an event (represented by the
+ <link linkend="IEvent">IEvent</link> interface) happens.</para>
+
+ <para>The IEvent interface is an abstract parent interface for all
+ events that can occur in VirtualBox. The actual events that the server
+ sends out are then of one of the specific subclasses, for example
+ <link linkend="IMachineStateChangedEvent">IMachineStateChangedEvent</link>
+ or
+ <link linkend="IMediumChangedEvent">IMediumChangedEvent</link>.</para>
+
+ <para>As an example, the VirtualBox GUI waits for machine events and can
+ thus update its display when the machine state changes or machine
+ settings are modified, even if this happens in another client. This is
+ how the GUI can automatically refresh its display even if you manipulate
+ a machine from another client, for example, from VBoxManage.</para>
+
+ <para>To register an event listener to listen to events, use code like
+ this:<screen>EventSource es = console.getEventSource();
+IEventListener listener = es.createListener();
+VBoxEventType aTypes[] = (VBoxEventType.OnMachineStateChanged);
+ // list of event types to listen for
+es.registerListener(listener, aTypes, false /* active */);
+ // register passive listener
+IEvent ev = es.getEvent(listener, 1000);
+ // wait up to one second for event to happen
+if (ev != null)
+{
+ // downcast to specific event interface (in this case we have only registered
+ // for one type, otherwise IEvent::type would tell us)
+ IMachineStateChangedEvent mcse = IMachineStateChangedEvent.queryInterface(ev);
+ ... // inspect and do something
+ es.eventProcessed(listener, ev);
+}
+...
+es.unregisterListener(listener); </screen></para>
+
+ <para>A graphical user interface would probably best start its own
+ thread to wait for events and then process these in a loop.</para>
+
+ <para>The events mechanism was introduced with VirtualBox 3.3 and
+ replaces various callback interfaces which were called for each event in
+ the interface. The callback mechanism was not compatible with scripting
+ languages, local Java bindings and remote web services as they do not
+ support callbacks. The new mechanism with events and event listeners
+ works with all of these.</para>
+
+ <para>To simplify developement of application using events, concept of
+ event aggregator was introduced. Essentially it's mechanism to aggregate
+ multiple event sources into single one, and then work with this single
+ aggregated event source instead of original sources. As an example, one
+ can evaluate demo recorder in VirtualBox Python shell, shipped with SDK
+ - it records mouse and keyboard events, represented as separate event
+ sources. Code is essentially like this:<screen>
+ listener = console.eventSource.createListener()
+ agg = console.eventSource.createAggregator([console.keyboard.eventSource, console.mouse.eventSource])
+ agg.registerListener(listener, [ctx['global'].constants.VBoxEventType_Any], False)
+ registered = True
+ end = time.time() + dur
+ while time.time() &lt; end:
+ ev = agg.getEvent(listener, 1000)
+ processEent(ev)
+ agg.unregisterListener(listener)</screen> Without using aggregators
+ consumer have to poll on both sources, or start multiple threads to
+ block on those sources.</para>
+ </sect1>
+ </chapter>
+
+ <chapter id="vboxshell">
+ <title>The VirtualBox shell</title>
+
+ <para>VirtualBox comes with an extensible shell, which allows you to
+ control your virtual machines from the command line. It is also a
+ nontrivial example of how to use the VirtualBox APIs from Python, for all
+ three COM/XPCOM/WS styles of the API.</para>
+
+ <para>You can easily extend this shell with your own commands. Create a
+ subdirectory named
+ <computeroutput>.config/VirtualBox/shexts</computeroutput> below your home
+ directory (respectively <computeroutput>.VirtualBox/shexts</computeroutput>
+ on a Windows system and
+ <computeroutput>Library/VirtualBox/shexts</computeroutput> on OS X) and put
+ a Python file implementing your shell extension commands in this directory.
+ This file must contain an array named
+ <computeroutput>commands</computeroutput> containing your command
+ definitions: <screen>
+ commands = {
+ 'cmd1': ['Command cmd1 help', cmd1],
+ 'cmd2': ['Command cmd2 help', cmd2]
+ }
+ </screen> For example, to create a command for creating hard drive
+ images, the following code can be used: <screen>
+ def createHdd(ctx,args):
+ # Show some meaningful error message on wrong input
+ if (len(args) &lt; 3):
+ print "usage: createHdd sizeM location type"
+ return 0
+
+ # Get arguments
+ size = int(args[1])
+ loc = args[2]
+ if len(args) &gt; 3:
+ format = args[3]
+ else:
+ # And provide some meaningful defaults
+ format = "vdi"
+
+ # Call VirtualBox API, using context's fields
+ hdd = ctx['vb'].createMedium(format, loc, ctx['global'].constants.AccessMode_ReadWrite, \
+ ctx['global'].constants.DeviceType_HardDisk)
+ # Access constants using ctx['global'].constants
+ progress = hdd.createBaseStorage(size, (ctx['global'].constants.MediumVariant_Standard, ))
+ # use standard progress bar mechanism
+ ctx['progressBar'](progress)
+
+
+ # Report errors
+ if not hdd.id:
+ print "cannot create disk (file %s exist?)" %(loc)
+ return 0
+
+ # Give user some feedback on success too
+ print "created HDD with id: %s" %(hdd.id)
+
+ # 0 means continue execution, other values mean exit from the interpreter
+ return 0
+
+ commands = {
+ 'myCreateHDD': ['Create virtual HDD, createHdd size location type', createHdd]
+ }
+ </screen> Just store the above text in the file
+ <computeroutput>createHdd</computeroutput> (or any other meaningful name)
+ in <computeroutput>.config/VirtualBox/shexts/</computeroutput>. Start the
+ VirtualBox shell, or just issue the
+ <computeroutput>reloadExts</computeroutput> command, if the shell is
+ already running. Your new command will now be available.</para>
+ </chapter>
+
+ <xi:include href="SDKRef_apiref.xml" xpointer="xpointer(/book/*)"
+ xmlns:xi="http://www.w3.org/2001/XInclude" />
+
+ <chapter id="cloud">
+ <title>Working with the Cloud</title>
+
+ <para>VirtualBox supports and goes towards the Oracle tendencies like "move to the Cloud".</para>
+
+ <sect1>
+ <title>OCI features</title>
+ <para>VirtualBox supports the Oracle Cloud Infrastructure (OCI). See the interfaces:
+ <link linkend="ICloudClient">ICloudClient</link>,
+ <link linkend="ICloudProvider">ICloudProvider</link>,
+ <link linkend="ICloudProfile">ICloudProfile</link>,
+ <link linkend="ICloudProviderManager">ICloudProviderManager</link>.
+ </para>
+ <para>Each cloud interface has own implementation to support OCI features. There are everal functions in the implementation
+ which should be explained in details because OCI requires some special data or settings.
+ </para>
+ <para>
+ Also see the enumeration <link linkend="VirtualSystemDescriptionType">VirtualSystemDescriptionType</link> for the possible values.
+ </para>
+ </sect1>
+
+ <sect1>
+ <title>Function ICloudClient::exportVM</title>
+ <para>
+ See the <link linkend="ICloudClient__exportVM">ICloudClient::exportVM</link>.
+ The function exports an existing virtual machine into OCI. The final result of this operation is creation a custom image
+ from the bootable image of VM. The Id of created image is returned in the parameter "description" (which is
+ <link linkend="IVirtualSystemDescription">IVirtualSystemDescription</link>) as an entry with the type
+ VirtualSystemDescriptionType::CloudImageId. The standard steps here are:
+ <itemizedlist>
+ <listitem>
+ <para>Upload VBox image to OCI Object Storage.</para>
+ </listitem>
+ <listitem>
+ <para>Create OCI custom image from the uploaded object.</para>
+ </listitem>
+ </itemizedlist>
+ Parameter "description" must contain all information and settings needed for creation a custom image in OCI.
+ At least next entries must be presented there before the call:
+ <itemizedlist>
+ <listitem>
+ <para>VirtualSystemDescriptionType::Name - Name of new instance in OCI.</para>
+ </listitem>
+ <listitem>
+ <para>VirtualSystemDescriptionType::HardDiskImage - The local path or id of bootable VM image.</para>
+ </listitem>
+ <listitem>
+ <para>VirtualSystemDescriptionType::CloudBucket - A cloud bucket name where the exported image is uploaded.</para>
+ </listitem>
+ <listitem>
+ <para>VirtualSystemDescriptionType::CloudImageDisplayName - A name which is assigned to a new custom image in the OCI.</para>
+ </listitem>
+ <listitem>
+ <para>VirtualSystemDescriptionType::CloudKeepObject - Whether keep or delete an uploaded object after its usage.</para>
+ </listitem>
+ <listitem>
+ <para>VirtualSystemDescriptionType::CloudLaunchInstance - Whether launch or not a new instance.</para>
+ </listitem>
+ </itemizedlist>
+ </para>
+ </sect1>
+
+ <sect1>
+ <title>Function ICloudClient::launchVM</title>
+ <para>
+ See the <link linkend="ICloudClient__launchVM">ICloudClient::launchVM</link>.
+ The function launches a new instance in OCI with a bootable volume previously created from a custom image in OCI or
+ as the source may be used an existing bootable volume which shouldn't be attached to any instance.
+ For launching instance from a custom image use the parameter VirtualSystemDescriptionType::CloudImageId.
+ For launching instance from a bootable volume use the parameter VirtualSystemDescriptionType::CloudBootVolumeId.
+ Only one of them must be presented otherwise the error will occur.
+ The final result of this operation is a running instance. The id of created instance is returned
+ in the parameter "description" (which is <link linkend="IVirtualSystemDescription">IVirtualSystemDescription</link>)
+ as an entry with the type VirtualSystemDescriptionType::CloudInstanceId. Parameter "description" must contain all information
+ and settings needed for creation a new instance in OCI. At least next entries must be presented there before the call:
+ <itemizedlist>
+ <listitem>
+ <para>VirtualSystemDescriptionType::Name - Name of new instance in OCI.</para>
+ </listitem>
+ <listitem>
+ <para>VirtualSystemDescriptionType::CloudOCISubnet - OCID of existing subnet in OCI which will be used by the instance.</para>
+ </listitem>
+ <listitem>
+ <para>
+ Use VirtualSystemDescriptionType::CloudImageId - OCID of custom image used as a bootable image for the instance
+ or
+ VirtualSystemDescriptionType::CloudBootVolumeId - OCID of existing and non-attached bootable volume used as a bootable volume for the instance.
+ </para>
+ </listitem>
+ <listitem>
+ <para>Add VirtualSystemDescriptionType::CloudBootDiskSize - The size of instance bootable volume in GB,
+ If you use VirtualSystemDescriptionType::CloudImageId.</para>
+ </listitem>
+ <listitem>
+ <para>VirtualSystemDescriptionType::CloudInstanceShape - The shape of instance according to OCI documentation,
+ defines the number of CPUs and RAM memory.</para>
+ </listitem>
+ <listitem>
+ <para>VirtualSystemDescriptionType::CloudLaunchInstance - Whether launch or not a new instance.</para>
+ </listitem>
+ <listitem>
+ <para>VirtualSystemDescriptionType::CloudDomain - Availability domain in OCI where new instance is created.</para>
+ </listitem>
+ <listitem>
+ <para>VirtualSystemDescriptionType::CloudPublicIP - Whether the instance will have a public IP or not.</para>
+ </listitem>
+ <listitem>
+ <para>VirtualSystemDescriptionType::CloudPublicSSHKey - Public SSH key which is used to connect to an instance via SSH.
+ It may be one or more records with the type VirtualSystemDescriptionType::CloudPublicSSHKey in the VirtualSystemDescription.
+ But at least one should be presented otherwise user won't be able to connect to the instance via SSH.
+ </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+ </sect1>
+
+ <sect1>
+ <title>Function ICloudClient::getInstanceInfo</title>
+ <para>
+ See the <link linkend="ICloudClient__getInstanceInfo">ICloudClient::getInstanceInfo</link>.
+ The function takes an instance id (parameter "uid"), finds the requested instance in OCI and gets back information
+ about the found instance in the parameter "description" (which is <link linkend="IVirtualSystemDescription">IVirtualSystemDescription</link>)
+ The entries with next types will be presented in the object:
+ <itemizedlist>
+ <listitem>
+ <para>VirtualSystemDescriptionType::Name - Displayed name of the instance.</para>
+ </listitem>
+ <listitem>
+ <para>VirtualSystemDescriptionType::CloudDomain - Availability domain in OCI.</para>
+ </listitem>
+ <listitem>
+ <para>VirtualSystemDescriptionType::CloudImageId - Name of custom image used for creation this instance.</para>
+ </listitem>
+ <listitem>
+ <para>VirtualSystemDescriptionType::CloudInstanceId - The OCID of the instance.</para>
+ </listitem>
+ <listitem>
+ <para>VirtualSystemDescriptionType::OS - Guest OS type of the instance.</para>
+ </listitem>
+ <listitem>
+ <para>VirtualSystemDescriptionType::CloudBootDiskSize - Size of instance bootable image.</para>
+ </listitem>
+ <listitem>
+ <para>VirtualSystemDescriptionType::CloudInstanceState - The instance state according to OCI documentation.</para>
+ </listitem>
+ <listitem>
+ <para>VirtualSystemDescriptionType::CloudInstanceShape - The instance shape according to OCI documentation</para>
+ </listitem>
+ <listitem>
+ <para>VirtualSystemDescriptionType::Memory - RAM memory in GB allocated for the instance.</para>
+ </listitem>
+ <listitem>
+ <para>VirtualSystemDescriptionType::CPU - Number of virtual CPUs allocated for the instance.</para>
+ </listitem>
+ </itemizedlist>
+ </para>
+ </sect1>
+
+ <sect1>
+ <title>Function ICloudClient::importInstance</title>
+ <para>
+ See the <link linkend="ICloudClient__importInstance">ICloudClient::importInstance</link>.
+ The API function imports an existing instance from the OCI to the local host.
+ The standard steps here are:
+ <itemizedlist>
+ <listitem>
+ <para>Create a custom image from an existing OCI instance.</para>
+ </listitem>
+ <listitem>
+ <para>Export the custom image to OCI object (the object is created in the OCI Object Storage).</para>
+ </listitem>
+ <listitem>
+ <para>Download the OCI object to the local host.</para>
+ </listitem>
+ </itemizedlist>
+ As the result of operation user will have a file with the suffix ".oci" on the local host. This file is a TAR archive which
+ contains a bootable instance image in QCOW2 format and a JSON file with some metadata related to
+ the imported instance. The function takes the parameter "description"
+ (which is <link linkend="IVirtualSystemDescription">IVirtualSystemDescription</link>)
+ Parameter "description" must contain all information and settings needed for successful operation result.
+ At least next entries must be presented there before the call:
+ <itemizedlist>
+ <listitem>
+ <para>VirtualSystemDescriptionType::Name is used for the several purposes:
+ <itemizedlist>
+ <listitem>
+ <para>As a custom image name. A custom image is created from an instance.</para>
+ </listitem>
+ <listitem>
+ <para>As OCI object name. An object is a file in OCI Object Storage. The object is created from the custom image.</para>
+ </listitem>
+ <listitem>
+ <para>Name of imported instance on the local host. Because the result of import is a file, the file will have this
+ name and extension ".oci".</para>
+ </listitem>
+ </itemizedlist>
+ </para>
+ </listitem>
+ <listitem>
+ <para>VirtualSystemDescriptionType::CloudInstanceId - The OCID of the existing instance.</para>
+ </listitem>
+ <listitem>
+ <para>VirtualSystemDescriptionType::CloudBucket - a cloud bucket name in OCI Object Storage where created an OCI object
+ from a custom image.
+ </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+ </sect1>
+
+ </chapter>
+
+ <chapter id="hgcm">
+ <title>Host-Guest Communication Manager</title>
+
+ <para>The VirtualBox Host-Guest Communication Manager (HGCM) allows a
+ guest application or a guest driver to call a host shared library. The
+ following features of VirtualBox are implemented using HGCM: <itemizedlist>
+ <listitem>
+ <para>Shared Folders</para>
+ </listitem>
+
+ <listitem>
+ <para>Shared Clipboard</para>
+ </listitem>
+
+ <listitem>
+ <para>Guest configuration interface</para>
+ </listitem>
+ </itemizedlist></para>
+
+ <para>The shared library contains a so called HGCM service. The guest HGCM
+ clients establish connections to the service to call it. When calling a
+ HGCM service the client supplies a function code and a number of
+ parameters for the function.</para>
+
+ <sect1>
+ <title>Virtual hardware implementation</title>
+
+ <para>HGCM uses the VMM virtual PCI device to exchange data between the
+ guest and the host. The guest always acts as an initiator of requests. A
+ request is constructed in the guest physical memory, which must be
+ locked by the guest. The physical address is passed to the VMM device
+ using a 32-bit <computeroutput>out edx, eax</computeroutput>
+ instruction. The physical memory must be allocated below 4GB by 64-bit
+ guests.</para>
+
+ <para>The host parses the request header and data and queues the request
+ for a host HGCM service. The guest continues execution and usually waits
+ on a HGCM event semaphore.</para>
+
+ <para>When the request has been processed by the HGCM service, the VMM
+ device sets the completion flag in the request header, sets the HGCM
+ event and raises an IRQ for the guest. The IRQ handler signals the HGCM
+ event semaphore and all HGCM callers check the completion flag in the
+ corresponding request header. If the flag is set, the request is
+ considered completed.</para>
+ </sect1>
+
+ <sect1>
+ <title>Protocol specification</title>
+
+ <para>The HGCM protocol definitions are contained in the
+ <computeroutput>VBox/VBoxGuest.h</computeroutput></para>
+
+ <sect2>
+ <title>Request header</title>
+
+ <para>HGCM request structures contains a generic header
+ (VMMDevHGCMRequestHeader): <table>
+ <title>HGCM Request Generic Header</title>
+
+ <tgroup cols="2">
+ <tbody>
+ <row>
+ <entry><emphasis role="bold">Name</emphasis></entry>
+
+ <entry><emphasis role="bold">Description</emphasis></entry>
+ </row>
+
+ <row>
+ <entry>size</entry>
+
+ <entry>Size of the entire request.</entry>
+ </row>
+
+ <row>
+ <entry>version</entry>
+
+ <entry>Version of the header, must be set to
+ <computeroutput>0x10001</computeroutput>.</entry>
+ </row>
+
+ <row>
+ <entry>type</entry>
+
+ <entry>Type of the request.</entry>
+ </row>
+
+ <row>
+ <entry>rc</entry>
+
+ <entry>HGCM return code, which will be set by the VMM
+ device.</entry>
+ </row>
+
+ <row>
+ <entry>reserved1</entry>
+
+ <entry>A reserved field 1.</entry>
+ </row>
+
+ <row>
+ <entry>reserved2</entry>
+
+ <entry>A reserved field 2.</entry>
+ </row>
+
+ <row>
+ <entry>flags</entry>
+
+ <entry>HGCM flags, set by the VMM device.</entry>
+ </row>
+
+ <row>
+ <entry>result</entry>
+
+ <entry>The HGCM result code, set by the VMM device.</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table> <note>
+ <itemizedlist>
+ <listitem>
+ <para>All fields are 32-bit.</para>
+ </listitem>
+
+ <listitem>
+ <para>Fields from <computeroutput>size</computeroutput> to
+ <computeroutput>reserved2</computeroutput> are a standard VMM
+ device request header, which is used for other interfaces as
+ well.</para>
+ </listitem>
+ </itemizedlist>
+ </note></para>
+
+ <para>The <emphasis role="bold">type</emphasis> field indicates the
+ type of the HGCM request: <table>
+ <title>Request Types</title>
+
+ <tgroup cols="2">
+ <tbody>
+ <row>
+ <entry><emphasis role="bold">Name (decimal
+ value)</emphasis></entry>
+
+ <entry><emphasis role="bold">Description</emphasis></entry>
+ </row>
+
+ <row>
+ <entry>VMMDevReq_HGCMConnect
+ (<computeroutput>60</computeroutput>)</entry>
+
+ <entry>Connect to a HGCM service.</entry>
+ </row>
+
+ <row>
+ <entry>VMMDevReq_HGCMDisconnect
+ (<computeroutput>61</computeroutput>)</entry>
+
+ <entry>Disconnect from the service.</entry>
+ </row>
+
+ <row>
+ <entry>VMMDevReq_HGCMCall32
+ (<computeroutput>62</computeroutput>)</entry>
+
+ <entry>Call a HGCM function using the 32-bit
+ interface.</entry>
+ </row>
+
+ <row>
+ <entry>VMMDevReq_HGCMCall64
+ (<computeroutput>63</computeroutput>)</entry>
+
+ <entry>Call a HGCM function using the 64-bit
+ interface.</entry>
+ </row>
+
+ <row>
+ <entry>VMMDevReq_HGCMCancel
+ (<computeroutput>64</computeroutput>)</entry>
+
+ <entry>Cancel a HGCM request currently being processed by a
+ host HGCM service.</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table></para>
+
+ <para>The <emphasis role="bold">flags</emphasis> field may contain:
+ <table>
+ <title>Flags</title>
+
+ <tgroup cols="2">
+ <tbody>
+ <row>
+ <entry><emphasis role="bold">Name (hexadecimal
+ value)</emphasis></entry>
+
+ <entry><emphasis role="bold">Description</emphasis></entry>
+ </row>
+
+ <row>
+ <entry>VBOX_HGCM_REQ_DONE
+ (<computeroutput>0x00000001</computeroutput>)</entry>
+
+ <entry>The request has been processed by the host
+ service.</entry>
+ </row>
+
+ <row>
+ <entry>VBOX_HGCM_REQ_CANCELLED
+ (<computeroutput>0x00000002</computeroutput>)</entry>
+
+ <entry>This request was cancelled.</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table></para>
+ </sect2>
+
+ <sect2>
+ <title>Connect</title>
+
+ <para>The connection request must be issued by the guest HGCM client
+ before it can call the HGCM service (VMMDevHGCMConnect): <table>
+ <title>Connect request</title>
+
+ <tgroup cols="2">
+ <tbody>
+ <row>
+ <entry><emphasis role="bold">Name</emphasis></entry>
+
+ <entry><emphasis role="bold">Description</emphasis></entry>
+ </row>
+
+ <row>
+ <entry>header</entry>
+
+ <entry>The generic HGCM request header with type equal to
+ VMMDevReq_HGCMConnect
+ (<computeroutput>60</computeroutput>).</entry>
+ </row>
+
+ <row>
+ <entry>type</entry>
+
+ <entry>The type of the service location information (32
+ bit).</entry>
+ </row>
+
+ <row>
+ <entry>location</entry>
+
+ <entry>The service location information (128 bytes).</entry>
+ </row>
+
+ <row>
+ <entry>clientId</entry>
+
+ <entry>The client identifier assigned to the connecting
+ client by the HGCM subsystem (32-bit).</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table> The <emphasis role="bold">type</emphasis> field tells the
+ HGCM how to look for the requested service: <table>
+ <title>Location Information Types</title>
+
+ <tgroup cols="2">
+ <tbody>
+ <row>
+ <entry><emphasis role="bold">Name (hexadecimal
+ value)</emphasis></entry>
+
+ <entry><emphasis role="bold">Description</emphasis></entry>
+ </row>
+
+ <row>
+ <entry>VMMDevHGCMLoc_LocalHost
+ (<computeroutput>0x1</computeroutput>)</entry>
+
+ <entry>The requested service is a shared library located on
+ the host and the location information contains the library
+ name.</entry>
+ </row>
+
+ <row>
+ <entry>VMMDevHGCMLoc_LocalHost_Existing
+ (<computeroutput>0x2</computeroutput>)</entry>
+
+ <entry>The requested service is a preloaded one and the
+ location information contains the service name.</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table> <note>
+ <para>Currently preloaded HGCM services are hard-coded in
+ VirtualBox: <itemizedlist>
+ <listitem>
+ <para>VBoxSharedFolders</para>
+ </listitem>
+
+ <listitem>
+ <para>VBoxSharedClipboard</para>
+ </listitem>
+
+ <listitem>
+ <para>VBoxGuestPropSvc</para>
+ </listitem>
+
+ <listitem>
+ <para>VBoxSharedOpenGL</para>
+ </listitem>
+ </itemizedlist></para>
+ </note> There is no difference between both types of HGCM services,
+ only the location mechanism is different.</para>
+
+ <para>The client identifier is returned by the host and must be used
+ in all subsequent requests by the client.</para>
+ </sect2>
+
+ <sect2>
+ <title>Disconnect</title>
+
+ <para>This request disconnects the client and makes the client
+ identifier invalid (VMMDevHGCMDisconnect): <table>
+ <title>Disconnect request</title>
+
+ <tgroup cols="2">
+ <tbody>
+ <row>
+ <entry><emphasis role="bold">Name</emphasis></entry>
+
+ <entry><emphasis role="bold">Description</emphasis></entry>
+ </row>
+
+ <row>
+ <entry>header</entry>
+
+ <entry>The generic HGCM request header with type equal to
+ VMMDevReq_HGCMDisconnect
+ (<computeroutput>61</computeroutput>).</entry>
+ </row>
+
+ <row>
+ <entry>clientId</entry>
+
+ <entry>The client identifier previously returned by the
+ connect request (32-bit).</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table></para>
+ </sect2>
+
+ <sect2>
+ <title>Call32 and Call64</title>
+
+ <para>Calls the HGCM service entry point (VMMDevHGCMCall) using 32-bit
+ or 64-bit addresses: <table>
+ <title>Call request</title>
+
+ <tgroup cols="2">
+ <tbody>
+ <row>
+ <entry><emphasis role="bold">Name</emphasis></entry>
+
+ <entry><emphasis role="bold">Description</emphasis></entry>
+ </row>
+
+ <row>
+ <entry>header</entry>
+
+ <entry>The generic HGCM request header with type equal to
+ either VMMDevReq_HGCMCall32
+ (<computeroutput>62</computeroutput>) or
+ VMMDevReq_HGCMCall64
+ (<computeroutput>63</computeroutput>).</entry>
+ </row>
+
+ <row>
+ <entry>clientId</entry>
+
+ <entry>The client identifier previously returned by the
+ connect request (32-bit).</entry>
+ </row>
+
+ <row>
+ <entry>function</entry>
+
+ <entry>The function code to be processed by the service (32
+ bit).</entry>
+ </row>
+
+ <row>
+ <entry>cParms</entry>
+
+ <entry>The number of following parameters (32-bit). This
+ value is 0 if the function requires no parameters.</entry>
+ </row>
+
+ <row>
+ <entry>parms</entry>
+
+ <entry>An array of parameter description structures
+ (HGCMFunctionParameter32 or
+ HGCMFunctionParameter64).</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table></para>
+
+ <para>The 32-bit parameter description (HGCMFunctionParameter32)
+ consists of 32-bit type field and 8 bytes of an opaque value, so 12
+ bytes in total. The 64-bit variant (HGCMFunctionParameter64) consists
+ of the type and 12 bytes of a value, so 16 bytes in total.</para>
+
+ <para><table>
+ <title>Parameter types</title>
+
+ <tgroup cols="2">
+ <tbody>
+ <row>
+ <entry><emphasis role="bold">Type</emphasis></entry>
+
+ <entry><emphasis role="bold">Format of the
+ value</emphasis></entry>
+ </row>
+
+ <row>
+ <entry>VMMDevHGCMParmType_32bit (1)</entry>
+
+ <entry>A 32-bit value.</entry>
+ </row>
+
+ <row>
+ <entry>VMMDevHGCMParmType_64bit (2)</entry>
+
+ <entry>A 64-bit value.</entry>
+ </row>
+
+ <row>
+ <entry>VMMDevHGCMParmType_PhysAddr (3)</entry>
+
+ <entry>A 32-bit size followed by a 32-bit or 64-bit guest
+ physical address.</entry>
+ </row>
+
+ <row>
+ <entry>VMMDevHGCMParmType_LinAddr (4)</entry>
+
+ <entry>A 32-bit size followed by a 32-bit or 64-bit guest
+ linear address. The buffer is used both for guest to host
+ and for host to guest data.</entry>
+ </row>
+
+ <row>
+ <entry>VMMDevHGCMParmType_LinAddr_In (5)</entry>
+
+ <entry>Same as VMMDevHGCMParmType_LinAddr but the buffer is
+ used only for host to guest data.</entry>
+ </row>
+
+ <row>
+ <entry>VMMDevHGCMParmType_LinAddr_Out (6)</entry>
+
+ <entry>Same as VMMDevHGCMParmType_LinAddr but the buffer is
+ used only for guest to host data.</entry>
+ </row>
+
+ <row>
+ <entry>VMMDevHGCMParmType_LinAddr_Locked (7)</entry>
+
+ <entry>Same as VMMDevHGCMParmType_LinAddr but the buffer is
+ already locked by the guest.</entry>
+ </row>
+
+ <row>
+ <entry>VMMDevHGCMParmType_LinAddr_Locked_In (1)</entry>
+
+ <entry>Same as VMMDevHGCMParmType_LinAddr_In but the buffer
+ is already locked by the guest.</entry>
+ </row>
+
+ <row>
+ <entry>VMMDevHGCMParmType_LinAddr_Locked_Out (1)</entry>
+
+ <entry>Same as VMMDevHGCMParmType_LinAddr_Out but the buffer
+ is already locked by the guest.</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table></para>
+
+ <para>The</para>
+ </sect2>
+
+ <sect2>
+ <title>Cancel</title>
+
+ <para>This request cancels a call request (VMMDevHGCMCancel): <table>
+ <title>Cancel request</title>
+
+ <tgroup cols="2">
+ <tbody>
+ <row>
+ <entry><emphasis role="bold">Name</emphasis></entry>
+
+ <entry><emphasis role="bold">Description</emphasis></entry>
+ </row>
+
+ <row>
+ <entry>header</entry>
+
+ <entry>The generic HGCM request header with type equal to
+ VMMDevReq_HGCMCancel
+ (<computeroutput>64</computeroutput>).</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table></para>
+ </sect2>
+ </sect1>
+
+ <sect1>
+ <title>Guest software interface</title>
+
+ <para>The guest HGCM clients can call HGCM services from both drivers
+ and applications.</para>
+
+ <sect2>
+ <title>The guest driver interface</title>
+
+ <para>The driver interface is implemented in the VirtualBox guest
+ additions driver (VBoxGuest), which works with the VMM virtual device.
+ Drivers must use the VBox Guest Library (VBGL), which provides an API
+ for HGCM clients (<computeroutput>VBox/VBoxGuestLib.h</computeroutput>
+ and <computeroutput>VBox/VBoxGuest.h</computeroutput>).</para>
+
+ <para><screen>
+DECLR0VBGL(int) VbglR0HGCMConnect(VBGLHGCMHANDLE *pHandle, const char *pszServiceName, HGCMCLIENTID *pidClient);
+ </screen> Connects to the service: <screen>
+ VBoxGuestHGCMConnectInfo data;
+
+ memset(&amp;data, sizeof(VBoxGuestHGCMConnectInfo));
+
+ data.result = VINF_SUCCESS;
+ data.Loc.type = VMMDevHGCMLoc_LocalHost_Existing;
+ strcpy (data.Loc.u.host.achName, "VBoxSharedFolders");
+
+ rc = VbglHGCMConnect (&amp;handle, "VBoxSharedFolders"&amp;data);
+
+ if (RT_SUCCESS (rc))
+ {
+ rc = data.result;
+ }
+
+ if (RT_SUCCESS (rc))
+ {
+ /* Get the assigned client identifier. */
+ ulClientID = data.u32ClientID;
+ }
+ </screen></para>
+
+ <para><screen>
+DECLVBGL(int) VbglHGCMDisconnect (VBGLHGCMHANDLE handle, VBoxGuestHGCMDisconnectInfo *pData);
+ </screen> Disconnects from the service. <screen>
+ VBoxGuestHGCMDisconnectInfo data;
+
+ RtlZeroMemory (&amp;data, sizeof (VBoxGuestHGCMDisconnectInfo));
+
+ data.result = VINF_SUCCESS;
+ data.u32ClientID = ulClientID;
+
+ rc = VbglHGCMDisconnect (handle, &amp;data);
+ </screen></para>
+
+ <para><screen>
+DECLVBGL(int) VbglHGCMCall (VBGLHGCMHANDLE handle, VBoxGuestHGCMCallInfo *pData, uint32_t cbData);
+ </screen> Calls a function in the service. <screen>
+typedef struct _VBoxSFRead
+{
+ VBoxGuestHGCMCallInfo callInfo;
+
+ /** pointer, in: SHFLROOT
+ * Root handle of the mapping which name is queried.
+ */
+ HGCMFunctionParameter root;
+
+ /** value64, in:
+ * SHFLHANDLE of object to read from.
+ */
+ HGCMFunctionParameter handle;
+
+ /** value64, in:
+ * Offset to read from.
+ */
+ HGCMFunctionParameter offset;
+
+ /** value64, in/out:
+ * Bytes to read/How many were read.
+ */
+ HGCMFunctionParameter cb;
+
+ /** pointer, out:
+ * Buffer to place data to.
+ */
+ HGCMFunctionParameter buffer;
+
+} VBoxSFRead;
+
+/** Number of parameters */
+#define SHFL_CPARMS_READ (5)
+
+...
+
+ VBoxSFRead data;
+
+ /* The call information. */
+ data.callInfo.result = VINF_SUCCESS; /* Will be returned by HGCM. */
+ data.callInfo.u32ClientID = ulClientID; /* Client identifier. */
+ data.callInfo.u32Function = SHFL_FN_READ; /* The function code. */
+ data.callInfo.cParms = SHFL_CPARMS_READ; /* Number of parameters. */
+
+ /* Initialize parameters. */
+ data.root.type = VMMDevHGCMParmType_32bit;
+ data.root.u.value32 = pMap-&gt;root;
+
+ data.handle.type = VMMDevHGCMParmType_64bit;
+ data.handle.u.value64 = hFile;
+
+ data.offset.type = VMMDevHGCMParmType_64bit;
+ data.offset.u.value64 = offset;
+
+ data.cb.type = VMMDevHGCMParmType_32bit;
+ data.cb.u.value32 = *pcbBuffer;
+
+ data.buffer.type = VMMDevHGCMParmType_LinAddr_Out;
+ data.buffer.u.Pointer.size = *pcbBuffer;
+ data.buffer.u.Pointer.u.linearAddr = (uintptr_t)pBuffer;
+
+ rc = VbglHGCMCall (handle, &amp;data.callInfo, sizeof (data));
+
+ if (RT_SUCCESS (rc))
+ {
+ rc = data.callInfo.result;
+ *pcbBuffer = data.cb.u.value32; /* This is returned by the HGCM service. */
+ }
+ </screen></para>
+ </sect2>
+
+ <sect2>
+ <title>Guest application interface</title>
+
+ <para>Applications call the VirtualBox Guest Additions driver to
+ utilize the HGCM interface. There are IOCTL's which correspond to the
+ <computeroutput>Vbgl*</computeroutput> functions: <itemizedlist>
+ <listitem>
+ <para><computeroutput>VBOXGUEST_IOCTL_HGCM_CONNECT</computeroutput></para>
+ </listitem>
+
+ <listitem>
+ <para><computeroutput>VBOXGUEST_IOCTL_HGCM_DISCONNECT</computeroutput></para>
+ </listitem>
+
+ <listitem>
+ <para><computeroutput>VBOXGUEST_IOCTL_HGCM_CALL</computeroutput></para>
+ </listitem>
+ </itemizedlist></para>
+
+ <para>These IOCTL's get the same input buffer as
+ <computeroutput>VbglHGCM*</computeroutput> functions and the output
+ buffer has the same format as the input buffer. The same address can
+ be used as the input and output buffers.</para>
+
+ <para>For example see the guest part of shared clipboard, which runs
+ as an application and uses the HGCM interface.</para>
+ </sect2>
+ </sect1>
+
+ <sect1>
+ <title>HGCM Service Implementation</title>
+
+ <para>The HGCM service is a shared library with a specific set of entry
+ points. The library must export the
+ <computeroutput>VBoxHGCMSvcLoad</computeroutput> entry point: <screen>
+extern "C" DECLCALLBACK(DECLEXPORT(int)) VBoxHGCMSvcLoad (VBOXHGCMSVCFNTABLE *ptable)
+ </screen></para>
+
+ <para>The service must check the
+ <computeroutput>ptable-&gt;cbSize</computeroutput> and
+ <computeroutput>ptable-&gt;u32Version</computeroutput> fields of the
+ input structure and fill the remaining fields with function pointers of
+ entry points and the size of the required client buffer size.</para>
+
+ <para>The HGCM service gets a dedicated thread, which calls service
+ entry points synchronously, that is the service will be called again
+ only when a previous call has returned. However, the guest calls can be
+ processed asynchronously. The service must call a completion callback
+ when the operation is actually completed. The callback can be issued
+ from another thread as well.</para>
+
+ <para>Service entry points are listed in the
+ <computeroutput>VBox/hgcmsvc.h</computeroutput> in the
+ <computeroutput>VBOXHGCMSVCFNTABLE</computeroutput> structure. <table>
+ <title>Service entry points</title>
+
+ <tgroup cols="2">
+ <tbody>
+ <row>
+ <entry><emphasis role="bold">Entry</emphasis></entry>
+
+ <entry><emphasis role="bold">Description</emphasis></entry>
+ </row>
+
+ <row>
+ <entry>pfnUnload</entry>
+
+ <entry>The service is being unloaded.</entry>
+ </row>
+
+ <row>
+ <entry>pfnConnect</entry>
+
+ <entry>A client <computeroutput>u32ClientID</computeroutput>
+ is connected to the service. The
+ <computeroutput>pvClient</computeroutput> parameter points to
+ an allocated memory buffer which can be used by the service to
+ store the client information.</entry>
+ </row>
+
+ <row>
+ <entry>pfnDisconnect</entry>
+
+ <entry>A client is being disconnected.</entry>
+ </row>
+
+ <row>
+ <entry>pfnCall</entry>
+
+ <entry>A guest client calls a service function. The
+ <computeroutput>callHandle</computeroutput> must be used in
+ the VBOXHGCMSVCHELPERS::pfnCallComplete callback when the call
+ has been processed.</entry>
+ </row>
+
+ <row>
+ <entry>pfnHostCall</entry>
+
+ <entry>Called by the VirtualBox host components to perform
+ functions which should be not accessible by the guest. Usually
+ this entry point is used by VirtualBox to configure the
+ service.</entry>
+ </row>
+
+ <row>
+ <entry>pfnSaveState</entry>
+
+ <entry>The VM state is being saved and the service must save
+ relevant information using the SSM API
+ (<computeroutput>VBox/ssm.h</computeroutput>).</entry>
+ </row>
+
+ <row>
+ <entry>pfnLoadState</entry>
+
+ <entry>The VM is being restored from the saved state and the
+ service must load the saved information and be able to
+ continue operations from the saved state.</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table></para>
+ </sect1>
+ </chapter>
+
+ <chapter id="rdpweb">
+ <title>RDP Web Control</title>
+
+ <para>The VirtualBox <emphasis>RDP Web Control</emphasis> (RDPWeb)
+ provides remote access to a running VM. RDPWeb is a RDP (Remote Desktop
+ Protocol) client based on Flash technology and can be used from a Web
+ browser with a Flash plugin.</para>
+
+ <sect1>
+ <title>RDPWeb features</title>
+
+ <para>RDPWeb is embedded into a Web page and can connect to VRDP server
+ in order to displays the VM screen and pass keyboard and mouse events to
+ the VM.</para>
+ </sect1>
+
+ <sect1>
+ <title>RDPWeb reference</title>
+
+ <para>RDPWeb consists of two required components:<itemizedlist>
+ <listitem>
+ <para>Flash movie
+ <computeroutput>RDPClientUI.swf</computeroutput></para>
+ </listitem>
+
+ <listitem>
+ <para>JavaScript helpers
+ <computeroutput>webclient.js</computeroutput></para>
+ </listitem>
+ </itemizedlist></para>
+
+ <para>The VirtualBox SDK contains sample HTML code
+ including:<itemizedlist>
+ <listitem>
+ <para>JavaScript library for embedding Flash content
+ <computeroutput>SWFObject.js</computeroutput></para>
+ </listitem>
+
+ <listitem>
+ <para>Sample HTML page
+ <computeroutput>webclient3.html</computeroutput></para>
+ </listitem>
+ </itemizedlist></para>
+
+ <sect2>
+ <title>RDPWeb functions</title>
+
+ <para><computeroutput>RDPClientUI.swf</computeroutput> and
+ <computeroutput>webclient.js</computeroutput> work with each other.
+ JavaScript code is responsible for a proper SWF initialization,
+ delivering mouse events to the SWF and processing resize requests from
+ the SWF. On the other hand, the SWF contains a few JavaScript callable
+ methods, which are used both from
+ <computeroutput>webclient.js</computeroutput> and the user HTML
+ page.</para>
+
+ <sect3>
+ <title>JavaScript functions</title>
+
+ <para><computeroutput>webclient.js</computeroutput> contains helper
+ functions. In the following table ElementId refers to an HTML
+ element name or attribute, and Element to the HTML element itself.
+ HTML code<programlisting>
+ &lt;div id="FlashRDP"&gt;
+ &lt;/div&gt;
+</programlisting> would have ElementId equal to FlashRDP and Element equal to
+ the div element.</para>
+
+ <para><itemizedlist>
+ <listitem>
+ <programlisting>RDPWebClient.embedSWF(SWFFileName, ElementId)</programlisting>
+
+ <para>Uses SWFObject library to replace the HTML element with
+ the Flash movie.</para>
+ </listitem>
+
+ <listitem>
+ <programlisting>RDPWebClient.isRDPWebControlById(ElementId)</programlisting>
+
+ <para>Returns true if the given id refers to a RDPWeb Flash
+ element.</para>
+ </listitem>
+
+ <listitem>
+ <programlisting>RDPWebClient.isRDPWebControlByElement(Element)</programlisting>
+
+ <para>Returns true if the given element is a RDPWeb Flash
+ element.</para>
+ </listitem>
+
+ <listitem>
+ <programlisting>RDPWebClient.getFlashById(ElementId)</programlisting>
+
+ <para>Returns an element, which is referenced by the given id.
+ This function will try to resolve any element, event if it is
+ not a Flash movie.</para>
+ </listitem>
+ </itemizedlist></para>
+ </sect3>
+
+ <sect3>
+ <title>Flash methods callable from JavaScript</title>
+
+ <para><computeroutput>RDPWebClienUI.swf</computeroutput> methods can
+ be called directly from JavaScript code on a HTML page.</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>getProperty(Name)</para>
+ </listitem>
+
+ <listitem>
+ <para>setProperty(Name)</para>
+ </listitem>
+
+ <listitem>
+ <para>connect()</para>
+ </listitem>
+
+ <listitem>
+ <para>disconnect()</para>
+ </listitem>
+
+ <listitem>
+ <para>keyboardSendCAD()</para>
+ </listitem>
+ </itemizedlist>
+ </sect3>
+
+ <sect3>
+ <title>Flash JavaScript callbacks</title>
+
+ <para><computeroutput>RDPWebClienUI.swf</computeroutput> calls
+ JavaScript functions provided by the HTML page.</para>
+ </sect3>
+ </sect2>
+
+ <sect2>
+ <title>Embedding RDPWeb in an HTML page</title>
+
+ <para>It is necessary to include
+ <computeroutput>webclient.js</computeroutput> helper script. If
+ SWFObject library is used, the
+ <computeroutput>swfobject.js</computeroutput> must be also included
+ and RDPWeb flash content can be embedded to a Web page using dynamic
+ HTML. The HTML must include a "placeholder", which consists of 2
+ <computeroutput>div</computeroutput> elements.</para>
+ </sect2>
+ </sect1>
+
+ <sect1>
+ <title>RDPWeb change log</title>
+
+ <sect2>
+ <title>Version 1.2.28</title>
+
+ <itemizedlist>
+ <listitem>
+ <para><computeroutput>keyboardLayout</computeroutput>,
+ <computeroutput>keyboardLayouts</computeroutput>,
+ <computeroutput>UUID</computeroutput> properties.</para>
+ </listitem>
+
+ <listitem>
+ <para>Support for German keyboard layout on the client.</para>
+ </listitem>
+
+ <listitem>
+ <para>Rebranding to Oracle.</para>
+ </listitem>
+ </itemizedlist>
+ </sect2>
+
+ <sect2>
+ <title>Version 1.1.26</title>
+
+ <itemizedlist>
+ <listitem>
+ <para><computeroutput>webclient.js</computeroutput> is a part of
+ the distribution package.</para>
+ </listitem>
+
+ <listitem>
+ <para><computeroutput>lastError</computeroutput> property.</para>
+ </listitem>
+
+ <listitem>
+ <para><computeroutput>keyboardSendScancodes</computeroutput> and
+ <computeroutput>keyboardSendCAD</computeroutput> methods.</para>
+ </listitem>
+ </itemizedlist>
+ </sect2>
+
+ <sect2>
+ <title>Version 1.0.24</title>
+
+ <itemizedlist>
+ <listitem>
+ <para>Initial release.</para>
+ </listitem>
+ </itemizedlist>
+ </sect2>
+ </sect1>
+ </chapter>
+
+ <chapter id="dnd">
+ <title>Drag and Drop</title>
+
+ <para>Since VirtualBox 4.2 it's possible to transfer files from host to the
+ Linux guests by dragging files, directories or text from the host into the
+ guest's screen. This is called <emphasis>drag and drop
+ (DnD)</emphasis>.</para>
+
+ <para>In version 5.0 support for Windows guests has been added, as well as
+ the ability to transfer data the other way around, that is, from the guest
+ to the host.</para>
+
+ <note><para>Currently only the VirtualBox Manager frontend supports drag and
+ drop.</para></note>
+
+ <para>This chapter will show how to use the required interfaces provided
+ by VirtualBox for adding drag and drop functionality to third-party
+ frontends.</para>
+
+ <sect1>
+ <title>Basic concepts</title>
+
+ <para>In order to use the interfaces provided by VirtualBox, some basic
+ concepts needs to be understood first: To successfully initiate a
+ drag and drop operation at least two sides needs to be involved, a
+ <emphasis>source</emphasis> and a <emphasis>target</emphasis>:</para>
+
+ <para>The <emphasis>source</emphasis> is the side which provides the
+ data, e.g. is the origin of data. This data can be stored within the
+ source directly or can be retrieved on-demand by the source itself. Other
+ interfaces don't care where the data from this source actually came
+ from.</para>
+
+ <para>The <emphasis>target</emphasis> on the other hand is the side which
+ provides the source a visual representation where the user can drop the
+ data the source offers. This representation can be a window (or just a
+ certain part of it), for example.</para>
+
+ <para>The source and the target have abstract interfaces called
+ <link linkend="IDnDSource">IDnDSource</link> and
+ <link linkend="IDnDTarget">IDnDTarget</link>. VirtualBox also
+ provides implementations of both interfaces, called
+ <link linkend="IGuestDnDSource">IGuestDnDSource</link> and
+ <link linkend="IGuestDnDTarget">IGuestDnDTarget</link>. Both
+ implementations are also used in the VirtualBox Manager frontend.</para>
+ </sect1>
+
+ <sect1>
+ <title>Supported formats</title>
+
+ <para>As the target needs to perform specific actions depending on the
+ data the source provided, the target first needs to know what type of
+ data it actually is going to retrieve. It might be that the source offers
+ data the target cannot (or intentionally does not want to)
+ support.</para>
+
+ <para>VirtualBox handles those data types by providing so-called
+ <emphasis>MIME types</emphasis> -- these MIME types were originally
+ defined in
+ <ulink url="https://tools.ietf.org/html/rfc2046">RFC 2046</ulink> and
+ are also called <emphasis>Content-types</emphasis>.
+ <link linkend="IGuestDnDSource">IGuestDnDSource</link> and
+ <link linkend="IGuestDnDTarget">IGuestDnDTarget</link> support
+ the following MIME types by default:<itemizedlist>
+ <listitem>
+ <para><emphasis role="bold">text/uri-list</emphasis> - A list of
+ URIs (Uniform Resource Identifier, see
+ <ulink url="https://tools.ietf.org/html/rfc3986">RFC 3986</ulink>)
+ pointing to the file and/or directory paths already transferred
+ from the source to the target.</para>
+ </listitem>
+ <listitem>
+ <para><emphasis role="bold">text/plain;charset=utf-8</emphasis> and
+ <emphasis role="bold">UTF8_STRING</emphasis> - text in UTF-8
+ format.</para>
+ </listitem>
+ <listitem>
+ <para><emphasis role="bold">text/plain, TEXT</emphasis>
+ and <emphasis role="bold">STRING</emphasis> - plain ASCII text,
+ depending on the source's active ANSI page (if any).</para>
+ </listitem>
+ </itemizedlist>
+ </para>
+
+ <para>If, for whatever reason, a certain default format should not be
+ supported or a new format should be registered,
+ <link linkend="IDnDSource">IDnDSource</link> and
+ <link linkend="IDnDTarget">IDnDTarget</link> have methods derived from
+ <link linkend="IDnDBase">IDnDBase</link> which provide adding,
+ removing and enumerating specific formats.
+ <note><para>Registering new or removing default formats on the guest side
+ currently is not implemented.</para></note></para>
+ </sect1>
+
+ </chapter>
+
+ <chapter id="vbox-auth">
+ <title>VirtualBox external authentication modules</title>
+
+ <para>VirtualBox supports arbitrary external modules to perform
+ authentication. The module is used when the authentication method is set
+ to "external" for a particular VM VRDE access and the library was
+ specified with <computeroutput>VBoxManage setproperty
+ vrdeauthlibrary</computeroutput>. Web service also use the authentication
+ module which was specified with <computeroutput>VBoxManage setproperty
+ websrvauthlibrary</computeroutput>.</para>
+
+ <para>This library will be loaded by the VM or web service process on
+ demand, i.e. when the first remote desktop connection is made by a client
+ or when a client that wants to use the web service logs on.</para>
+
+ <para>External authentication is the most flexible as the external handler
+ can both choose to grant access to everyone (like the "null"
+ authentication method would) and delegate the request to the guest
+ authentication component. When delegating the request to the guest
+ component, the handler will still be called afterwards with the option to
+ override the result.</para>
+
+ <para>An authentication library is required to implement exactly one entry
+ point:</para>
+
+ <screen>#include "VBoxAuth.h"
+
+/**
+ * Authentication library entry point.
+ *
+ * Parameters:
+ *
+ * szCaller The name of the component which calls the library (UTF8).
+ * pUuid Pointer to the UUID of the accessed virtual machine. Can be NULL.
+ * guestJudgement Result of the guest authentication.
+ * szUser User name passed in by the client (UTF8).
+ * szPassword Password passed in by the client (UTF8).
+ * szDomain Domain passed in by the client (UTF8).
+ * fLogon Boolean flag. Indicates whether the entry point is called
+ * for a client logon or the client disconnect.
+ * clientId Server side unique identifier of the client.
+ *
+ * Return code:
+ *
+ * AuthResultAccessDenied Client access has been denied.
+ * AuthResultAccessGranted Client has the right to use the
+ * virtual machine.
+ * AuthResultDelegateToGuest Guest operating system must
+ * authenticate the client and the
+ * library must be called again with
+ * the result of the guest
+ * authentication.
+ *
+ * Note: When 'fLogon' is 0, only pszCaller, pUuid and clientId are valid and the return
+ * code is ignored.
+ */
+AuthResult AUTHCALL AuthEntry(
+ const char *szCaller,
+ PAUTHUUID pUuid,
+ AuthGuestJudgement guestJudgement,
+ const char *szUser,
+ const char *szPassword
+ const char *szDomain
+ int fLogon,
+ unsigned clientId)
+{
+ /* Process request against your authentication source of choice. */
+ // if (authSucceeded(...))
+ // return AuthResultAccessGranted;
+ return AuthResultAccessDenied;
+}</screen>
+
+ <para>A note regarding the UUID implementation of the
+ <computeroutput>pUuid</computeroutput> argument: VirtualBox uses a
+ consistent binary representation of UUIDs on all platforms. For this
+ reason the integer fields comprising the UUID are stored as little endian
+ values. If you want to pass such UUIDs to code which assumes that the
+ integer fields are big endian (often also called network byte order), you
+ need to adjust the contents of the UUID to e.g. achieve the same string
+ representation. The required changes are:<itemizedlist>
+ <listitem>
+ <para>reverse the order of byte 0, 1, 2 and 3</para>
+ </listitem>
+
+ <listitem>
+ <para>reverse the order of byte 4 and 5</para>
+ </listitem>
+
+ <listitem>
+ <para>reverse the order of byte 6 and 7.</para>
+ </listitem>
+ </itemizedlist>Using this conversion you will get identical results when
+ converting the binary UUID to the string representation.</para>
+
+ <para>The <computeroutput>guestJudgement</computeroutput> argument
+ contains information about the guest authentication status. For the first
+ call, it is always set to
+ <computeroutput>AuthGuestNotAsked</computeroutput>. In case the
+ <computeroutput>AuthEntry</computeroutput> function returns
+ <computeroutput>AuthResultDelegateToGuest</computeroutput>, a guest
+ authentication will be attempted and another call to the
+ <computeroutput>AuthEntry</computeroutput> is made with its result. This
+ can be either granted / denied or no judgement (the guest component chose
+ for whatever reason to not make a decision). In case there is a problem
+ with the guest authentication module (e.g. the Additions are not installed
+ or not running or the guest did not respond within a timeout), the "not
+ reacted" status will be returned.</para>
+ </chapter>
+
+ <chapter id="javaapi">
+ <title>Using Java API</title>
+
+ <sect1>
+ <title>Introduction</title>
+
+ <para>VirtualBox can be controlled by a Java API, both locally
+ (COM/XPCOM) and from remote (SOAP) clients. As with the Python bindings,
+ a generic glue layer tries to hide all platform differences, allowing
+ for source and binary compatibility on different platforms.</para>
+ </sect1>
+
+ <sect1>
+ <title>Requirements</title>
+
+ <para>To use the Java bindings, there are certain requirements depending
+ on the platform. First of all, you need JDK 1.5 (Java 5) or later. Also
+ please make sure that the version of the VirtualBox API .jar file
+ exactly matches the version of VirtualBox you use. To avoid confusion,
+ the VirtualBox API provides versioning in the Java package name, e.g.
+ the package is named <computeroutput>org.virtualbox_3_2</computeroutput>
+ for VirtualBox version 3.2. <itemizedlist>
+ <listitem>
+ <para><emphasis role="bold">XPCOM</emphasis> - for all platforms,
+ but Microsoft Windows. A Java bridge based on JavaXPCOM is shipped
+ with VirtualBox. The classpath must contain
+ <computeroutput>vboxjxpcom.jar</computeroutput> and the
+ <computeroutput>vbox.home</computeroutput> property must be set to
+ location where the VirtualBox binaries are. Please make sure that
+ the JVM bitness matches bitness of VirtualBox you use as the XPCOM
+ bridge relies on native libraries.</para>
+
+ <para>Start your application like this: <programlisting>
+ java -cp vboxjxpcom.jar -Dvbox.home=/opt/virtualbox MyProgram
+ </programlisting></para>
+ </listitem>
+
+ <listitem>
+ <para><emphasis role="bold">COM</emphasis> - for Microsoft
+ Windows. We rely on <computeroutput>Jacob</computeroutput> - a
+ generic Java to COM bridge - which has to be installed seperately.
+ See <ulink
+ url="http://sourceforge.net/projects/jacob-project/">http://sourceforge.net/projects/jacob-project/</ulink>
+ for installation instructions. Also, the VirtualBox provided
+ <computeroutput>vboxjmscom.jar</computeroutput> must be in the
+ class path.</para>
+
+ <para>Start your application like this:
+ <programlisting>java -cp vboxjmscom.jar;c:\jacob\jacob.jar -Djava.library.path=c:\jacob MyProgram</programlisting></para>
+ </listitem>
+
+ <listitem>
+ <para><emphasis role="bold">SOAP</emphasis> - all platforms. Java
+ 6 is required, as it comes with builtin support for SOAP via the
+ JAX-WS library. Also, the VirtualBox provided
+ <computeroutput>vbojws.jar</computeroutput> must be in the class
+ path. In the SOAP case it's possible to create several
+ VirtualBoxManager instances to communicate with multiple
+ VirtualBox hosts.</para>
+
+ <para>Start your application like this: <programlisting>
+ java -cp vboxjws.jar MyProgram
+ </programlisting></para>
+ </listitem>
+ </itemizedlist></para>
+
+ <para>Exception handling is also generalized by the generic glue layer,
+ so that all methods could throw
+ <computeroutput>VBoxException</computeroutput> containing human-readable
+ text message (see <computeroutput>getMessage()</computeroutput> method)
+ along with wrapped original exception (see
+ <computeroutput>getWrapped()</computeroutput> method).</para>
+ </sect1>
+
+ <sect1>
+ <title>Example</title>
+
+ <para>This example shows a simple use case of the Java API. Differences
+ for SOAP vs. local version are minimal, and limited to the connection
+ setup phase (see <computeroutput>ws</computeroutput> variable). In the
+ SOAP case it's possible to create several VirtualBoxManager instances to
+ communicate with multiple VirtualBox hosts. <programlisting>
+ import org.virtualbox_4_3.*;
+ ....
+ VirtualBoxManager mgr = VirtualBoxManager.createInstance(null);
+ boolean ws = false; // or true, if we need the SOAP version
+ if (ws)
+ {
+ String url = "http://myhost:18034";
+ String user = "test";
+ String passwd = "test";
+ mgr.connect(url, user, passwd);
+ }
+ IVirtualBox vbox = mgr.getVBox();
+ System.out.println("VirtualBox version: " + vbox.getVersion() + "\n");
+ // get first VM name
+ String m = vbox.getMachines().get(0).getName();
+ System.out.println("\nAttempting to start VM '" + m + "'");
+ // start it
+ mgr.startVm(m, null, 7000);
+
+ if (ws)
+ mgr.disconnect();
+
+ mgr.cleanup();
+ </programlisting> For more a complete example, see
+ <computeroutput>TestVBox.java</computeroutput>, shipped with the
+ SDK. It contains exception handling and error printing code, which
+ is important for reliable larger scale projects.</para>
+
+ <para>It is good practice in long-running API clients to process the
+ system events every now and then in the main thread (does not work
+ in other threads). As a rule of thumb it makes sense to process them
+ every few 100msec to every few seconds). This is done by
+ calling<programlisting>
+ mgr.waitForEvents(0);
+ </programlisting>
+ This avoids that a large number of system events accumulate, which can
+ need a significant amount of memory, and as they also play a role in
+ object cleanup it helps freeing additional memory in a timely manner
+ which is used by the API implementation itself. Java's garbage collection
+ approach already needs more memory due to the delayed freeing of memory
+ used by no longer accessible objects, and not processing the system
+ events exacerbates the memory usage. The
+ <computeroutput>TestVBox.java</computeroutput> example code sprinkles
+ such lines over the code to achieve the desired effect. In multi-threaded
+ applications it can be called from the main thread periodically.
+ Sometimes it's possible to use the non-zero timeout variant of the
+ method, which then waits the specified number of milliseconds for
+ events, processing them immediately as they arrive. It achieves better
+ runtime behavior than separate sleeping/processing.</para>
+ </sect1>
+ </chapter>
+
+ <chapter>
+ <title>License information</title>
+
+ <para>The sample code files shipped with the SDK are generally licensed
+ liberally to make it easy for anyone to use this code for their own
+ application code.</para>
+
+ <para>The Java files under
+ <computeroutput>bindings/webservice/java/jax-ws/</computeroutput> (library
+ files for the object-oriented web service) are, by contrast, licensed
+ under the GNU Lesser General Public License (LGPL) V2.1.</para>
+
+ <para>See
+ <computeroutput>sdk/bindings/webservice/java/jax-ws/src/COPYING.LIB</computeroutput>
+ for the full text of the LGPL 2.1.</para>
+
+ <para>When in doubt, please refer to the individual source code files
+ shipped with this SDK.</para>
+ </chapter>
+
+ <chapter>
+ <title>Main API change log</title>
+
+ <para>Generally, VirtualBox will maintain API compatibility within a major
+ release; a major release occurs when the first or the second of the three
+ version components of VirtualBox change (that is, in the x.y.z scheme, a
+ major release is one where x or y change, but not when only z
+ changes).</para>
+
+ <para>In other words, updates like those from 2.0.0 to 2.0.2 will not come
+ with API breakages.</para>
+
+ <para>Migration between major releases most likely will lead to API
+ breakage, so please make sure you updated code accordingly. The OOWS Java
+ wrappers enforce that mechanism by putting VirtualBox classes into
+ version-specific packages such as
+ <computeroutput>org.virtualbox_2_2</computeroutput>. This approach allows
+ for connecting to multiple VirtualBox versions simultaneously from the
+ same Java application.</para>
+
+ <para>The following sections list incompatible changes that the Main API
+ underwent since the original release of this SDK Reference with VirtualBox
+ 2.0. A change is deemed "incompatible" only if it breaks existing client
+ code (e.g. changes in method parameter lists, renamed or removed
+ interfaces and similar). In other words, the list does not contain new
+ interfaces, methods or attributes or other changes that do not affect
+ existing client code.</para>
+
+ <sect1>
+ <title>Incompatible API changes with version 7.0</title>
+
+ <itemizedlist>
+
+ <listitem><para>The machine's audio adapter has been moved into the new IAudioSettings interface, which in turn
+ takes care of of all audio settings of a virtual machine.
+ See <link linkend="IMachine__audioSettings">IMachine::audioSettings</link> and
+ <link linkend="IAudioSettings">IAudioSettings</link> for more information.</para>
+ </listitem>
+
+ <listitem><para>The <link linkend="IVirtualBox__openMachine">IVirtualBox::openMachine</link> call now
+ requires an additional password parameter. If the machine is not encrypted the parameter is ignored.</para>
+ </listitem>
+
+ <listitem><para>When a new VM is being created, the default audio driver will be now
+ <link linkend="AudioDriverType__Default">AudioDriverType_Default</link>. This driver
+ type will automatically choose the best audio driver (backend) for the host OS &VBOX_PRODUCT;
+ currently is running on.</para>
+ </listitem>
+
+ <listitem><para>The host update functionality at IHost::update has been refactored into
+ <link linkend="IHost__updateHost">IHost::updateHost</link>, which in turn uses the new
+ <link linkend="IHostUpdateAgent">IHostUpdateAgent</link> interface, derived from the new
+ <link linkend="IUpdateAgent">IUpdateAgent</link> interface.</para>
+ </listitem>
+
+ <listitem><para><link linkend="IGuestSession__directoryCopyFromGuest">IGuestSession::directoryCopyFromGuest()</link> and
+ <link linkend="IGuestSession__directoryCopyToGuest">IGuestSession::directoryCopyToGuest()</link> no longer implicitly
+ copy recursively and follow symbolic links -- for this to continue working, the newly introduced flags
+ <link linkend="DirectoryCopyFlag__Recursive">DirectoryCopyFlag::Recursive</link> and/or
+ <link linkend="DirectoryCopyFlag__FollowLinks">DirectoryCopyFlag::FollowLinks</link> have to be used.</para>
+ </listitem>
+
+ <listitem><para>VBoxEventType_Last has been renamed to <link linkend="VBoxEventType__End">VBoxEventType_End</link>
+ for consistency.</para></listitem>
+
+ </itemizedlist>
+
+ </sect1>
+
+ <sect1>
+ <title>Incompatible API changes with version 6.1</title>
+
+ <itemizedlist>
+
+ <listitem><para>Split off the graphics adapter part of
+ <link linkend="IMachine">IMachine</link> into
+ <link linkend="IGraphicsAdapter">IGraphicsAdapter</link>.
+ This moved 5 attributes.</para>
+ </listitem>
+
+ </itemizedlist>
+
+ </sect1>
+
+ <sect1>
+ <title>Incompatible API changes with version 6.0</title>
+
+ <itemizedlist>
+
+ <listitem><para>Video recording APIs were changed as follows:
+ <itemizedlist>
+ <listitem><para>All attributes which were living in <link linkend="IMachine">IMachine</link> before
+ have been moved to an own, dedicated interface named <link linkend="IRecordingSettings">IRecordingSettings</link>.
+ This new interface can be accessed via the new <link linkend="IMachine__recordingSettings">IMachine::recordingSettings</link>
+ attribute. This should emphasize that recording is not limited to video capturing as such.</para>
+ </listitem>
+
+ <listitem><para>For further flexibility all specific per-VM-screen settings have been moved to a new interface
+ called <link linkend="IRecordingScreenSettings">IRecordingScreenSettings</link>. Such settings now exist per configured
+ VM display and can be retrieved via the <link linkend="IRecordingSettings__screens">IRecordingSettings::screens</link>
+ attribute or the <link linkend="IRecordingSettings__getScreenSettings">IRecordingSettings::getScreenSettings</link>
+ method.
+ <note><para>For now all screen settings will share the same settings, e.g. different settings on a per-screen basis
+ is not implemented yet.</para></note>
+ </para>
+ </listitem>
+
+ <listitem><para>The event <computeroutput>IVideoCaptureChangedEvent</computeroutput> was renamed into
+ <link linkend="IRecordingChangedEvent">IRecordingChangedEvent</link>.</para>
+ </listitem>
+
+ </itemizedlist>
+ </para></listitem>
+
+ <listitem><para>Guest Control APIs were changed as follows:
+ <itemizedlist>
+ <listitem><para><link linkend="IGuest__createSession">IGuest::createSession()</link>,
+ <link linkend="IGuestSession__processCreate">IGuestSession::processCreate()</link>,
+ <link linkend="IGuestSession__processCreateEx">IGuestSession::processCreateEx()</link>,
+ <link linkend="IGuestSession__directoryOpen">IGuestSession::directoryOpen()</link> and
+ <link linkend="IGuestSession__fileOpen">IGuestSession::fileOpen()</link> now will
+ return the new error code VBOX_E_MAXIMUM_REACHED if the limit for the according object
+ group has been reached.</para>
+ </listitem>
+
+ <listitem><para>The enumerations FileOpenExFlags, FsObjMoveFlags and DirectoryCopyFlags have
+ been renamed to <link linkend="FileOpenExFlag">FileOpenExFlag</link>,
+ <link linkend="FsObjMoveFlag">FsObjMoveFlag</link> and <link linkend="DirectoryCopyFlag">DirectoryCopyFlag</link>
+ accordingly to match the rest of the API.</para>
+ </listitem>
+
+ <listitem>
+ <para>The following methods have been implemented:
+ <computeroutput>IGuestSession::directoryCopyFromGuest()</computeroutput> and
+ <computeroutput>IGuestSession::directoryCopyToGuest()</computeroutput>.
+ </para>
+
+ <para>The following attributes have been implemented:
+ <computeroutput>IGuestFsObjInfo::accessTime</computeroutput>,
+ <computeroutput>IGuestFsObjInfo::birthTime</computeroutput>,
+ <computeroutput>IGuestFsObjInfo::changeTime</computeroutput> and
+ <computeroutput>IGuestFsObjInfo::modificationTime</computeroutput>.
+ </para>
+
+ </listitem>
+ </itemizedlist>
+ </para></listitem>
+
+ <listitem><para>The webservice version of the <link linkend="ISharedFolder">ISharedFolder</link>
+ interface was changed from a struct to a managed object. This causes incompatiblities on the
+ protocol level as the shared folder attributes are not returned in the responses of
+ <link linkend="IVirtualBox__sharedFolders">IVirtualBox::getSharedFolders</link> and
+ <link linkend="IMachine__sharedFolders">IMachine::getSharedFolders</link> anymore. They
+ return object UUIDs instead which need be wrapped by stub objects. The change is not visible when
+ using the appropriate client bindings from the most recent VirtualBox SDK.
+ </para></listitem>
+
+ </itemizedlist>
+
+ </sect1>
+
+ <sect1>
+ <title>Incompatible API changes with version 5.x</title>
+
+ <itemizedlist>
+ <listitem><para>ProcessCreateFlag::NoProfile has been renamed to
+ <link linkend="ProcessCreateFlag__Profile">ProcessCreateFlag::Profile</link>,
+ whereas the semantics also has been changed: ProcessCreateFlag::NoProfile
+ explicitly <emphasis role="bold">did not</emphasis> utilize the guest user's profile data,
+ which in turn <link linkend="ProcessCreateFlag__Profile">ProcessCreateFlag::Profile</link>
+ explicitly <emphasis role="bold">does now</emphasis>.</para>
+ </listitem>
+ </itemizedlist>
+
+ </sect1>
+
+ <sect1>
+ <title>Incompatible API changes with version 5.0</title>
+
+ <itemizedlist>
+ <listitem>
+ <para>The methods for saving state, adopting a saved state file,
+ discarding a saved state, taking a snapshot, restoring
+ a snapshot and deleting a snapshot have been moved from
+ <computeroutput>IConsole</computeroutput> to
+ <computeroutput>IMachine</computeroutput>. This straightens out the
+ logical placement of methods and was necessary to resolve a
+ long-standing issue, preventing 32-bit API clients from invoking
+ those operations in the case where no VM is running.
+ <itemizedlist>
+ <listitem><para><link linkend="IMachine__saveState">IMachine::saveState()</link>
+ replaces
+ <computeroutput>IConsole::saveState()</computeroutput></para>
+ </listitem>
+ <listitem>
+ <para><link linkend="IMachine__adoptSavedState">IMachine::adoptSavedState()</link>
+ replaces
+ <computeroutput>IConsole::adoptSavedState()</computeroutput></para>
+ </listitem>
+ <listitem>
+ <para><link linkend="IMachine__discardSavedState">IMachine::discardSavedState()</link>
+ replaces
+ <computeroutput>IConsole::discardSavedState()</computeroutput></para>
+ </listitem>
+ <listitem>
+ <para><link linkend="IMachine__takeSnapshot">IMachine::takeSnapshot()</link>
+ replaces
+ <computeroutput>IConsole::takeSnapshot()</computeroutput></para>
+ </listitem>
+ <listitem>
+ <para><link linkend="IMachine__deleteSnapshot">IMachine::deleteSnapshot()</link>
+ replaces
+ <computeroutput>IConsole::deleteSnapshot()</computeroutput></para>
+ </listitem>
+ <listitem>
+ <para><link linkend="IMachine__deleteSnapshotAndAllChildren">IMachine::deleteSnapshotAndAllChildren()</link>
+ replaces
+ <computeroutput>IConsole::deleteSnapshotAndAllChildren()</computeroutput></para>
+ </listitem>
+ <listitem>
+ <para><link linkend="IMachine__deleteSnapshotRange">IMachine::deleteSnapshotRange()</link>
+ replaces
+ <computeroutput>IConsole::deleteSnapshotRange()</computeroutput></para>
+ </listitem>
+ <listitem>
+ <para><link linkend="IMachine__restoreSnapshot">IMachine::restoreSnapshot()</link>
+ replaces
+ <computeroutput>IConsole::restoreSnapshot()</computeroutput></para>
+ </listitem>
+ </itemizedlist>
+ Small adjustments to the parameter lists have been made to reduce
+ the number of API calls when taking online snapshots (no longer
+ needs explicit pausing), and taking a snapshot also returns now
+ the snapshot id (useful for finding the right snapshot if there
+ are non-unique snapshot names).</para>
+ </listitem>
+
+ <listitem>
+ <para>Two new machine states have been introduced to allow proper
+ distinction between saving state and taking a snapshot.
+ <link linkend="MachineState__Saving">MachineState::Saving</link>
+ now is used exclusively while the VM's state is being saved, without
+ any overlaps with snapshot functionality. The new state
+ <link linkend="MachineState__Snapshotting">MachineState::Snapshotting</link>
+ is used when an offline snapshot is taken and likewise the new state
+ <link linkend="MachineState__OnlineSnapshotting">MachineState::OnlineSnapshotting</link>
+ is used when an online snapshot is taken.</para>
+ </listitem>
+
+ <listitem>
+ <para>A new event has been introduced, which signals when a snapshot
+ has been restored:
+ <link linkend="ISnapshotRestoredEvent">ISnapshotRestoredEvent</link>.
+ Previously the event
+ <link linkend="ISnapshotDeletedEvent">ISnapshotDeletedEvent</link>
+ was signalled, which isn't logical (but could be distinguished from
+ actual deletion by the fact that the snapshot was still
+ there).</para>
+ </listitem>
+
+ <listitem>
+ <para>The method
+ <link linkend="IVirtualBox__createMedium">IVirtualBox::createMedium()</link>
+ replaces
+ <computeroutput>VirtualBox::createHardDisk()</computeroutput>.
+ Adjusting existing code needs adding two parameters with
+ value <computeroutput>AccessMode_ReadWrite</computeroutput>
+ and <computeroutput>DeviceType_HardDisk</computeroutput>
+ respectively. The new method supports creating floppy and
+ DVD images, and (less obviously) further API functionality
+ such as cloning floppy images.</para>
+ </listitem>
+
+ <listitem>
+ <para>The method
+ <link linkend="IMachine__getStorageControllerByInstance">IMachine::getStorageControllerByInstance()</link>
+ now has an additional parameter (first parameter), for specifying the
+ storage bus which the storage controller must be using. The method
+ was not useful before, as the instance numbers are only unique for a
+ specfic storage bus.</para>
+ </listitem>
+
+ <listitem>
+ <para>The attribute
+ <computeroutput>IMachine::sessionType</computeroutput> has been
+ renamed to
+ <link linkend="IMachine__sessionName">IMachine::sessionName()</link>.
+ This cleans up the confusing terminology (as the session type is
+ something different).</para>
+ </listitem>
+
+ <listitem>
+ <para>The attribute
+ <computeroutput>IMachine::guestPropertyNotificationPatterns</computeroutput>
+ has been removed. In practice it was not usable because it is too
+ global and didn't distinguish between API clients.</para>
+ </listitem>
+
+ <listitem><para>Drag and drop APIs were changed as follows:<itemizedlist>
+
+ <listitem>
+ <para>Methods for providing host to guest drag and drop
+ functionality, such as
+ <computeroutput>IGuest::dragHGEnter</computeroutput>,
+ <computeroutput>IGuest::dragHGMove()</computeroutput>,
+ <computeroutput>IGuest::dragHGLeave()</computeroutput>,
+ <computeroutput>IGuest::dragHGDrop()</computeroutput> and
+ <computeroutput>IGuest::dragHGPutData()</computeroutput>,
+ have been moved to an abstract base class called
+ <link linkend="IDnDTarget">IDnDTarget</link>.
+ VirtualBox implements this base class in the
+ <link linkend="IGuestDnDTarget">IGuestDnDTarget</link>
+ interface. The implementation can be used by using the
+ <link linkend="IGuest__dnDTarget">IGuest::dnDTarget()</link>
+ method.</para>
+ <para>Methods for providing guest to host drag and drop
+ functionality, such as
+ <computeroutput>IGuest::dragGHPending()</computeroutput>,
+ <computeroutput>IGuest::dragGHDropped()</computeroutput> and
+ <computeroutput>IGuest::dragGHGetData()</computeroutput>,
+ have been moved to an abstract base class called
+ <link linkend="IDnDSource">IDnDSource</link>.
+ VirtualBox implements this base class in the
+ <link linkend="IGuestDnDSource">IGuestDnDSource</link>
+ interface. The implementation can be used by using the
+ <link linkend="IGuest__dnDSource">IGuest::dnDSource()</link>
+ method.</para>
+ </listitem>
+
+ <listitem>
+ <para>The <computeroutput>DragAndDropAction</computeroutput>
+ enumeration has been renamed to
+ <link linkend="DnDAction">DnDAction</link>.</para>
+ </listitem>
+
+ <listitem>
+ <para>The <computeroutput>DragAndDropMode</computeroutput>
+ enumeration has been renamed to
+ <link linkend="DnDMode">DnDMode</link>.</para>
+ </listitem>
+
+ <listitem>
+ <para>The attribute
+ <computeroutput>IMachine::dragAndDropMode</computeroutput>
+ has been renamed to
+ <link linkend="IMachine__dnDMode">IMachine::dnDMode()</link>.</para>
+ </listitem>
+
+ <listitem>
+ <para>The event
+ <computeroutput>IDragAndDropModeChangedEvent</computeroutput>
+ has been renamed to
+ <link linkend="IDnDModeChangedEvent">IDnDModeChangedEvent</link>.</para>
+ </listitem>
+
+ </itemizedlist></para>
+ </listitem>
+
+ <listitem><para>IDisplay and IFramebuffer interfaces were changed to
+ allow IFramebuffer object to reside in a separate frontend
+ process:<itemizedlist>
+
+ <listitem><para>
+ IDisplay::ResizeCompleted() has been removed, because the
+ IFramebuffer object does not provide the screen memory anymore.
+ </para></listitem>
+
+ <listitem><para>
+ IDisplay::SetFramebuffer() has been replaced with
+ IDisplay::AttachFramebuffer() and IDisplay::DetachFramebuffer().
+ </para></listitem>
+
+ <listitem><para>
+ IDisplay::GetFramebuffer() has been replaced with
+ IDisplay::QueryFramebuffer().
+ </para></listitem>
+
+ <listitem><para>
+ IDisplay::GetScreenResolution() has a new output parameter
+ <computeroutput>guestMonitorStatus</computeroutput>
+ which tells whether the monitor is enabled in the guest.
+ </para></listitem>
+
+ <listitem><para>
+ IDisplay::TakeScreenShot() and IDisplay::TakeScreenShotToArray()
+ have a new parameter
+ <computeroutput>bitmapFormat</computeroutput>. As a consequence of
+ this, IDisplay::TakeScreenShotPNGToArray() has been removed.
+ </para></listitem>
+
+ <listitem><para>
+ IFramebuffer::RequestResize() has been replaced with
+ IFramebuffer::NotifyChange().
+ </para></listitem>
+
+ <listitem><para>
+ IFramebuffer::NotifyUpdateImage() added to support IFramebuffer
+ objects in a different process.
+ </para></listitem>
+
+ <listitem><para>
+ IFramebuffer::Lock(), IFramebuffer::Unlock(),
+ IFramebuffer::Address(), IFramebuffer::UsesGuestVRAM() have been
+ removed because the IFramebuffer object does not provide the screen
+ memory anymore.
+ </para></listitem>
+
+ </itemizedlist></para>
+ </listitem>
+
+ <listitem><para>IGuestSession, IGuestFile and IGuestProcess interfaces
+ were changed as follows:
+ <itemizedlist>
+ <listitem>
+ <para>Replaced IGuestSession::directoryQueryInfo and
+ IGuestSession::fileQueryInfo with a new
+ <link linkend="IGuestSession__fsObjQueryInfo">IGuestSession::fsObjQueryInfo</link>
+ method that works on any type of file system object.</para>
+ </listitem>
+ <listitem>
+ <para>Replaced IGuestSession::fileRemove,
+ IGuestSession::symlinkRemoveDirectory and
+ IGuestSession::symlinkRemoveFile with a new
+ <link linkend="IGuestSession__fsObjRemove">IGuestSession::fsObjRemove</link>
+ method that works on any type of file system object except
+ directories. (fileRemove also worked on any type of object
+ too, though that was not the intent of the method.)</para>
+ </listitem>
+ <listitem>
+ <para>Replaced IGuestSession::directoryRename and
+ IGuestSession::directoryRename with a new
+ <link linkend="IGuestSession__fsObjRename">IGuestSession::fsObjRename</link>
+ method that works on any type of file system object.
+ (directoryRename and fileRename may already have worked for
+ any kind of object, but that was never the intent of the
+ methods.)</para>
+ </listitem>
+ <listitem>
+ <para>Replaced the unimplemented IGuestSession::directorySetACL
+ and IGuestSession::fileSetACL with a new
+ <link linkend="IGuestSession__fsObjSetACL">IGuestSession::fsObjSetACL</link>
+ method that works on all type of file system object. Also
+ added a UNIX-style mode parameter as an alternative to the
+ ACL.</para>
+ </listitem>
+ <listitem>
+ <para>Replaced IGuestSession::fileRemove,
+ IGuestSession::symlinkRemoveDirectory and
+ IGuestSession::symlinkRemoveFile with a new
+ <link linkend="IGuestSession__fsObjRemove">IGuestSession::fsObjRemove</link>
+ method that works on any type of file system object except
+ directories (fileRemove also worked on any type of object,
+ though that was not the intent of the method.)</para>
+ </listitem>
+ <listitem>
+ <para>Renamed IGuestSession::copyTo to
+ <link linkend="IGuestSession__fileCopyToGuest">IGuestSession::fileCopyToGuest</link>.</para>
+ </listitem>
+ <listitem>
+ <para>Renamed IGuestSession::copyFrom to
+ <link linkend="IGuestSession__fileCopyFromGuest">IGuestSession::fileCopyFromGuest</link>.</para>
+ </listitem>
+ <listitem>
+ <para>Renamed the CopyFileFlag enum to
+ <link linkend="FileCopyFlag">FileCopyFlag</link>.</para>
+ </listitem>
+ <listitem>
+ <para>Renamed the IGuestSession::environment attribute to
+ <link linkend="IGuestSession__environmentChanges">IGuestSession::environmentChanges</link>
+ to better reflect what it does.</para>
+ </listitem>
+ <listitem>
+ <para>Changed the
+ <link linkend="IProcess__environment">IGuestProcess::environment</link>
+ to a stub returning E_NOTIMPL since it wasn't doing what was
+ advertised (returned changes, not the actual environment).</para>
+ </listitem>
+ <listitem>
+ <para>Renamed IGuestSession::environmentSet to
+ <link linkend="IGuestSession__environmentScheduleSet">IGuestSession::environmentScheduleSet</link>
+ to better reflect what it does.</para>
+ </listitem>
+ <listitem>
+ <para>Renamed IGuestSession::environmentUnset to
+ <link linkend="IGuestSession__environmentScheduleUnset">IGuestSession::environmentScheduleUnset</link>
+ to better reflect what it does.</para>
+ </listitem>
+ <listitem>
+ <para>Removed IGuestSession::environmentGet it was only getting
+ changes while giving the impression it was actual environment
+ variables, and it did not represent scheduled unset
+ operations.</para>
+ </listitem>
+ <listitem>
+ <para>Removed IGuestSession::environmentClear as it duplicates
+ assigning an empty array to the
+ <link linkend="IGuestSession__environmentChanges">IGuestSession::environmentChanges</link>
+ (formerly known as IGuestSession::environment).</para>
+ </listitem>
+ <listitem>
+ <para>Changed the
+ <link linkend="IGuestSession__processCreate">IGuestSession::processCreate</link>
+ and
+ <link linkend="IGuestSession__processCreateEx">IGuestSession::processCreateEx</link>
+ methods to accept arguments starting with argument zero (argv[0])
+ instead of argument one (argv[1]). (Not yet implemented on the
+ guest additions side, so argv[0] will probably be ignored for a
+ short while.)</para>
+ </listitem>
+
+ <listitem>
+ <para>Added a followSymlink parameter to the following methods:
+ <itemizedlist>
+ <listitem><para><link linkend="IGuestSession__directoryExists">IGuestSession::directoryExists</link></para></listitem>
+ <listitem><para><link linkend="IGuestSession__fileExists">IGuestSession::fileExists</link></para></listitem>
+ <listitem><para><link linkend="IGuestSession__fileQuerySize">IGuestSession::fileQuerySize</link></para></listitem>
+ </itemizedlist></para>
+ </listitem>
+ <listitem>
+ <para>The parameters to the
+ <link linkend="IGuestSession__fileOpen">IGuestSession::fileOpen</link>
+ and
+ <link linkend="IGuestSession__fileOpenEx">IGuestSession::fileOpenEx</link>
+ methods were altered:<itemizedlist>
+ <listitem><para>The openMode string parameter was replaced by
+ the enum
+ <link linkend="FileAccessMode">FileAccessMode</link>
+ and renamed to accessMode.</para></listitem>
+ <listitem><para>The disposition string parameter was replaced
+ by the enum
+ <link linkend="FileOpenAction">FileOpenAction</link>
+ and renamed to openAction.</para></listitem>
+ <listitem><para>The unimplemented sharingMode string parameter
+ was replaced by the enum
+ <link linkend="FileSharingMode">FileSharingMode</link>
+ (fileOpenEx only).</para></listitem>
+ <listitem><para>Added a flags parameter taking a list of
+ <link linkend="FileOpenExFlag">FileOpenExFlag</link> values
+ (fileOpenEx only).</para></listitem>
+ <listitem><para>Removed the offset parameter (fileOpenEx
+ only).</para></listitem>
+ </itemizedlist></para>
+ </listitem>
+
+ <listitem>
+ <para><link linkend="IFile__seek">IGuestFile::seek</link> now
+ returns the new offset.</para>
+ </listitem>
+ <listitem>
+ <para>Renamed the FileSeekType enum used by
+ <link linkend="IFile__seek">IGuestFile::seek</link>
+ to <link linkend="FileSeekOrigin">FileSeekOrigin</link> and
+ added the missing End value and renaming the Set to
+ Begin.</para>
+ </listitem>
+ <listitem>
+ <para>Extended the unimplemented
+ <link linkend="IFile__setACL">IGuestFile::setACL</link>
+ method with a UNIX-style mode parameter as an alternative to
+ the ACL.</para>
+ </listitem>
+ <listitem>
+ <para>Renamed the IFile::openMode attribute to
+ <link linkend="IFile__accessMode">IFile::accessMode</link>
+ and change the type from string to
+ <link linkend="FileAccessMode">FileAccessMode</link> to reflect
+ the changes to the fileOpen methods.</para>
+ </listitem>
+ <listitem>
+ <para>Renamed the IGuestFile::disposition attribute to
+ <link linkend="IFile__openAction">IFile::openAction</link> and
+ change the type from string to
+ <link linkend="FileOpenAction">FileOpenAction</link> to reflect
+ the changes to the fileOpen methods.</para>
+ </listitem>
+
+ <!-- Non-incompatible things worth mentioning (stubbed methods/attrs aren't worth it). -->
+ <listitem>
+ <para>Added
+ <link linkend="IGuestSession__pathStyle">IGuestSession::pathStyle</link>
+ attribute.</para>
+ </listitem>
+ <listitem>
+ <para>Added
+ <link linkend="IGuestSession__fsObjExists">IGuestSession::fsObjExists</link>
+ attribute.</para>
+ </listitem>
+
+ </itemizedlist>
+ </para>
+ </listitem>
+
+ <listitem><para>
+ IConsole::GetDeviceActivity() returns information about multiple
+ devices.
+ </para></listitem>
+
+ <listitem><para>
+ IMachine::ReadSavedThumbnailToArray() has a new parameter
+ <computeroutput>bitmapFormat</computeroutput>. As a consequence of
+ this, IMachine::ReadSavedThumbnailPNGToArray() has been removed.
+ </para></listitem>
+
+ <listitem><para>
+ IMachine::QuerySavedScreenshotPNGSize() has been renamed to
+ IMachine::QuerySavedScreenshotInfo() which also returns
+ an array of available screenshot formats.
+ </para></listitem>
+
+ <listitem><para>
+ IMachine::ReadSavedScreenshotPNGToArray() has been renamed to
+ IMachine::ReadSavedScreenshotToArray() which has a new parameter
+ <computeroutput>bitmapFormat</computeroutput>.
+ </para></listitem>
+
+ <listitem><para>
+ IMachine::QuerySavedThumbnailSize() has been removed.
+ </para></listitem>
+
+ <listitem>
+ <para>The method
+ <link linkend="IWebsessionManager__getSessionObject">IWebsessionManager::getSessionObject()</link>
+ now returns a new <link linkend="ISession">ISession</link> instance
+ for every invocation. This puts the behavior in line with other
+ binding styles, which never forced the equivalent of establishing
+ another connection and logging in again to get another
+ instance.</para>
+ </listitem>
+ </itemizedlist>
+ </sect1>
+
+ <sect1>
+ <title>Incompatible API changes with version 4.3</title>
+
+ <itemizedlist>
+ <listitem>
+ <para>The explicit medium locking methods
+ <link linkend="IMedium__lockRead">IMedium::lockRead()</link>
+ and <link linkend="IMedium__lockWrite">IMedium::lockWrite()</link>
+ have been redesigned. They return a lock token object reference
+ now, and calling the
+ <link linkend="IToken__abandon">IToken::abandon()</link> method (or
+ letting the reference count to this object drop to 0) will unlock
+ it. This eliminates the rather common problem that an API client
+ crash left behind locks, and also improves the safety (API clients
+ can't release locks they didn't obtain).</para>
+ </listitem>
+
+ <listitem>
+ <para>The parameter list of
+ <link linkend="IAppliance__write">IAppliance::write()</link>
+ has been changed slightly, to allow multiple flags to be
+ passed.</para>
+ </listitem>
+
+ <listitem>
+ <para><computeroutput>IMachine::delete</computeroutput>
+ has been renamed to
+ <link linkend="IMachine__deleteConfig">IMachine::deleteConfig()</link>,
+ to improve API client binding compatibility.</para>
+ </listitem>
+
+ <listitem>
+ <para><computeroutput>IMachine::export</computeroutput>
+ has been renamed to
+ <link linkend="IMachine__exportTo">IMachine::exportTo()</link>,
+ to improve API client binding compatibility.</para>
+ </listitem>
+
+ <listitem>
+ <para>For
+ <link linkend="IMachine__launchVMProcess">IMachine::launchVMProcess()</link>
+ the meaning of the <computeroutput>type</computeroutput> parameter
+ has changed slightly. Empty string now means that the per-VM or
+ global default frontend is launched. Most callers of this method
+ should use the empty string now, unless they really want to override
+ the default and launch a particular frontend.</para>
+ </listitem>
+
+ <listitem>
+ <para>Medium management APIs were changed as follows:<itemizedlist>
+
+ <listitem>
+ <para>The type of attribute
+ <link linkend="IMedium__variant">IMedium::variant()</link>
+ changed from <computeroutput>unsigned long</computeroutput>
+ to <computeroutput>safe-array MediumVariant</computeroutput>.
+ It is an array of flags instead of a set of flags which were
+ stored inside one variable.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>The parameter list for
+ <link linkend="IMedium__cloneTo">IMedium::cloneTo()</link>
+ was modified. The type of parameter variant was changed from
+ unsigned long to safe-array MediumVariant.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>The parameter list for
+ <link linkend="IMedium__createBaseStorage">IMedium::createBaseStorage()</link>
+ was modified. The type of parameter variant was changed from
+ unsigned long to safe-array MediumVariant.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>The parameter list for
+ <link linkend="IMedium__createDiffStorage">IMedium::createDiffStorage()</link>
+ was modified. The type of parameter variant was changed from
+ unsigned long to safe-array MediumVariant.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>The parameter list for
+ <link linkend="IMedium__cloneToBase">IMedium::cloneToBase()</link>
+ was modified. The type of parameter variant was changed from
+ unsigned long to safe-array MediumVariant.
+ </para>
+ </listitem>
+ </itemizedlist></para>
+ </listitem>
+
+ <listitem>
+ <para>The type of attribute
+ <link linkend="IMediumFormat__capabilities">IMediumFormat::capabilities()</link>
+ changed from <computeroutput>unsigned long</computeroutput> to
+ <computeroutput>safe-array MediumFormatCapabilities</computeroutput>.
+ It is an array of flags instead of a set of flags which were stored
+ inside one variable.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>The attribute
+ <link linkend="IMedium__logicalSize">IMedium::logicalSize()</link>
+ now returns the logical size of exactly this medium object (whether
+ it is a base or diff image). The old behavior was no longer
+ acceptable, as each image can have a different capacity.</para>
+ </listitem>
+
+ <listitem>
+ <para>Guest control APIs - such as
+ <link linkend="IGuest">IGuest</link>,
+ <link linkend="IGuestSession">IGuestSession</link>,
+ <link linkend="IGuestProcess">IGuestProcess</link> and so on - now
+ emit own events to provide clients much finer control and the ability
+ to write own frontends for guest operations. The event
+ <link linkend="IGuestSessionEvent">IGuestSessionEvent</link> acts as
+ an abstract base class for all guest control events. Certain guest
+ events contain a
+ <link linkend="IVirtualBoxErrorInfo">IVirtualBoxErrorInfo</link>
+ member to provide more information in case of an error happened on
+ the guest side.</para>
+ </listitem>
+
+ <listitem>
+ <para>Guest control sessions on the guest started by
+ <link linkend="IGuest__createSession">IGuest::createSession()</link>
+ now are dedicated guest processes to provide more safety and
+ performance for certain operations. Also, the
+ <link linkend="IGuest__createSession">IGuest::createSession()</link>
+ call does not wait for the guest session being created anymore due
+ to the dedicated guest session processes just mentioned. This also
+ will enable webservice clients to handle guest session creation
+ more gracefully. To wait for a guest session being started, use the
+ newly added attribute
+ <link linkend="IGuestSession__status">IGuestSession::status()</link>
+ to query the current guest session status.</para>
+ </listitem>
+
+ <listitem>
+ <para>The <link linkend="IGuestFile">IGuestFile</link>
+ APIs are now implemented to provide native guest file access from
+ the host.</para>
+ </listitem>
+
+ <listitem>
+ <para>The parameter list for
+ <link linkend="IGuest__updateGuestAdditions">IMedium::updateGuestAdditions()</link>
+ was modified. It now supports specifying optional command line
+ arguments for the Guest Additions installer performing the actual
+ update on the guest.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>A new event
+ <link linkend="IGuestUserStateChangedEvent">IGuestUserStateChangedEvent</link>
+ was introduced to provide guest user status updates to the host via
+ event listeners. To use this event there needs to be at least the 4.3
+ Guest Additions installed on the guest. At the moment only the states
+ "Idle" and "InUse" of the
+ <link linkend="GuestUserState">GuestUserState</link> enumeration arei
+ supported on Windows guests, starting at Windows 2000 SP2.</para>
+ </listitem>
+
+ <listitem>
+ <para>
+ The attribute
+ <link linkend="IGuestSession__protocolVersion">IGuestSession::protocolVersion</link>
+ was added to provide a convenient way to lookup the guest session's
+ protocol version it uses to communicate with the installed Guest
+ Additions on the guest. Older Guest Additions will set the protocol
+ version to 1, whereas Guest Additions 4.3 will set the protocol
+ version to 2. This might change in the future as new features
+ arise.</para>
+ </listitem>
+
+ <listitem>
+ <para><computeroutput>IDisplay::getScreenResolution</computeroutput>
+ has been extended to return the display position in the guest.</para>
+ </listitem>
+
+ <listitem>
+ <para>
+ The <link linkend="IUSBController">IUSBController</link>
+ class is not a singleton of
+ <link linkend="IMachine">IMachine</link> anymore but
+ <link linkend="IMachine">IMachine</link> contains a list of USB
+ controllers present in the VM. The USB device filter handling was
+ moved to
+ <link linkend="IUSBDeviceFilters">IUSBDeviceFilters</link>.
+ </para>
+ </listitem>
+ </itemizedlist>
+ </sect1>
+
+ <sect1>
+ <title>Incompatible API changes with version 4.2</title>
+
+ <itemizedlist>
+ <listitem>
+ <para>Guest control APIs for executing guest processes, working with
+ guest files or directories have been moved to the newly introduced
+ <link linkend="IGuestSession">IGuestSession</link> interface which
+ can be created by calling
+ <link linkend="IGuest__createSession">IGuest::createSession()</link>.</para>
+
+ <para>A guest session will act as a
+ guest user's impersonation so that the guest credentials only have to
+ be provided when creating a new guest session. There can be up to 32
+ guest sessions at once per VM, each session serving up to 2048 guest
+ processes running or files opened.</para>
+
+ <para>Instead of working with process or directory handles before
+ version 4.2, there now are the dedicated interfaces
+ <link linkend="IGuestProcess">IGuestProcess</link>,
+ <link linkend="IGuestDirectory">IGuestDirectory</link> and
+ <link linkend="IGuestFile">IGuestFile</link>. To retrieve more
+ information of a file system object the new interface
+ <link linkend="IGuestFsObjInfo">IGuestFsObjInfo</link> has been
+ introduced.</para>
+
+ <para>Even though the guest control API was changed it is backwards
+ compatible so that it can be used with older installed Guest
+ Additions. However, to use upcoming features like process termination
+ or waiting for input / output new Guest Additions must be installed
+ when these features got implemented.</para>
+
+ <para>The following limitations apply:
+ <itemizedlist>
+ <listitem><para>The <link linkend="IGuestFile">IGuestFile</link>
+ interface is not fully implemented yet.</para>
+ </listitem>
+ <listitem><para>The symbolic link APIs
+ <link linkend="IGuestSession__symlinkCreate">IGuestSession::symlinkCreate()</link>,
+ <link linkend="IGuestSession__symlinkExists">IGuestSession::symlinkExists()</link>,
+ <link linkend="IGuestSession__symlinkRead">IGuestSession::symlinkRead()</link>,
+ IGuestSession::symlinkRemoveDirectory() and
+ IGuestSession::symlinkRemoveFile() are not
+ implemented yet.</para>
+ </listitem>
+ <listitem><para>The directory APIs
+ <link linkend="IGuestSession__directoryRemove">IGuestSession::directoryRemove()</link>,
+ <link linkend="IGuestSession__directoryRemoveRecursive">IGuestSession::directoryRemoveRecursive()</link>,
+ IGuestSession::directoryRename() and
+ IGuestSession::directorySetACL() are not
+ implemented yet.</para>
+ </listitem>
+ <listitem><para>The temporary file creation API
+ <link linkend="IGuestSession__fileCreateTemp">IGuestSession::fileCreateTemp()</link>
+ is not implemented yet.</para>
+ </listitem>
+ <listitem><para>Guest process termination via
+ <link linkend="IProcess__terminate">IProcess::terminate()</link>
+ is not implemented yet.</para>
+ </listitem>
+ <listitem><para>Waiting for guest process output via
+ <link linkend="ProcessWaitForFlag__StdOut">ProcessWaitForFlag::StdOut</link>
+ and
+ <link linkend="ProcessWaitForFlag__StdErr">ProcessWaitForFlag::StdErr</link>
+ is not implemented yet.</para>
+ <para>To wait for process output,
+ <link linkend="IProcess__read">IProcess::read()</link> with
+ appropriate flags still can be used to periodically check for
+ new output data to arrive. Note that
+ <link linkend="ProcessCreateFlag__WaitForStdOut">ProcessCreateFlag::WaitForStdOut</link>
+ and / or
+ <link linkend="ProcessCreateFlag__WaitForStdErr">ProcessCreateFlag::WaitForStdErr</link>
+ need to be specified when creating a guest process via
+ <link linkend="IGuestSession__processCreate">IGuestSession::processCreate()</link>
+ or
+ <link linkend="IGuestSession__processCreateEx">IGuestSession::processCreateEx()</link>.</para>
+ </listitem>
+ <listitem>
+ <para>ACL (Access Control List) handling in general is not
+ implemented yet.</para>
+ </listitem>
+ </itemizedlist>
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>The <link linkend="LockType">LockType</link>
+ enumeration now has an additional value
+ <computeroutput>VM</computeroutput> which tells
+ <link linkend="IMachine__lockMachine">IMachine::lockMachine()</link>
+ to create a full-blown object structure for running a VM. This was
+ the previous behavior with <computeroutput>Write</computeroutput>,
+ which now only creates the minimal object structure to save time and
+ resources (at the moment the Console object is still created, but all
+ sub-objects such as Display, Keyboard, Mouse, Guest are not.</para>
+ </listitem>
+
+ <listitem>
+ <para>Machines can be put in groups (actually an array of groups).
+ The primary group affects the default placement of files belonging
+ to a VM.
+ <link linkend="IVirtualBox__createMachine">IVirtualBox::createMachine()</link>
+ and
+ <link linkend="IVirtualBox__composeMachineFilename">IVirtualBox::composeMachineFilename()</link>
+ have been adjusted accordingly, the former taking an array of groups
+ as an additional parameter and the latter taking a group as an
+ additional parameter. The create option handling has been changed for
+ those two methods, too.</para>
+ </listitem>
+
+ <listitem>
+ <para>The method IVirtualBox::findMedium() has been removed, since
+ it provides a subset of the functionality of
+ <link linkend="IVirtualBox__openMedium">IVirtualBox::openMedium()</link>.</para>
+ </listitem>
+
+ <listitem>
+ <para>The use of acronyms in API enumeration, interface, attribute
+ and method names has been made much more consistent, previously they
+ sometimes were lowercase and sometimes mixed case. They are now
+ consistently all caps:<table>
+ <title>Renamed identifiers in VirtualBox 4.2</title>
+
+ <tgroup cols="2" style="verywide">
+ <tbody>
+ <row>
+ <entry><emphasis role="bold">Old name</emphasis></entry>
+
+ <entry><emphasis role="bold">New name</emphasis></entry>
+ </row>
+ <row>
+ <entry>PointingHidType</entry>
+ <entry><link linkend="PointingHIDType">PointingHIDType</link></entry>
+ </row>
+ <row>
+ <entry>KeyboardHidType</entry>
+ <entry><link linkend="KeyboardHIDType">KeyboardHIDType</link></entry>
+ </row>
+ <row>
+ <entry>IPciAddress</entry>
+ <entry><link linkend="IPCIAddress">IPCIAddress</link></entry>
+ </row>
+ <row>
+ <entry>IPciDeviceAttachment</entry>
+ <entry><link linkend="IPCIDeviceAttachment">IPCIDeviceAttachment</link></entry>
+ </row>
+ <row>
+ <entry>IMachine::pointingHidType</entry>
+ <entry><link linkend="IMachine__pointingHIDType">IMachine::pointingHIDType</link></entry>
+ </row>
+ <row>
+ <entry>IMachine::keyboardHidType</entry>
+ <entry><link linkend="IMachine__keyboardHIDType">IMachine::keyboardHIDType</link></entry>
+ </row>
+ <row>
+ <entry>IMachine::hpetEnabled</entry>
+ <entry><link linkend="IMachine__HPETEnabled">IMachine::HPETEnabled</link></entry>
+ </row>
+ <row>
+ <entry>IMachine::sessionPid</entry>
+ <entry><link linkend="IMachine__sessionPID">IMachine::sessionPID</link></entry>
+ </row>
+ <row>
+ <entry>IMachine::ioCacheEnabled</entry>
+ <entry><link linkend="IMachine__IOCacheEnabled">IMachine::IOCacheEnabled</link></entry>
+ </row>
+ <row>
+ <entry>IMachine::ioCacheSize</entry>
+ <entry><link linkend="IMachine__IOCacheSize">IMachine::IOCacheSize</link></entry>
+ </row>
+ <row>
+ <entry>IMachine::pciDeviceAssignments</entry>
+ <entry><link linkend="IMachine__PCIDeviceAssignments">IMachine::PCIDeviceAssignments</link></entry>
+ </row>
+ <row>
+ <entry>IMachine::attachHostPciDevice()</entry>
+ <entry><link linkend="IMachine__attachHostPCIDevice">IMachine::attachHostPCIDevice</link></entry>
+ </row>
+ <row>
+ <entry>IMachine::detachHostPciDevice()</entry>
+ <entry><link linkend="IMachine__detachHostPCIDevice">IMachine::detachHostPCIDevice()</link></entry>
+ </row>
+ <row>
+ <entry>IConsole::attachedPciDevices</entry>
+ <entry><link linkend="IConsole__attachedPCIDevices">IConsole::attachedPCIDevices</link></entry>
+ </row>
+ <row>
+ <entry>IHostNetworkInterface::dhcpEnabled</entry>
+ <entry><link linkend="IHostNetworkInterface__DHCPEnabled">IHostNetworkInterface::DHCPEnabled</link></entry>
+ </row>
+ <row>
+ <entry>IHostNetworkInterface::enableStaticIpConfig()</entry>
+ <entry><link linkend="IHostNetworkInterface__enableStaticIPConfig">IHostNetworkInterface::enableStaticIPConfig()</link></entry>
+ </row>
+ <row>
+ <entry>IHostNetworkInterface::enableStaticIpConfigV6()</entry>
+ <entry><link linkend="IHostNetworkInterface__enableStaticIPConfigV6">IHostNetworkInterface::enableStaticIPConfigV6()</link></entry>
+ </row>
+ <row>
+ <entry>IHostNetworkInterface::enableDynamicIpConfig()</entry>
+ <entry><link linkend="IHostNetworkInterface__enableDynamicIPConfig">IHostNetworkInterface::enableDynamicIPConfig()</link></entry>
+ </row>
+ <row>
+ <entry>IHostNetworkInterface::dhcpRediscover()</entry>
+ <entry><link linkend="IHostNetworkInterface__DHCPRediscover">IHostNetworkInterface::DHCPRediscover()</link></entry>
+ </row>
+ <row>
+ <entry>IHost::Acceleration3DAvailable</entry>
+ <entry><link linkend="IHost__acceleration3DAvailable">IHost::acceleration3DAvailable</link></entry>
+ </row>
+ <row>
+ <entry>IGuestOSType::recommendedPae</entry>
+ <entry><link linkend="IGuestOSType__recommendedPAE">IGuestOSType::recommendedPAE</link></entry>
+ </row>
+ <row>
+ <entry>IGuestOSType::recommendedDvdStorageController</entry>
+ <entry><link linkend="IGuestOSType__recommendedDVDStorageController">IGuestOSType::recommendedDVDStorageController</link></entry>
+ </row>
+ <row>
+ <entry>IGuestOSType::recommendedDvdStorageBus</entry>
+ <entry><link linkend="IGuestOSType__recommendedDVDStorageBus">IGuestOSType::recommendedDVDStorageBus</link></entry>
+ </row>
+ <row>
+ <entry>IGuestOSType::recommendedHdStorageController</entry>
+ <entry><link linkend="IGuestOSType__recommendedHDStorageController">IGuestOSType::recommendedHDStorageController</link></entry>
+ </row>
+ <row>
+ <entry>IGuestOSType::recommendedHdStorageBus</entry>
+ <entry><link linkend="IGuestOSType__recommendedHDStorageBus">IGuestOSType::recommendedHDStorageBus</link></entry>
+ </row>
+ <row>
+ <entry>IGuestOSType::recommendedUsbHid</entry>
+ <entry><link linkend="IGuestOSType__recommendedUSBHID">IGuestOSType::recommendedUSBHID</link></entry>
+ </row>
+ <row>
+ <entry>IGuestOSType::recommendedHpet</entry>
+ <entry><link linkend="IGuestOSType__recommendedHPET">IGuestOSType::recommendedHPET</link></entry>
+ </row>
+ <row>
+ <entry>IGuestOSType::recommendedUsbTablet</entry>
+ <entry><link linkend="IGuestOSType__recommendedUSBTablet">IGuestOSType::recommendedUSBTablet</link></entry>
+ </row>
+ <row>
+ <entry>IGuestOSType::recommendedRtcUseUtc</entry>
+ <entry><link linkend="IGuestOSType__recommendedRTCUseUTC">IGuestOSType::recommendedRTCUseUTC</link></entry>
+ </row>
+ <row>
+ <entry>IGuestOSType::recommendedUsb</entry>
+ <entry><link linkend="IGuestOSType__recommendedUSB">IGuestOSType::recommendedUSB</link></entry>
+ </row>
+ <row>
+ <entry>INetworkAdapter::natDriver</entry>
+ <entry><link linkend="INetworkAdapter__NATEngine">INetworkAdapter::NATEngine</link></entry>
+ </row>
+ <row>
+ <entry>IUSBController::enabledEhci</entry>
+ <entry>IUSBController::enabledEHCI"</entry>
+ </row>
+ <row>
+ <entry>INATEngine::tftpPrefix</entry>
+ <entry><link linkend="INATEngine__TFTPPrefix">INATEngine::TFTPPrefix</link></entry>
+ </row>
+ <row>
+ <entry>INATEngine::tftpBootFile</entry>
+ <entry><link linkend="INATEngine__TFTPBootFile">INATEngine::TFTPBootFile</link></entry>
+ </row>
+ <row>
+ <entry>INATEngine::tftpNextServer</entry>
+ <entry><link linkend="INATEngine__TFTPNextServer">INATEngine::TFTPNextServer</link></entry>
+ </row>
+ <row>
+ <entry>INATEngine::dnsPassDomain</entry>
+ <entry><link linkend="INATEngine__DNSPassDomain">INATEngine::DNSPassDomain</link></entry>
+ </row>
+ <row>
+ <entry>INATEngine::dnsProxy</entry>
+ <entry><link linkend="INATEngine__DNSProxy">INATEngine::DNSProxy</link></entry>
+ </row>
+ <row>
+ <entry>INATEngine::dnsUseHostResolver</entry>
+ <entry><link linkend="INATEngine__DNSUseHostResolver">INATEngine::DNSUseHostResolver</link></entry>
+ </row>
+ <row>
+ <entry>VBoxEventType::OnHostPciDevicePlug</entry>
+ <entry><link linkend="VBoxEventType__OnHostPCIDevicePlug">VBoxEventType::OnHostPCIDevicePlug</link></entry>
+ </row>
+ <row>
+ <entry>ICPUChangedEvent::cpu</entry>
+ <entry><link linkend="ICPUChangedEvent__CPU">ICPUChangedEvent::CPU</link></entry>
+ </row>
+ <row>
+ <entry>INATRedirectEvent::hostIp</entry>
+ <entry><link linkend="INATRedirectEvent__hostIP">INATRedirectEvent::hostIP</link></entry>
+ </row>
+ <row>
+ <entry>INATRedirectEvent::guestIp</entry>
+ <entry><link linkend="INATRedirectEvent__guestIP">INATRedirectEvent::guestIP</link></entry>
+ </row>
+ <row>
+ <entry>IHostPciDevicePlugEvent</entry>
+ <entry><link linkend="IHostPCIDevicePlugEvent">IHostPCIDevicePlugEvent</link></entry>
+ </row>
+ </tbody>
+ </tgroup></table></para>
+ </listitem>
+ </itemizedlist>
+ </sect1>
+
+ <sect1>
+ <title>Incompatible API changes with version 4.1</title>
+
+ <itemizedlist>
+ <listitem>
+ <para>The method
+ <link linkend="IAppliance__importMachines">IAppliance::importMachines()</link>
+ has one more parameter now, which allows to configure the import
+ process in more detail.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>The method
+ <link linkend="IVirtualBox__openMedium">IVirtualBox::openMedium()</link>
+ has one more parameter now, which allows resolving duplicate medium
+ UUIDs without the need for external tools.</para>
+ </listitem>
+
+ <listitem>
+ <para>The <link linkend="INetworkAdapter">INetworkAdapter</link>
+ interface has been cleaned up. The various methods to activate an
+ attachment type have been replaced by the
+ <link linkend="INetworkAdapter__attachmentType">INetworkAdapter::attachmentType</link>
+ setter.</para>
+ <para>Additionally each attachment mode now has its own attribute,
+ which means that host only networks no longer share the settings with
+ bridged interfaces.</para>
+ <para>To allow introducing new network attachment implementations
+ without making API changes, the concept of a generic network
+ attachment driver has been introduced, which is configurable through
+ key/value properties.</para>
+ </listitem>
+
+ <listitem>
+ <para>This version introduces the guest facilities concept. A guest
+ facility either represents a module or feature the guest is running
+ or offering, which is defined by
+ <link linkend="AdditionsFacilityType">AdditionsFacilityType</link>.
+ Each facility is member of a
+ <link linkend="AdditionsFacilityClass">AdditionsFacilityClass</link>
+ and has a current status indicated by
+ <link linkend="AdditionsFacilityStatus">AdditionsFacilityStatus</link>,
+ together with a timestamp (in ms) of the last status update.</para>
+ <para>To address the above concept, the following changes were made:
+ <itemizedlist>
+ <listitem>
+ <para>
+ In the <link linkend="IGuest">IGuest</link> interface, the
+ following were removed:
+ <itemizedlist>
+ <listitem>
+ <para>the
+ <computeroutput>supportsSeamless</computeroutput>
+ attribute;</para>
+ </listitem>
+ <listitem>
+ <para>the
+ <computeroutput>supportsGraphics</computeroutput>
+ attribute;</para>
+ </listitem>
+ </itemizedlist>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ The function
+ <link linkend="IGuest__getFacilityStatus">IGuest::getFacilityStatus()</link>
+ was added. It quickly provides a facility's status without
+ the need to get the facility collection with
+ <link linkend="IGuest__facilities">IGuest::facilities</link>.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ The attribute
+ <link linkend="IGuest__facilities">IGuest::facilities</link>
+ was added to provide an easy to access collection of all
+ currently known guest facilities, that is, it contains all
+ facilies where at least one status update was made since the
+ guest was started.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ The interface
+ <link linkend="IAdditionsFacility">IAdditionsFacility</link>
+ was added to represent a single facility returned by
+ <link linkend="IGuest__facilities">IGuest::facilities</link>.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <link linkend="AdditionsFacilityStatus">AdditionsFacilityStatus</link>
+ was added to represent a facility's overall status.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <link linkend="AdditionsFacilityType">AdditionsFacilityType</link> and
+ <link linkend="AdditionsFacilityClass">AdditionsFacilityClass</link> were
+ added to represent the facility's type and class.
+ </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+ </listitem>
+ </itemizedlist>
+ </sect1>
+
+ <sect1>
+ <title>Incompatible API changes with version 4.0</title>
+
+ <itemizedlist>
+ <listitem>
+ <para>A new Java glue layer replacing the previous OOWS JAX-WS
+ bindings was introduced. The new library allows for uniform code
+ targeting both local (COM/XPCOM) and remote (SOAP) transports. Now,
+ instead of <computeroutput>IWebsessionManager</computeroutput>, the
+ new class <computeroutput>VirtualBoxManager</computeroutput> must be
+ used. See <xref linkend="javaapi"/> for details.</para>
+ </listitem>
+
+ <listitem>
+ <para>The confusingly named and impractical session APIs were
+ changed. In existing client code, the following changes need to be
+ made:<itemizedlist>
+ <listitem>
+ <para>Replace any
+ <computeroutput>IVirtualBox::openSession(uuidMachine,
+ ...)</computeroutput> API call with the machine's
+ <link linkend="IMachine__lockMachine">IMachine::lockMachine()</link>
+ call and a
+ <computeroutput>LockType.Write</computeroutput> argument. The
+ functionality is unchanged, but instead of "opening a direct
+ session on a machine" all documentation now refers to
+ "obtaining a write lock on a machine for the client
+ session".</para>
+ </listitem>
+
+ <listitem>
+ <para>Similarly, replace any
+ <computeroutput>IVirtualBox::openExistingSession(uuidMachine,
+ ...)</computeroutput> call with the machine's
+ <link linkend="IMachine__lockMachine">IMachine::lockMachine()</link>
+ call and a <computeroutput>LockType.Shared</computeroutput>
+ argument. Whereas it was previously impossible to connect a
+ client session to a running VM process in a race-free manner,
+ the new API will atomically either write-lock the machine for
+ the current session or establish a remote link to an existing
+ session. Existing client code which tried calling both
+ <computeroutput>openSession()</computeroutput> and
+ <computeroutput>openExistingSession()</computeroutput> can now
+ use this one call instead.</para>
+ </listitem>
+
+ <listitem>
+ <para>Third, replace any
+ <computeroutput>IVirtualBox::openRemoteSession(uuidMachine,
+ ...)</computeroutput> call with the machine's
+ <link linkend="IMachine__launchVMProcess">IMachine::launchVMProcess()</link>
+ call. The functionality is unchanged.</para>
+ </listitem>
+
+ <listitem>
+ <para>The <link linkend="SessionState">SessionState</link> enum
+ was adjusted accordingly: "Open" is now "Locked", "Closed" is
+ now "Unlocked", "Closing" is now "Unlocking".</para>
+ </listitem>
+ </itemizedlist></para>
+ </listitem>
+
+ <listitem>
+ <para>Virtual machines created with VirtualBox 4.0 or later no
+ longer register their media in the global media registry in the
+ <computeroutput>VirtualBox.xml</computeroutput> file. Instead, such
+ machines list all their media in their own machine XML files. As a
+ result, a number of media-related APIs had to be modified again.
+ <itemizedlist>
+ <listitem>
+ <para>Neither
+ <computeroutput>IVirtualBox::createHardDisk()</computeroutput>
+ nor
+ <link linkend="IVirtualBox__openMedium">IVirtualBox::openMedium()</link>
+ register media automatically any more.</para>
+ </listitem>
+
+ <listitem>
+ <para><link linkend="IMachine__attachDevice">IMachine::attachDevice()</link>
+ and
+ <link linkend="IMachine__mountMedium">IMachine::mountMedium()</link>
+ now take an IMedium object instead of a UUID as an argument. It
+ is these two calls which add media to a registry now (either a
+ machine registry for machines created with VirtualBox 4.0 or
+ later or the global registry otherwise). As a consequence, if a
+ medium is opened but never attached to a machine, it is no
+ longer added to any registry any more.</para>
+ </listitem>
+
+ <listitem>
+ <para>To reduce code duplication, the APIs
+ IVirtualBox::findHardDisk(), getHardDisk(), findDVDImage(),
+ getDVDImage(), findFloppyImage() and getFloppyImage() have all
+ been merged into IVirtualBox::findMedium(), and
+ IVirtualBox::openHardDisk(), openDVDImage() and
+ openFloppyImage() have all been merged into
+ <link linkend="IVirtualBox__openMedium">IVirtualBox::openMedium()</link>.</para>
+ </listitem>
+
+ <listitem>
+ <para>The rare use case of changing the UUID and parent UUID
+ of a medium previously handled by
+ <computeroutput>openHardDisk()</computeroutput> is now in a
+ separate IMedium::setIDs method.</para>
+ </listitem>
+
+ <listitem>
+ <para><computeroutput>ISystemProperties::get/setDefaultHardDiskFolder()</computeroutput>
+ have been removed since disk images are now by default placed
+ in each machine's folder.</para>
+ </listitem>
+
+ <listitem>
+ <para>The
+ <link linkend="ISystemProperties__infoVDSize">ISystemProperties::infoVDSize</link>
+ attribute replaces the
+ <computeroutput>getMaxVDISize()</computeroutput>
+ API call; this now uses bytes instead of megabytes.</para>
+ </listitem>
+ </itemizedlist></para>
+ </listitem>
+
+ <listitem>
+ <para>Machine management APIs were enhanced as follows:<itemizedlist>
+ <listitem>
+ <para><link linkend="IVirtualBox__createMachine">IVirtualBox::createMachine()</link>
+ is no longer restricted to creating machines in the default
+ "Machines" folder, but can now create machines at arbitrary
+ locations. For this to work, the parameter list had to be
+ changed.</para>
+ </listitem>
+
+ <listitem>
+ <para>The long-deprecated
+ <computeroutput>IVirtualBox::createLegacyMachine()</computeroutput>
+ API has been removed.</para>
+ </listitem>
+
+ <listitem>
+ <para>To reduce code duplication and for consistency with the
+ aforementioned media APIs,
+ <computeroutput>IVirtualBox::getMachine()</computeroutput> has
+ been merged with
+ <link linkend="IVirtualBox__findMachine">IVirtualBox::findMachine()</link>,
+ and
+ <computeroutput>IMachine::getSnapshot()</computeroutput> has
+ been merged with
+ <link linkend="IMachine__findSnapshot">IMachine::findSnapshot()</link>.</para>
+ </listitem>
+
+ <listitem>
+ <para><computeroutput>IVirtualBox::unregisterMachine()</computeroutput>
+ was replaced with
+ <link linkend="IMachine__unregister">IMachine::unregister()</link>
+ with additional functionality for cleaning up machine
+ files.</para>
+ </listitem>
+
+ <listitem>
+ <para><computeroutput>IMachine::deleteSettings</computeroutput>
+ has been replaced by IMachine::delete, which allows specifying
+ which disk images are to be deleted as part of the deletion,
+ and because it can take a while it also returns a
+ <computeroutput>IProgress</computeroutput> object reference,
+ so that the completion of the asynchronous activities can be
+ monitored.</para>
+ </listitem>
+
+ <listitem>
+ <para><computeroutput>IConsole::forgetSavedState</computeroutput>
+ has been renamed to
+ <computeroutput>IConsole::discardSavedState()</computeroutput>.</para>
+ </listitem>
+ </itemizedlist></para>
+ </listitem>
+
+ <listitem>
+ <para>All event callbacks APIs were replaced with a new, generic
+ event mechanism that can be used both locally (COM, XPCOM) and
+ remotely (web services). Also, the new mechanism is usable from
+ scripting languages and a local Java. See
+ <link linkend="IEvent">events</link> for details. The new concept
+ will require changes to all clients that used event callbacks.</para>
+ </listitem>
+
+ <listitem>
+ <para><computeroutput>additionsActive()</computeroutput> was replaced
+ with
+ <link linkend="IGuest__additionsRunLevel">additionsRunLevel()</link>
+ and
+ <link linkend="IGuest__getAdditionsStatus">getAdditionsStatus()</link>
+ in order to support a more detailed status of the current Guest
+ Additions loading/readiness state.
+ <link linkend="IGuest__additionsVersion">IGuest::additionsVersion()</link>
+ no longer returns the Guest Additions interface version but the
+ installed Guest Additions version and revision in form of
+ <computeroutput>3.3.0r12345</computeroutput>.</para>
+ </listitem>
+
+ <listitem>
+ <para>To address shared folders auto-mounting support, the following
+ APIs were extended to require an additional
+ <computeroutput>automount</computeroutput> parameter: <itemizedlist>
+ <listitem>
+ <para><link linkend="IVirtualBox__createSharedFolder">IVirtualBox::createSharedFolder()</link></para>
+ </listitem>
+
+ <listitem>
+ <para><link linkend="IMachine__createSharedFolder">IMachine::createSharedFolder()</link></para>
+ </listitem>
+
+ <listitem>
+ <para><link linkend="IConsole__createSharedFolder">IConsole::createSharedFolder()</link></para>
+ </listitem>
+ </itemizedlist> Also, a new property named
+ <computeroutput>autoMount</computeroutput> was added to the
+ <link linkend="ISharedFolder">ISharedFolder</link>
+ interface.</para>
+ </listitem>
+
+ <listitem>
+ <para>The appliance (OVF) APIs were enhanced as
+ follows:<itemizedlist>
+ <listitem>
+ <para><computeroutput>IMachine::export</computeroutput>
+ received an extra parameter
+ <computeroutput>location</computeroutput>, which is used to
+ decide for the disk naming.</para>
+ </listitem>
+
+ <listitem>
+ <para><link linkend="IAppliance__write">IAppliance::write()</link>
+ received an extra parameter
+ <computeroutput>manifest</computeroutput>, which can suppress
+ creating the manifest file on export.</para>
+ </listitem>
+
+ <listitem>
+ <para><link linkend="IVFSExplorer__entryList">IVFSExplorer::entryList()</link>
+ received two extra parameters
+ <computeroutput>sizes</computeroutput> and
+ <computeroutput>modes</computeroutput>, which contains the
+ sizes (in bytes) and the file access modes (in octal form) of
+ the returned files.</para>
+ </listitem>
+ </itemizedlist></para>
+ </listitem>
+
+ <listitem>
+ <para>Support for remote desktop access to virtual machines has been
+ cleaned up to allow third party implementations of the remote
+ desktop server. This is called the VirtualBox Remote Desktop
+ Extension (VRDE) and can be added to VirtualBox by installing the
+ corresponding extension package; see the VirtualBox User Manual for
+ details.</para>
+
+ <para>The following API changes were made to support the VRDE
+ interface: <itemizedlist>
+ <listitem>
+ <para><computeroutput>IVRDPServer</computeroutput> has been
+ renamed to
+ <link linkend="IVRDEServer">IVRDEServer</link>.</para>
+ </listitem>
+
+ <listitem>
+ <para><computeroutput>IRemoteDisplayInfo</computeroutput> has
+ been renamed to
+ <link linkend="IVRDEServerInfo">IVRDEServerInfo</link>.</para>
+ </listitem>
+
+ <listitem>
+ <para><link linkend="IMachine__VRDEServer">IMachine::VRDEServer</link>
+ replaces
+ <computeroutput>VRDPServer.</computeroutput></para>
+ </listitem>
+
+ <listitem>
+ <para><link linkend="IConsole__VRDEServerInfo">IConsole::VRDEServerInfo</link>
+ replaces
+ <computeroutput>RemoteDisplayInfo</computeroutput>.</para>
+ </listitem>
+
+ <listitem>
+ <para><link linkend="ISystemProperties__VRDEAuthLibrary">ISystemProperties::VRDEAuthLibrary</link>
+ replaces
+ <computeroutput>RemoteDisplayAuthLibrary</computeroutput>.</para>
+ </listitem>
+
+ <listitem>
+ <para>The following methods have been implemented in
+ <computeroutput>IVRDEServer</computeroutput> to support
+ generic VRDE properties: <itemizedlist>
+ <listitem>
+ <para><link linkend="IVRDEServer__setVRDEProperty">IVRDEServer::setVRDEProperty</link></para>
+ </listitem>
+
+ <listitem>
+ <para><link linkend="IVRDEServer__getVRDEProperty">IVRDEServer::getVRDEProperty</link></para>
+ </listitem>
+
+ <listitem>
+ <para><link linkend="IVRDEServer__VRDEProperties">IVRDEServer::VRDEProperties</link></para>
+ </listitem>
+ </itemizedlist></para>
+
+ <para>A few implementation-specific attributes of the old
+ <computeroutput>IVRDPServer</computeroutput> interface have
+ been removed and replaced with properties: <itemizedlist>
+ <listitem>
+ <para><computeroutput>IVRDPServer::Ports</computeroutput>
+ has been replaced with the
+ <computeroutput>"TCP/Ports"</computeroutput> property.
+ The property value is a string, which contains a
+ comma-separated list of ports or ranges of ports. Use a
+ dash between two port numbers to specify a range.
+ Example:
+ <computeroutput>"5000,5010-5012"</computeroutput></para>
+ </listitem>
+
+ <listitem>
+ <para><computeroutput>IVRDPServer::NetAddress</computeroutput>
+ has been replaced with the
+ <computeroutput>"TCP/Address"</computeroutput> property.
+ The property value is an IP address string. Example:
+ <computeroutput>"127.0.0.1"</computeroutput></para>
+ </listitem>
+
+ <listitem>
+ <para><computeroutput>IVRDPServer::VideoChannel</computeroutput>
+ has been replaced with the
+ <computeroutput>"VideoChannel/Enabled"</computeroutput>
+ property. The property value is either
+ <computeroutput>"true"</computeroutput> or
+ <computeroutput>"false"</computeroutput></para>
+ </listitem>
+
+ <listitem>
+ <para><computeroutput>IVRDPServer::VideoChannelQuality</computeroutput>
+ has been replaced with the
+ <computeroutput>"VideoChannel/Quality"</computeroutput>
+ property. The property value is a string which contain a
+ decimal number in range 10..100. Invalid values are
+ ignored and the quality is set to the default value 75.
+ Example: <computeroutput>"50"</computeroutput></para>
+ </listitem>
+ </itemizedlist></para>
+ </listitem>
+ </itemizedlist></para>
+ </listitem>
+
+ <listitem>
+ <para>The VirtualBox external authentication module interface has
+ been updated and made more generic. Because of that,
+ <computeroutput>VRDPAuthType</computeroutput> enumeration has been
+ renamed to <link linkend="AuthType">AuthType</link>.</para>
+ </listitem>
+ </itemizedlist>
+ </sect1>
+
+ <sect1>
+ <title>Incompatible API changes with version 3.2</title>
+
+ <itemizedlist>
+ <listitem>
+ <para>The following interfaces were renamed for consistency:
+ <itemizedlist>
+ <listitem>
+ <para>IMachine::getCpuProperty() is now
+ <link linkend="IMachine__getCPUProperty">IMachine::getCPUProperty()</link>;</para>
+ </listitem>
+
+ <listitem>
+ <para>IMachine::setCpuProperty() is now
+ <link linkend="IMachine__setCPUProperty">IMachine::setCPUProperty()</link>;</para>
+ </listitem>
+
+ <listitem>
+ <para>IMachine::getCpuIdLeaf() is now
+ <link linkend="IMachine__getCPUIDLeaf">IMachine::getCPUIDLeaf()</link>;</para>
+ </listitem>
+
+ <listitem>
+ <para>IMachine::setCpuIdLeaf() is now
+ <link linkend="IMachine__setCPUIDLeaf">IMachine::setCPUIDLeaf()</link>;</para>
+ </listitem>
+
+ <listitem>
+ <para>IMachine::removeCpuIdLeaf() is now
+ <link linkend="IMachine__removeCPUIDLeaf">IMachine::removeCPUIDLeaf()</link>;</para>
+ </listitem>
+
+ <listitem>
+ <para>IMachine::removeAllCpuIdLeafs() is now
+ <link linkend="IMachine__removeAllCPUIDLeaves">IMachine::removeAllCPUIDLeaves()</link>;</para>
+ </listitem>
+
+ <listitem>
+ <para>the CpuPropertyType enum is now
+ <link linkend="CPUPropertyType">CPUPropertyType</link>.</para>
+ </listitem>
+
+ <listitem>
+ <para>IVirtualBoxCallback::onSnapshotDiscarded() is now
+ IVirtualBoxCallback::onSnapshotDeleted.</para>
+ </listitem>
+ </itemizedlist></para>
+ </listitem>
+
+ <listitem>
+ <para>When creating a VM configuration with
+ <link linkend="IVirtualBox__createMachine">IVirtualBox::createMachine()</link>
+ it is now possible to ignore existing configuration files which would
+ previously have caused a failure. For this the
+ <computeroutput>override</computeroutput> parameter was added.</para>
+ </listitem>
+
+ <listitem>
+ <para>Deleting snapshots via
+ <computeroutput>IConsole::deleteSnapshot()</computeroutput> is now
+ possible while the associated VM is running in almost all cases.
+ The API is unchanged, but client code that verifies machine states
+ to determine whether snapshots can be deleted may need to be
+ adjusted.</para>
+ </listitem>
+
+ <listitem>
+ <para>The IoBackendType enumeration was replaced with a boolean flag
+ (see
+ <link linkend="IStorageController__useHostIOCache">IStorageController::useHostIOCache</link>).</para>
+ </listitem>
+
+ <listitem>
+ <para>To address multi-monitor support, the following APIs were
+ extended to require an additional
+ <computeroutput>screenId</computeroutput> parameter: <itemizedlist>
+ <listitem>
+ <para>IMachine::querySavedThumbnailSize()</para>
+ </listitem>
+
+ <listitem>
+ <para><link linkend="IMachine__readSavedThumbnailToArray">IMachine::readSavedThumbnailToArray()</link></para>
+ </listitem>
+
+ <listitem>
+ <para><link linkend="IMachine__querySavedScreenshotInfo">IMachine::querySavedScreenshotPNGSize()</link></para>
+ </listitem>
+
+ <listitem>
+ <para><link linkend="IMachine__readSavedScreenshotToArray">IMachine::readSavedScreenshotPNGToArray()</link></para>
+ </listitem>
+ </itemizedlist></para>
+ </listitem>
+
+ <listitem>
+ <para>The <computeroutput>shape</computeroutput> parameter of
+ IConsoleCallback::onMousePointerShapeChange was changed from a
+ implementation-specific pointer to a safearray, enabling scripting
+ languages to process pointer shapes.</para>
+ </listitem>
+ </itemizedlist>
+ </sect1>
+
+ <sect1>
+ <title>Incompatible API changes with version 3.1</title>
+
+ <itemizedlist>
+ <listitem>
+ <para>Due to the new flexibility in medium attachments that was
+ introduced with version 3.1 (in particular, full flexibility with
+ attaching CD/DVD drives to arbitrary controllers), we seized the
+ opportunity to rework all interfaces dealing with storage media to
+ make the API more flexible as well as logical. The
+ <link linkend="IStorageController">IStorageController</link>,
+ <link linkend="IMedium">IMedium</link>,
+ <link linkend="IMediumAttachment">IMediumAttachment</link> and
+ <link linkend="IMachine">IMachine</link> interfaces were
+ affected the most. Existing code using them to configure storage and
+ media needs to be carefully checked.</para>
+
+ <para>All media (hard disks, floppies and CDs/DVDs) are now
+ uniformly handled through the <link linkend="IMedium">IMedium</link>
+ interface. The device-specific interfaces
+ (<code>IHardDisk</code>, <code>IDVDImage</code>,
+ <code>IHostDVDDrive</code>, <code>IFloppyImage</code> and
+ <code>IHostFloppyDrive</code>) have been merged into IMedium; CD/DVD
+ and floppy media no longer need special treatment. The device type
+ of a medium determines in which context it can be used. Some
+ functionality was moved to the other storage-related
+ interfaces.</para>
+
+ <para><code>IMachine::attachHardDisk</code> and similar methods have
+ been renamed and generalized to deal with any type of drive and
+ medium.
+ <link linkend="IMachine__attachDevice">IMachine::attachDevice()</link>
+ is the API method for adding any drive to a storage controller. The
+ floppy and DVD/CD drives are no longer handled specially, and that
+ means you can have more than one of them. As before, drives can only
+ be changed while the VM is powered off. Mounting (or unmounting)
+ removable media at runtime is possible with
+ <link linkend="IMachine__mountMedium">IMachine::mountMedium()</link>.</para>
+
+ <para>Newly created virtual machines have no storage controllers
+ associated with them. Even the IDE Controller needs to be created
+ explicitly. The floppy controller is now visible as a separate
+ controller, with a new storage bus type. For each storage bus type
+ you can query the device types which can be attached, so that it is
+ not necessary to hardcode any attachment rules.</para>
+
+ <para>This required matching changes e.g. in the callback interfaces
+ (the medium specific change notification was replaced by a generic
+ medium change notification) and removing associated enums (e.g.
+ <code>DriveState</code>). In many places the incorrect use of the
+ plural form "media" was replaced by "medium", to improve
+ consistency.</para>
+ </listitem>
+
+ <listitem>
+ <para>Reading the
+ <link linkend="IMedium__state">IMedium::state</link> attribute no
+ longer automatically performs an accessibility check; a new method
+ <link linkend="IMedium__refreshState">IMedium::refreshState()</link>
+ does this. The attribute only returns the state now.</para>
+ </listitem>
+
+ <listitem>
+ <para>There were substantial changes related to snapshots, triggered
+ by the "branched snapshots" functionality introduced with version
+ 3.1. IConsole::discardSnapshot was renamed to
+ <computeroutput>IConsole::deleteSnapshot()</computeroutput>.
+ IConsole::discardCurrentState and
+ IConsole::discardCurrentSnapshotAndState were removed; corresponding
+ new functionality is in
+ <computeroutput>IConsole::restoreSnapshot()</computeroutput>.
+ Also, when <computeroutput>IConsole::takeSnapshot()</computeroutput>
+ is called on a running virtual machine, a live snapshot will be
+ created. The old behavior was to temporarily pause the virtual
+ machine while creating an online snapshot.</para>
+ </listitem>
+
+ <listitem>
+ <para>The <computeroutput>IVRDPServer</computeroutput>,
+ <computeroutput>IRemoteDisplayInfo"</computeroutput> and
+ <computeroutput>IConsoleCallback</computeroutput> interfaces were
+ changed to reflect VRDP server ability to bind to one of available
+ ports from a list of ports.</para>
+
+ <para>The <computeroutput>IVRDPServer::port</computeroutput>
+ attribute has been replaced with
+ <computeroutput>IVRDPServer::ports</computeroutput>, which is a
+ comma-separated list of ports or ranges of ports.</para>
+
+ <para>An <computeroutput>IRemoteDisplayInfo::port"</computeroutput>
+ attribute has been added for querying the actual port VRDP server
+ listens on.</para>
+
+ <para>An IConsoleCallback::onRemoteDisplayInfoChange() notification
+ callback has been added.</para>
+ </listitem>
+
+ <listitem>
+ <para>The parameter lists for the following functions were
+ modified:<itemizedlist>
+ <listitem>
+ <para><link linkend="IHost__removeHostOnlyNetworkInterface">IHost::removeHostOnlyNetworkInterface()</link></para>
+ </listitem>
+
+ <listitem>
+ <para><link linkend="IHost__removeUSBDeviceFilter">IHost::removeUSBDeviceFilter()</link></para>
+ </listitem>
+ </itemizedlist></para>
+ </listitem>
+
+ <listitem>
+ <para>In the OOWS bindings for JAX-WS, the behavior of structures
+ changed: for one, we implemented natural structures field access so
+ you can just call a "get" method to obtain a field. Secondly,
+ setters in structures were disabled as they have no expected effect
+ and were at best misleading.</para>
+ </listitem>
+ </itemizedlist>
+ </sect1>
+
+ <sect1>
+ <title>Incompatible API changes with version 3.0</title>
+
+ <itemizedlist>
+ <listitem>
+ <para>In the object-oriented web service bindings for JAX-WS, proper
+ inheritance has been introduced for some classes, so explicit
+ casting is no longer needed to call methods from a parent class. In
+ particular, IHardDisk and other classes now properly derive from
+ <link linkend="IMedium">IMedium</link>.</para>
+ </listitem>
+
+ <listitem>
+ <para>All object identifiers (machines, snapshots, disks, etc)
+ switched from GUIDs to strings (now still having string
+ representation of GUIDs inside). As a result, no particular internal
+ structure can be assumed for object identifiers; instead, they
+ should be treated as opaque unique handles. This change mostly
+ affects Java and C++ programs; for other languages, GUIDs are
+ transparently converted to strings.</para>
+ </listitem>
+
+ <listitem>
+ <para>The uses of NULL strings have been changed greatly. All out
+ parameters now use empty strings to signal a null value. For in
+ parameters both the old NULL and empty string is allowed. This
+ change was necessary to support more client bindings, especially
+ using the web service API. Many of them either have no special NULL
+ value or have trouble dealing with it correctly in the respective
+ library code.</para>
+ </listitem>
+
+ <listitem>
+ <para>Accidentally, the <code>TSBool</code> interface still appeared
+ in 3.0.0, and was removed in 3.0.2. This is an SDK bug, do not use
+ the SDK for VirtualBox 3.0.0 for developing clients.</para>
+ </listitem>
+
+ <listitem>
+ <para>The type of
+ <link linkend="IVirtualBoxErrorInfo__resultCode">IVirtualBoxErrorInfo::resultCode</link>
+ changed from
+ <computeroutput>result</computeroutput> to
+ <computeroutput>long</computeroutput>.</para>
+ </listitem>
+
+ <listitem>
+ <para>The parameter list of IVirtualBox::openHardDisk was
+ changed.</para>
+ </listitem>
+
+ <listitem>
+ <para>The method IConsole::discardSavedState was renamed to
+ IConsole::forgetSavedState, and a parameter was added.</para>
+ </listitem>
+
+ <listitem>
+ <para>The method IConsole::powerDownAsync was renamed to
+ <link linkend="IConsole__powerDown">IConsole::powerDown</link>,
+ and the previous method with that name was deleted. So effectively a
+ parameter was added.</para>
+ </listitem>
+
+ <listitem>
+ <para>In the
+ <link linkend="IFramebuffer">IFramebuffer</link> interface, the
+ following were removed:<itemizedlist>
+ <listitem>
+ <para>the <computeroutput>operationSupported</computeroutput>
+ attribute;</para>
+
+ <para>(as a result, the
+ <computeroutput>FramebufferAccelerationOperation</computeroutput>
+ enum was no longer needed and removed as well);</para>
+ </listitem>
+
+ <listitem>
+ <para>the <computeroutput>solidFill()</computeroutput>
+ method;</para>
+ </listitem>
+
+ <listitem>
+ <para>the <computeroutput>copyScreenBits()</computeroutput>
+ method.</para>
+ </listitem>
+ </itemizedlist></para>
+ </listitem>
+
+ <listitem>
+ <para>In the <link linkend="IDisplay">IDisplay</link>
+ interface, the following were removed:<itemizedlist>
+ <listitem>
+ <para>the
+ <computeroutput>setupInternalFramebuffer()</computeroutput>
+ method;</para>
+ </listitem>
+
+ <listitem>
+ <para>the <computeroutput>lockFramebuffer()</computeroutput>
+ method;</para>
+ </listitem>
+
+ <listitem>
+ <para>the <computeroutput>unlockFramebuffer()</computeroutput>
+ method;</para>
+ </listitem>
+
+ <listitem>
+ <para>the
+ <computeroutput>registerExternalFramebuffer()</computeroutput>
+ method.</para>
+ </listitem>
+ </itemizedlist></para>
+ </listitem>
+ </itemizedlist>
+ </sect1>
+
+ <sect1>
+ <title>Incompatible API changes with version 2.2</title>
+
+ <itemizedlist>
+ <listitem>
+ <para>Added explicit version number into JAX-WS Java package names,
+ such as <computeroutput>org.virtualbox_2_2</computeroutput>,
+ allowing connect to multiple VirtualBox clients from single Java
+ application.</para>
+ </listitem>
+
+ <listitem>
+ <para>The interfaces having a "2" suffix attached to them with
+ version 2.1 were renamed again to have that suffix removed. This
+ time around, this change involves only the name, there are no
+ functional differences.</para>
+
+ <para>As a result, IDVDImage2 is now IDVDImage; IHardDisk2 is now
+ IHardDisk; IHardDisk2Attachment is now IHardDiskAttachment.</para>
+
+ <para>Consequentially, all related methods and attributes that had a
+ "2" suffix have been renamed; for example, IMachine::attachHardDisk2
+ now becomes IMachine::attachHardDisk().</para>
+ </listitem>
+
+ <listitem>
+ <para>IVirtualBox::openHardDisk has an extra parameter for opening a
+ disk read/write or read-only.</para>
+ </listitem>
+
+ <listitem>
+ <para>The remaining collections were replaced by more performant
+ safe-arrays. This affects the following collections:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>IGuestOSTypeCollection</para>
+ </listitem>
+
+ <listitem>
+ <para>IHostDVDDriveCollection</para>
+ </listitem>
+
+ <listitem>
+ <para>IHostFloppyDriveCollection</para>
+ </listitem>
+
+ <listitem>
+ <para>IHostUSBDeviceCollection</para>
+ </listitem>
+
+ <listitem>
+ <para>IHostUSBDeviceFilterCollection</para>
+ </listitem>
+
+ <listitem>
+ <para>IProgressCollection</para>
+ </listitem>
+
+ <listitem>
+ <para>ISharedFolderCollection</para>
+ </listitem>
+
+ <listitem>
+ <para>ISnapshotCollection</para>
+ </listitem>
+
+ <listitem>
+ <para>IUSBDeviceCollection</para>
+ </listitem>
+
+ <listitem>
+ <para>IUSBDeviceFilterCollection</para>
+ </listitem>
+ </itemizedlist>
+ </listitem>
+
+ <listitem>
+ <para>Since "Host Interface Networking" was renamed to "bridged
+ networking" and host-only networking was introduced, all associated
+ interfaces needed renaming as well. In detail:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>The HostNetworkInterfaceType enum has been renamed to
+ <link linkend="HostNetworkInterfaceMediumType">HostNetworkInterfaceMediumType</link></para>
+ </listitem>
+
+ <listitem>
+ <para>The IHostNetworkInterface::type attribute has been renamed
+ to
+ <link linkend="IHostNetworkInterface__mediumType">IHostNetworkInterface::mediumType</link></para>
+ </listitem>
+
+ <listitem>
+ <para>INetworkAdapter::attachToHostInterface() has been renamed
+ to INetworkAdapter::attachToBridgedInterface</para>
+ </listitem>
+
+ <listitem>
+ <para>In the IHost interface, createHostNetworkInterface() has
+ been renamed to
+ <link linkend="IHost__createHostOnlyNetworkInterface">createHostOnlyNetworkInterface()</link></para>
+ </listitem>
+
+ <listitem>
+ <para>Similarly, removeHostNetworkInterface() has been renamed
+ to
+ <link linkend="IHost__removeHostOnlyNetworkInterface">removeHostOnlyNetworkInterface()</link></para>
+ </listitem>
+ </itemizedlist>
+ </listitem>
+ </itemizedlist>
+ </sect1>
+
+ <sect1>
+ <title>Incompatible API changes with version 2.1</title>
+
+ <itemizedlist>
+ <listitem>
+ <para>With VirtualBox 2.1, error codes were added to many error
+ infos that give the caller a machine-readable (numeric) feedback in
+ addition to the error string that has always been available. This is
+ an ongoing process, and future versions of this SDK reference will
+ document the error codes for each method call.</para>
+ </listitem>
+
+ <listitem>
+ <para>The hard disk and other media interfaces were completely
+ redesigned. This was necessary to account for the support of VMDK,
+ VHD and other image types; since backwards compatibility had to be
+ broken anyway, we seized the moment to redesign the interfaces in a
+ more logical way.</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>Previously, the old IHardDisk interface had several
+ derivatives called IVirtualDiskImage, IVMDKImage, IVHDImage,
+ IISCSIHardDisk and ICustomHardDisk for the various disk formats
+ supported by VirtualBox. The new IHardDisk2 interface that comes
+ with version 2.1 now supports all hard disk image formats
+ itself.</para>
+ </listitem>
+
+ <listitem>
+ <para>IHardDiskFormat is a new interface to describe the
+ available back-ends for hard disk images (e.g. VDI, VMDK, VHD or
+ iSCSI). The IHardDisk2::format attribute can be used to find out
+ the back-end that is in use for a particular hard disk image.
+ ISystemProperties::hardDiskFormats[] contains a list of all
+ back-ends supported by the system.
+ <link linkend="ISystemProperties__defaultHardDiskFormat">ISystemProperties::defaultHardDiskFormat</link>
+ contains the default system format.</para>
+ </listitem>
+
+ <listitem>
+ <para>In addition, the new
+ <link linkend="IMedium">IMedium</link> interface is a generic
+ interface for hard disk, DVD and floppy images that contains the
+ attributes and methods shared between them. It can be considered
+ a parent class of the more specific interfaces for those images,
+ which are now IHardDisk2, IDVDImage2 and IFloppyImage2.</para>
+
+ <para>In each case, the "2" versions of these interfaces replace
+ the earlier versions that did not have the "2" suffix.
+ Previously, the IDVDImage and IFloppyImage interfaces were
+ entirely unrelated to IHardDisk.</para>
+ </listitem>
+
+ <listitem>
+ <para>As a result, all parts of the API that previously
+ referenced IHardDisk, IDVDImage or IFloppyImage or any of the
+ old subclasses are gone and will have replacements that use
+ IHardDisk2, IDVDImage2 and IFloppyImage2; see, for example,
+ IMachine::attachHardDisk2.</para>
+ </listitem>
+
+ <listitem>
+ <para>In particular, the IVirtualBox::hardDisks2 array replaces
+ the earlier IVirtualBox::hardDisks collection.</para>
+ </listitem>
+ </itemizedlist>
+ </listitem>
+
+ <listitem>
+ <para><link linkend="IGuestOSType">IGuestOSType</link> was
+ extended to group operating systems into families and for 64-bit
+ support.</para>
+ </listitem>
+
+ <listitem>
+ <para>The
+ <link linkend="IHostNetworkInterface">IHostNetworkInterface</link>
+ interface was completely rewritten to account for the changes in how
+ Host Interface Networking is now implemented in VirtualBox
+ 2.1.</para>
+ </listitem>
+
+ <listitem>
+ <para>The IVirtualBox::machines2[] array replaces the former
+ IVirtualBox::machines collection.</para>
+ </listitem>
+
+ <listitem>
+ <para>Added
+ <link linkend="IHost__getProcessorFeature">IHost::getProcessorFeature()</link>
+ and <link linkend="ProcessorFeature">ProcessorFeature</link>
+ enumeration.</para>
+ </listitem>
+
+ <listitem>
+ <para>The parameter list for
+ <link linkend="IVirtualBox__createMachine">IVirtualBox::createMachine()</link>
+ was modified.</para>
+ </listitem>
+
+ <listitem>
+ <para>Added IMachine::pushGuestProperty.</para>
+ </listitem>
+
+ <listitem>
+ <para>New attributes in IMachine: accelerate3DEnabled,
+ HWVirtExVPIDEnabled,
+ <computeroutput>IMachine::guestPropertyNotificationPatterns</computeroutput>,
+ <link linkend="IMachine__CPUCount">CPUCount</link>.</para>
+ </listitem>
+
+ <listitem>
+ <para>Added
+ <link linkend="IConsole__powerUpPaused">IConsole::powerUpPaused()</link>
+ and
+ <link linkend="IConsole__getGuestEnteredACPIMode">IConsole::getGuestEnteredACPIMode()</link>.</para>
+ </listitem>
+
+ <listitem>
+ <para>Removed ResourceUsage enumeration.</para>
+ </listitem>
+ </itemizedlist>
+ </sect1>
+ </chapter>
+</book>
+<!-- vim: set shiftwidth=2 tabstop=2 expandtab: -->