diff options
| author | Daniel Baumann <daniel.baumann@progress-linux.org> | 2024-04-11 08:17:27 +0000 |
|---|---|---|
| committer | Daniel Baumann <daniel.baumann@progress-linux.org> | 2024-04-11 08:17:27 +0000 |
| commit | f215e02bf85f68d3a6106c2a1f4f7f063f819064 (patch) | |
| tree | 6bb5b92c046312c4e95ac2620b10ddf482d3fa8b /doc/manual/en_US/SDKRef.xml | |
| parent | Initial commit. (diff) | |
| download | virtualbox-f215e02bf85f68d3a6106c2a1f4f7f063f819064.tar.xz virtualbox-f215e02bf85f68d3a6106c2a1f4f7f063f819064.zip | |
Adding upstream version 7.0.14-dfsg.upstream/7.0.14-dfsg
Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>
Diffstat (limited to 'doc/manual/en_US/SDKRef.xml')
| -rw-r--r-- | doc/manual/en_US/SDKRef.xml | 6324 |
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><file></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|<library></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 + <vmname|uuid></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><?xml version="1.0" encoding="UTF-8"?> +<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/"> +<SOAP-ENV:Body> + <test:SayHello> + <name>Peter</name> + </test:SayHello> + </SOAP-ENV:Body> +</SOAP-ENV:Envelope></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->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<></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 " & 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 & " " & 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->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->pfnClientUninitialize() + * when done. + */ + +if (VBoxCGlueInit()) +{ + fprintf(stderr, "s: FATAL: VBoxCGlueInit failed: %s\n", + argv[0], g_szVBoxErrMsg); + return EXIT_FAILURE; +} + +g_pVBoxFuncs->pfnClientInitialize(NULL, &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, &vbox); +if (FAILED(rc) || !vbox) +{ + PrintErrorInfo(argv[0], "FATAL: could not get VirtualBox reference", rc); + return EXIT_FAILURE; +} +rc = IVirtualBoxClient_get_Session(vboxclient, &session); +if (FAILED(rc) || !session) +{ + PrintErrorInfo(argv[0], "FATAL: could not get Session reference", rc); + return EXIT_FAILURE; +} + +rc = IVirtualBox_get_Revision(vbox, &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, &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 */ + &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 **)&pData, &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 ***)&machines, &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 *)&machines[0], sizeof(machines[0])); +IVirtualBox_GetMachineStates(ComSafeArrayAsInParam(psa), ...); +... +g_pVBoxFuncs->pfnSafeArrayDestroy(psa); +for (i = 0; i < 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, &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->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->pfnClientInitialize()</computeroutput> + , e.g. <screen>#include <stdlib.h> +#include <stdio.h> + +... + +/* + * Make sure g_pVBoxFuncs->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->pfnClientUninitialize()) != 0) { + fprintf(stderr, "failed to register g_pVBoxFuncs->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->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->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->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 $< + +# Compile interface ID list +VirtualBox_i.o: $(PLATFORM_LIB)/VirtualBox_i.c + $(CC) $(CFLAGS) $(CAPI_INC) $(PLATFORM_INC) $(GLUE_INC) -o $@ -c $< + +# Compile program code +program.o: program.c + $(CC) $(CFLAGS) $(CAPI_INC) $(PLATFORM_INC) $(GLUE_INC) -o $@ -c $< + +# 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() < 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) < 3): + print "usage: createHdd sizeM location type" + return 0 + + # Get arguments + size = int(args[1]) + loc = args[2] + if len(args) > 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(&data, sizeof(VBoxGuestHGCMConnectInfo)); + + data.result = VINF_SUCCESS; + data.Loc.type = VMMDevHGCMLoc_LocalHost_Existing; + strcpy (data.Loc.u.host.achName, "VBoxSharedFolders"); + + rc = VbglHGCMConnect (&handle, "VBoxSharedFolders"&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 (&data, sizeof (VBoxGuestHGCMDisconnectInfo)); + + data.result = VINF_SUCCESS; + data.u32ClientID = ulClientID; + + rc = VbglHGCMDisconnect (handle, &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->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, &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->cbSize</computeroutput> and + <computeroutput>ptable->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> + <div id="FlashRDP"> + </div> +</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: --> |