diff options
Diffstat (limited to 'doc/manual/en_US/SDKRef.xml')
| -rw-r--r-- | doc/manual/en_US/SDKRef.xml | 4899 |
1 files changed, 4899 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..40e1559f --- /dev/null +++ b/doc/manual/en_US/SDKRef.xml @@ -0,0 +1,4899 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN" +"http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd"> +<book> + <bookinfo> + <title>$VBOX_PRODUCT<superscript>®</superscript></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 lang="" + 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/.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 + <computeroutput>IWebsessionManager::logon()</computeroutput> API (see + <xref linkend="IWebsessionManager__logon" />) 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 + <xref linkend="IMachine__name" xreflabel="IMachine::name" />), 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" os="" /> 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 <xref linkend="IWebsessionManager" + xreflabel="IWebsessionManager" />, 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 <xref + linkend="IWebsessionManager__logon" + xreflabel="IWebsessionManager::logon()" />, which is the first + call that actually communicates with the server. This + authenticates the client with the web service and returns an + instance of <xref linkend="IVirtualBox" + xreflabel="IVirtualBox" />, 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 + <xref linkend="IManagedObjectRef__release" + xreflabel="IManagedObjectRef::release()" /> 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>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 Python 2.3 for 10.4, Python + 2.5 for 10.5 and Python 2.5 and 2.6 for 10.6.</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. Version of Python Win32 extensions earlier than 2.16 are known to have bugs, + leading to issues with VirtualBox Python bindings, and also some early builds of Python 2.5 for Windows have issues with + reporting platform name on some Windows versions, 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="???">http://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 <xref linkend="IVirtualBox__createMachine" + xreflabel="IVirtualBox::createMachine()" />), 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" os="" /> 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" os="" /> 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 <xref linkend="IWebsessionManager" + xreflabel="IWebsessionManager" /> 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 <xref linkend="IVirtualBox" xreflabel="IVirtualBox" /> + 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 <xref + linkend="IWebsessionManager__logon" + xreflabel="IWebsessionManager::logon()" /> 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 <xref + linkend="IWebsessionManager__logoff" + xreflabel="IWebsessionManager::logoff()" /> 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 <xref linkend="IVirtualBox" xreflabel="IVirtualBox" />. + 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, <xref + linkend="IWebsessionManager__logon" + xreflabel="IWebsessionManager::logon()" /> 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 + <xref linkend="IVirtualBox__version" xreflabel="version" /> + 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 <xref + linkend="IWebsessionManager__logoff" + xreflabel="IWebsessionManager::logoff()" /> 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 <xref + linkend="IWebsessionManager__logon" + xreflabel="IWebsessionManager::logon()" />.</para> + + <para>Upon logon, the websession manager creates one instance + of <xref linkend="IVirtualBox" xreflabel="IVirtualBox" /> and + another object of <xref linkend="ISession" + xreflabel="ISession" /> representing the web service session. + This can be retrieved using <xref + linkend="IWebsessionManager__getSessionObject" + xreflabel="IWebsessionManager::getSessionObject()" />.</para> + + <para>(Technically, there is always only one <xref + linkend="IVirtualBox" xreflabel="IVirtualBox" /> object, which + is shared between all sessions and clients, as it is a COM + singleton. However, each session receives its own managed + object reference to it. The <xref linkend="ISession" + xreflabel="ISession" /> object, however, is created and + destroyed for each session.)</para> + </listitem> + + <listitem> + <para>Whenever a web service clients invokes an operation + whose COM implementation creates COM objects.</para> + + <para>For example, <xref linkend="IVirtualBox__createMachine" + xreflabel="IVirtualBox::createMachine()" /> creates a new + instance of <xref linkend="IMachine" xreflabel="IMachine" />; + 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 <xref + linkend="IManagedObjectRef__release" + xreflabel="IManagedObjectRef::release()" />. 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 <xref + linkend="IWebsessionManager__logoff" + xreflabel="IWebsessionManager::logoff()" />, 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 install. See below for details on how to set up + the glue layer if you want to use a different Python + installation.</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.vbox +name = "Linux" +mach = vbox.findMachine(name) +session = mgr.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.vbox + +for m in mgr.getArray(vbox, 'machines'): +print "Machine '%s' logs in '%s'" %(m.name, m.logFolder) + </screen> + + <para>Code above demonstartes 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.mgr.getSessionObject()</computeroutput>).</para> + + <para>In case you want to use the glue layer with a different Python + installation, use these steps in a shell to add the necessary + files:</para> + + <screen> # cd VBOX_INSTALL_PATH/sdk/installer + # PYTHON vboxapisetup.py install</screen> + </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 XPCOM API</title> + + <note> + <para>This section currently applies to Linux hosts only.</para> + </note> + + <para>Starting with version 2.2, VirtualBox offers a C binding for the + XPCOM API.</para> + + <para>The C binding provides a layer enabling object creation, method + invocation and attribute access from C.</para> + + <sect3 id="c-gettingstarted"> + <title>Getting started</title> + + <para>The following sections describe how to use the C binding in a + C program.</para> + + <para>For Linux, a sample program is provided which demonstrates use + of the C binding to initialize XPCOM, get handles for VirtualBox and + Session objects, make calls to list and start virtual machines, and + uninitialize resources when done. The program uses the VBoxGlue + library to open the C binding layer during runtime.</para> + + <para>The sample program + <computeroutput>tstXPCOMCGlue</computeroutput> is located in the bin + directory and can be run without arguments. It lists registered + machines on the host along with some additional information and ask + for a machine to start. The source for this program is available in + <computeroutput>sdk/bindings/xpcom/cbinding/samples/</computeroutput> + directory. The source for the VBoxGlue library is available in the + <computeroutput>sdk/bindings/xpcom/cbinding/</computeroutput> + directory.</para> + </sect3> + + <sect3 id="c-initialization"> + <title>XPCOM initialization</title> + + <para>Just like in C++, XPCOM needs to be initialized before it can + be used. The <computeroutput>VBoxCAPI_v2_5.h</computeroutput> header + provides the interface to the C binding. Here's how to initialize + XPCOM:</para> + + <screen>#include "VBoxCAPI_v2_5.h" +... +PCVBOXXPCOM g_pVBoxFuncs = NULL; +IVirtualBox *vbox = NULL; +ISession *session = NULL; + +/* + * VBoxGetXPCOMCFunctions() is the only function exported by + * VBoxXPCOMC.so and the only one needed to make virtualbox + * work with C. This functions 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->pfnComInitialize does all the necessary startup + * action and provides us with pointers to vbox and session handles. + * It should be matched by a call to g_pVBoxFuncs->pfnComUninitialize() + * when done. + */ + +g_pVBoxFuncs = VBoxGetXPCOMCFunctions(VBOX_XPCOMC_VERSION); +g_pVBoxFuncs->pfnComInitialize(&vbox, &session);</screen> + + <para>If either <computeroutput>vbox</computeroutput> or + <computeroutput>session</computeroutput> is still + <computeroutput>NULL</computeroutput>, initialization failed and the + XPCOM API cannot be used.</para> + </sect3> + + <sect3 id="c-invocation"> + <title>XPCOM method invocation</title> + + <para>Method invocation is straightforward. It looks pretty much + like the C++ way, augmented with an extra indirection due to + accessing the vtable and passing a pointer to the object 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.</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>In other words, to call an object's method what you need + is</para> + + <screen>IObject *object; +nsresult rc; +... +/* + * Calling void IObject::method(arg, ...) + */ +rc = object->vtbl->Method(object, arg, ...); + +... +IFoo *foo; +/* + * Calling IFoo IObject::method(arg, ...) + */ +rc = object->vtbl->Method(object, args, ..., &foo);</screen> + + <para>As a real-world example of a method invocation, let's call + <xref linkend="IMachine__launchVMProcess" + xreflabel="IMachine::launchVMProcess" /> which returns an + IProgress object. Note again that the method name is + capitalized.</para> + + <screen>IProgress *progress; +... +rc = vbox->vtbl->LaunchVMProcess( + machine, /* this */ + session, /* arg 1 */ + sessionType, /* arg 2 */ + env, /* arg 3 */ + &progress /* Out */ +); +</screen> + </sect3> + + <sect3 id="c-attributes"> + <title>XPCOM attribute access</title> + + <para>A construct similar to calling non-void methods is used to + access object attributes. 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 read the <xref linkend="IVirtualBox__revision" + xreflabel="IVirtualBox::revision" /> attribute.</para> + + <para>Using the <computeroutput>IVirtualBox</computeroutput> handle + <computeroutput>vbox</computeroutput> obtained above, calling its + <computeroutput>GetRevision</computeroutput> method looks like + this:</para> + + <screen>PRUint32 rev; + +rc = vbox->vtbl->GetRevision(vbox, &rev); +if (NS_SUCCEEDED(rc)) +{ + printf("Revision: %u\n", (unsigned)rev); +} +</screen> + + <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, XPCOM 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>PRUnichar</computeroutput>. Strings of UTF-16 + characters are arrays of that type. Most string handling functions + take pointers to that type. Prototypes for the following conversion + functions are declared in + <computeroutput>VBoxCAPI_v2_5.h</computeroutput>.</para> + + <sect4> + <title>Conversion of UTF-16 to and from UTF-8</title> + + <screen>int (*pfnUtf16ToUtf8)(const PRUnichar *pwszString, char **ppszString); +int (*pfnUtf8ToUtf16)(const char *pszString, PRUnichar **ppwszString); +</screen> + </sect4> + + <sect4> + <title>Ownership</title> + + <para>The ownership of a string determines who is responsible for + releasing resources associated with the string. Whenever XPCOM + creates a string, ownership is transferred to the caller. To avoid + resource leaks, the caller should release resources once the + string is no longer needed.</para> + </sect4> + </sect3> + + <sect3 id="c-uninitialization"> + <title>XPCOM uninitialization</title> + + <para>Uninitialization is performed by + <computeroutput>g_pVBoxFuncs->pfnComUninitialize().</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->pfnComInitialize()</computeroutput> + , e.g. <screen>#include <stdlib.h> +#include <stdio.h> + +... + +/* + * Make sure g_pVBoxFuncs->pfnComUninitialize() 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(). Separate provisions must be taken for these cases. + */ + +if (atexit(g_pVBoxFuncs->pfnComUninitialize()) != 0) { + fprintf(stderr, "failed to register g_pVBoxFuncs->pfnComUninitialize()\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->pfnComUninitialize()</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->pfnComUninitialize()</computeroutput> + later on (usually <emphasis>not</emphasis> from the handler itself + .)</para> + + <para>That said, if a client program forgets to call + <computeroutput>g_pVBoxFuncs->pfnComUninitialize()</computeroutput> + before it terminates, there is a mechanism in place which will + eventually release references held by the client. You should not + rely on this, however.</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>tstXPCOMCGlue.c</computeroutput>. + Compilation and linking can be achieved, e.g., with a makefile + fragment similar to</para> + + <screen># Where is the XPCOM include directory? +INCS_XPCOM = -I../../include +# Where is the glue code directory? +GLUE_DIR = .. +GLUE_INC = -I.. + +#Compile Glue Library +VBoxXPCOMCGlue.o: $(GLUE_DIR)/VBoxXPCOMCGlue.c + $(CC) $(CFLAGS) $(INCS_XPCOM) $(GLUE_INC) -o $@ -c $< + +# Compile. +program.o: program.c VBoxCAPI_v2_5.h + $(CC) $(CFLAGS) $(INCS_XPCOM) $(GLUE_INC) -o $@ -c $< + +# Link. +program: program.o VBoxXPCOMCGlue.o + $(CC) -o $@ $^ -ldl</screen> + </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 <xref linkend="IVirtualBox" + xreflabel="IVirtualBox" />), from which all other functionality of the + API is derived. With the OOWS for JAX-WS, this is returned from the + <xref linkend="IWebsessionManager__logon" + xreflabel="IWebsessionManager::logon()" /> call.</para> + + <para>To enumerate virtual machines, one would look at the "machines" + array attribute in the VirtualBox object (see <xref + linkend="IVirtualBox__machines" xreflabel="IVirtualBox::machines" />). + This array contains all virtual machines currently registered with the + host, each of them being an instance of <xref linkend="IMachine" + xreflabel="IMachine" />. 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 + <xref linkend="IMachine" xreflabel="IMachine 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 "<xref linkend="IMachine__name" + xreflabel="name" />" 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 <xref linkend="ISession" + xreflabel="ISession" /> interface. Each process which talks to + VirtualBox needs its own instance of ISession. In the web service, you + cannot create such an object, but + <computeroutput>vboxwebsrv</computeroutput> creates one for you when you + log on, which you can obtain by calling <xref + linkend="IWebsessionManager__getSessionObject" + xreflabel="IWebsessionManager::getSessionObject()" />.</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 <xref + linkend="IMachine__lockMachine" xreflabel="IMachine::lockMachine()" /> + with your process's session object.</para> + + <para>After the machine has been locked, the <xref + linkend="ISession__machine" xreflabel="ISession::machine" /> 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 <xref + linkend="IMachine__saveSettings" + xreflabel="IMachine::saveSettings()" />, 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 <xref linkend="ISession__unlockMachine" + xreflabel="ISession::unlockMachine()" />. 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 <xref + linkend="IMachine__launchVMProcess" + xreflabel="IMachine::launchVMProcess()" />. 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 a + 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 <xref linkend="ISession__console" + xreflabel="ISession::console" />) with which the VM can be paused, + stopped, snapshotted or other things.</para> + </sect1> + + <sect1> + <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 <xref linkend="IEventListener" + xreflabel="IEventListener" /> interface), which will then get notified + by the server when an event (represented by the <xref linkend="IEvent" + xreflabel="IEvent" /> 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 <xref + linkend="IMachineStateChangedEvent" + xreflabel="IMachineStateChangedEvent" /> or <xref + linkend="IMediumChangedEvent" xreflabel="IMediumChangedEvent" />.</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>.VirtualBox/shexts</computeroutput> + below your home directory 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'].createHardDisk(format, loc) + # Access constants using ctx['global'].constants + progress = hdd.createBaseStorage(size, ctx['global'].constants.HardDiskVariant_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>.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> + + <!--$VIRTUALBOX_MAIN_API_REFERENCE--> + + <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> +DECLVBGL(int) VbglHGCMConnect (VBGLHGCMHANDLE *pHandle, VBoxGuestHGCMConnectInfo *pData); + </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, &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="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_3_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.</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 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 + <xref linkend="IGuestSession" xreflabel="IGuestSession" /> interface which + can be created by calling <xref linkend="IGuest__createSession" + xreflabel="IGuest::createSession()" />.</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 + <xref linkend="IGuestProcess" xreflabel="IGuestProcess" />, + <xref linkend="IGuestDirectory" xreflabel="IGuestDirectory" /> and + <xref linkend="IGuestFile" xreflabel="IGuestFile" />. To retrieve more + information of a file system object the new interface + <xref linkend="IGuestFsObjInfo" xreflabel="IGuestFsObjInfo" /> 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 <xref linkend="IGuestFile" xreflabel="IGuestFile" /> + interface is not fully implemented yet.</para> + </listitem> + <listitem><para>The symbolic link APIs + <xref linkend="IGuestSession__symlinkCreate" + xreflabel="IGuestSession::symlinkCreate()" />, + <xref linkend="IGuestSession__symlinkExists" + xreflabel="IGuestSession::symlinkExists()" />, + <xref linkend="IGuestSession__symlinkRead" + xreflabel="IGuestSession::symlinkRead()" />, + <xref linkend="IGuestSession__symlinkRemoveDirectory" + xreflabel="IGuestSession::symlinkRemoveDirectory()" /> and + <xref linkend="IGuestSession__symlinkRemoveFile" + xreflabel="IGuestSession::symlinkRemoveFile()" /> are not + implemented yet.</para> + </listitem> + <listitem><para>The directory APIs + <xref linkend="IGuestSession__directoryRemove" + xreflabel="IGuestSession::directoryRemove()" />, + <xref linkend="IGuestSession__directoryRemoveRecursive" + xreflabel="IGuestSession::directoryRemoveRecursive()" />, + <xref linkend="IGuestSession__directoryRename" + xreflabel="IGuestSession::directoryRename()" /> and + <xref linkend="IGuestSession__directorySetACL" + xreflabel="IGuestSession::directorySetACL()" /> are not + implemented yet.</para> + </listitem> + <listitem><para>The temporary file creation API + <xref linkend="IGuestSession__fileCreateTemp" + xreflabel="IGuestSession::fileCreateTemp()" /> is not + implemented yet.</para> + </listitem> + <listitem><para>Guest process termination via + <xref linkend="IProcess__terminate" + xreflabel="IProcess::terminate()" /> is not + implemented yet.</para> + </listitem> + <listitem><para>Waiting for guest process output via + <xref linkend="ProcessWaitForFlag__StdOut" xreflabel="ProcessWaitForFlag::StdOut" /> + and <xref linkend="ProcessWaitForFlag__StdErr" xreflabel="ProcessWaitForFlag::StdErr" /> + is not implemented yet.</para><para>To wait for process output, <xref linkend="IProcess__read" + xreflabel="IProcess::read()" /> with appropriate flags still can be used to periodically + check for new output data to arrive. Note that <xref linkend="ProcessCreateFlag__WaitForStdOut" + xreflabel="ProcessCreateFlag::WaitForStdOut" /> and / or + <xref linkend="ProcessCreateFlag__WaitForStdErr" xreflabel="ProcessCreateFlag::WaitForStdErr" /> + need to be specified when creating a guest process via <xref linkend="IGuestSession__processCreate" + xreflabel="IGuestSession::processCreate()" /> or <xref linkend="IGuestSession__processCreateEx" + xreflabel="IGuestSession::processCreateEx()" />.</para> + </listitem> + <listitem> + <para>ACL (Access Control List) handling in general is not implemented yet.</para> + </listitem> + </itemizedlist> + </para> + </listitem> + + <listitem> + <para>The <xref linkend="LockType" xreflabel="LockType" /> + enumeration now has an additional value <computeroutput>VM</computeroutput> + which tells <xref linkend="IMachine__lockMachine" + xreflabel="IMachine::lockMachine()" /> 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. <xref linkend="IVirtualBox__createMachine" + xreflabel="IVirtualBox::createMachine()"/> and + <xref linkend="IVirtualBox__composeMachineFilename" + xreflabel="IVirtualBox::composeMachineFilename()"/> 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 <xref linkend="IVirtualBox__openMedium" + xreflabel="IVirtualBox::openMedium()" />.</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><xref linkend="PointingHIDType" xreflabel="PointingHIDType"/></entry> + </row> + <row> + <entry>KeyboardHidType</entry> + <entry><xref linkend="KeyboardHIDType" xreflabel="KeyboardHIDType"/></entry> + </row> + <row> + <entry>IPciAddress</entry> + <entry><xref linkend="IPCIAddress" xreflabel="IPCIAddress"/></entry> + </row> + <row> + <entry>IPciDeviceAttachment</entry> + <entry><xref linkend="IPCIDeviceAttachment" xreflabel="IPCIDeviceAttachment"/></entry> + </row> + <row> + <entry>IMachine::pointingHidType</entry> + <entry><xref linkend="IMachine__pointingHIDType" xreflabel="IMachine::pointingHIDType"/></entry> + </row> + <row> + <entry>IMachine::keyboardHidType</entry> + <entry><xref linkend="IMachine__keyboardHIDType" xreflabel="IMachine::keyboardHIDType"/></entry> + </row> + <row> + <entry>IMachine::hpetEnabled</entry> + <entry><xref linkend="IMachine__HPETEnabled" xreflabel="IMachine::HPETEnabled"/></entry> + </row> + <row> + <entry>IMachine::sessionPid</entry> + <entry><xref linkend="IMachine__sessionPID" xreflabel="IMachine::sessionPID"/></entry> + </row> + <row> + <entry>IMachine::ioCacheEnabled</entry> + <entry><xref linkend="IMachine__IOCacheEnabled" xreflabel="IMachine::IOCacheEnabled"/></entry> + </row> + <row> + <entry>IMachine::ioCacheSize</entry> + <entry><xref linkend="IMachine__IOCacheSize" xreflabel="IMachine::IOCacheSize"/></entry> + </row> + <row> + <entry>IMachine::pciDeviceAssignments</entry> + <entry><xref linkend="IMachine__PCIDeviceAssignments" xreflabel="IMachine::PCIDeviceAssignments"/></entry> + </row> + <row> + <entry>IMachine::attachHostPciDevice()</entry> + <entry><xref linkend="IMachine__attachHostPCIDevice" xreflabel="IMachine::attachHostPCIDevice"/></entry> + </row> + <row> + <entry>IMachine::detachHostPciDevice()</entry> + <entry><xref linkend="IMachine__detachHostPCIDevice" xreflabel="IMachine::detachHostPCIDevice()"/></entry> + </row> + <row> + <entry>IConsole::attachedPciDevices</entry> + <entry><xref linkend="IConsole__attachedPCIDevices" xreflabel="IConsole::attachedPCIDevices"/></entry> + </row> + <row> + <entry>IHostNetworkInterface::dhcpEnabled</entry> + <entry><xref linkend="IHostNetworkInterface__DHCPEnabled" xreflabel="IHostNetworkInterface::DHCPEnabled"/></entry> + </row> + <row> + <entry>IHostNetworkInterface::enableStaticIpConfig()</entry> + <entry><xref linkend="IHostNetworkInterface__enableStaticIPConfig" xreflabel="IHostNetworkInterface::enableStaticIPConfig()"/></entry> + </row> + <row> + <entry>IHostNetworkInterface::enableStaticIpConfigV6()</entry> + <entry><xref linkend="IHostNetworkInterface__enableStaticIPConfigV6" xreflabel="IHostNetworkInterface::enableStaticIPConfigV6()"/></entry> + </row> + <row> + <entry>IHostNetworkInterface::enableDynamicIpConfig()</entry> + <entry><xref linkend="IHostNetworkInterface__enableDynamicIPConfig" xreflabel="IHostNetworkInterface::enableDynamicIPConfig()"/></entry> + </row> + <row> + <entry>IHostNetworkInterface::dhcpRediscover()</entry> + <entry><xref linkend="IHostNetworkInterface__DHCPRediscover" xreflabel="IHostNetworkInterface::DHCPRediscover()"/></entry> + </row> + <row> + <entry>IHost::Acceleration3DAvailable</entry> + <entry><xref linkend="IHost__acceleration3DAvailable" xreflabel="IHost::acceleration3DAvailable"/></entry> + </row> + <row> + <entry>IGuestOSType::recommendedPae</entry> + <entry><xref linkend="IGuestOSType__recommendedPAE" xreflabel="IGuestOSType::recommendedPAE"/></entry> + </row> + <row> + <entry>IGuestOSType::recommendedDvdStorageController</entry> + <entry><xref linkend="IGuestOSType__recommendedDVDStorageController" xreflabel="IGuestOSType::recommendedDVDStorageController"/></entry> + </row> + <row> + <entry>IGuestOSType::recommendedDvdStorageBus</entry> + <entry><xref linkend="IGuestOSType__recommendedDVDStorageBus" xreflabel="IGuestOSType::recommendedDVDStorageBus"/></entry> + </row> + <row> + <entry>IGuestOSType::recommendedHdStorageController</entry> + <entry><xref linkend="IGuestOSType__recommendedHDStorageController" xreflabel="IGuestOSType::recommendedHDStorageController"/></entry> + </row> + <row> + <entry>IGuestOSType::recommendedHdStorageBus</entry> + <entry><xref linkend="IGuestOSType__recommendedHDStorageBus" xreflabel="IGuestOSType::recommendedHDStorageBus"/></entry> + </row> + <row> + <entry>IGuestOSType::recommendedUsbHid</entry> + <entry><xref linkend="IGuestOSType__recommendedUSBHID" xreflabel="IGuestOSType::recommendedUSBHID"/></entry> + </row> + <row> + <entry>IGuestOSType::recommendedHpet</entry> + <entry><xref linkend="IGuestOSType__recommendedHPET" xreflabel="IGuestOSType::recommendedHPET"/></entry> + </row> + <row> + <entry>IGuestOSType::recommendedUsbTablet</entry> + <entry><xref linkend="IGuestOSType__recommendedUSBTablet" xreflabel="IGuestOSType::recommendedUSBTablet"/></entry> + </row> + <row> + <entry>IGuestOSType::recommendedRtcUseUtc</entry> + <entry><xref linkend="IGuestOSType__recommendedRTCUseUTC" xreflabel="IGuestOSType::recommendedRTCUseUTC"/></entry> + </row> + <row> + <entry>IGuestOSType::recommendedUsb</entry> + <entry><xref linkend="IGuestOSType__recommendedUSB" xreflabel="IGuestOSType::recommendedUSB"/></entry> + </row> + <row> + <entry>INetworkAdapter::natDriver</entry> + <entry><xref linkend="INetworkAdapter__NATEngine" xreflabel="INetworkAdapter::NATEngine"/></entry> + </row> + <row> + <entry>IUSBController::enabledEhci</entry> + <entry><xref linkend="IUSBController__enabledEHCI" xreflabel="IUSBController::enabledEHCI"/></entry> + </row> + <row> + <entry>INATEngine::tftpPrefix</entry> + <entry><xref linkend="INATEngine__TFTPPrefix" xreflabel="INATEngine::TFTPPrefix"/></entry> + </row> + <row> + <entry>INATEngine::tftpBootFile</entry> + <entry><xref linkend="INATEngine__TFTPBootFile" xreflabel="INATEngine::TFTPBootFile"/></entry> + </row> + <row> + <entry>INATEngine::tftpNextServer</entry> + <entry><xref linkend="INATEngine__TFTPNextServer" xreflabel="INATEngine::TFTPNextServer"/></entry> + </row> + <row> + <entry>INATEngine::dnsPassDomain</entry> + <entry><xref linkend="INATEngine__DNSPassDomain" xreflabel="INATEngine::DNSPassDomain"/></entry> + </row> + <row> + <entry>INATEngine::dnsProxy</entry> + <entry><xref linkend="INATEngine__DNSProxy" xreflabel="INATEngine::DNSProxy"/></entry> + </row> + <row> + <entry>INATEngine::dnsUseHostResolver</entry> + <entry><xref linkend="INATEngine__DNSUseHostResolver" xreflabel="INATEngine::DNSUseHostResolver"/></entry> + </row> + <row> + <entry>VBoxEventType::OnHostPciDevicePlug</entry> + <entry><xref linkend="VBoxEventType__OnHostPCIDevicePlug" xreflabel="VBoxEventType::OnHostPCIDevicePlug"/></entry> + </row> + <row> + <entry>ICPUChangedEvent::cpu</entry> + <entry><xref linkend="ICPUChangedEvent__CPU" xreflabel="ICPUChangedEvent::CPU"/></entry> + </row> + <row> + <entry>INATRedirectEvent::hostIp</entry> + <entry><xref linkend="INATRedirectEvent__hostIP" xreflabel="INATRedirectEvent::hostIP"/></entry> + </row> + <row> + <entry>INATRedirectEvent::guestIp</entry> + <entry><xref linkend="INATRedirectEvent__guestIP" xreflabel="INATRedirectEvent::guestIP"/></entry> + </row> + <row> + <entry>IHostPciDevicePlugEvent</entry> + <entry><xref linkend="IHostPCIDevicePlugEvent" xreflabel="IHostPCIDevicePlugEvent"/></entry> + </row> + </tbody> + </tgroup></table></para> + </listitem> + </itemizedlist> + </sect1> + + + <sect1> + <title>Incompatible API changes with version 4.1</title> + + <itemizedlist> + <listitem> + <para>The method <xref linkend="IAppliance__importMachines" + xreflabel="IAppliance::importMachines()" /> has one more parameter + now, which allows to configure the import process in more detail. + </para> + </listitem> + + <listitem> + <para>The method <xref linkend="IVirtualBox__openMedium" + xreflabel="IVirtualBox::openMedium()" /> has one more parameter + now, which allows resolving duplicate medium UUIDs without the need + for external tools.</para> + </listitem> + + <listitem> + <para>The <xref linkend="INetworkAdapter" xreflabel="INetworkAdapter"/> + interface has been cleaned up. The various methods to activate an + attachment type have been replaced by the + <xref linkend="INetworkAdapter__attachmentType" xreflabel="INetworkAdapter::attachmentType"/> 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 <xref linkend="AdditionsFacilityType" + xreflabel="AdditionsFacilityType"/>. Each facility is member of a + <xref linkend="AdditionsFacilityClass" xreflabel="AdditionsFacilityClass"/> + and has a current status indicated by <xref linkend="AdditionsFacilityStatus" + xreflabel="AdditionsFacilityStatus"/>, 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 <xref linkend="IGuest" xreflabel="IGuest"/> 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 <xref linkend="IGuest__getFacilityStatus" xreflabel="IGuest::getFacilityStatus()"/> + was added. It quickly provides a facility's status without the need to get the facility + collection with <xref linkend="IGuest__facilities" xreflabel="IGuest::facilities"/>. + </para> + </listitem> + <listitem> + <para> + The attribute <xref linkend="IGuest__facilities" xreflabel="IGuest::facilities"/> + 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 <xref linkend="IAdditionsFacility" xreflabel="IAdditionsFacility"/> + was added to represent a single facility returned by + <xref linkend="IGuest__facilities" xreflabel="IGuest::facilities"/>. + </para> + </listitem> + <listitem> + <para> + <xref linkend="AdditionsFacilityStatus" xreflabel="AdditionsFacilityStatus"/> + was added to represent a facility's overall status. + </para> + </listitem> + <listitem> + <para> + <xref linkend="AdditionsFacilityType" xreflabel="AdditionsFacilityType"/> and + <xref linkend="AdditionsFacilityClass" xreflabel="AdditionsFacilityClass"/> 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" xreflabel="Java API chapter" /> + 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 <xref + linkend="IMachine__lockMachine" + xreflabel="IMachine::lockMachine()" /> 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 <xref + linkend="IMachine__lockMachine" + xreflabel="IMachine::lockMachine()" /> 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 <xref + linkend="IMachine__launchVMProcess" + xreflabel="IMachine::launchVMProcess()" /> call. The + functionality is unchanged.</para> + </listitem> + + <listitem> + <para>The <xref linkend="SessionState" + xreflabel="SessionState" /> 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 <xref linkend="IVirtualBox__createHardDisk" + xreflabel="IVirtualBox::createHardDisk()" /> nor <xref + linkend="IVirtualBox__openMedium" + xreflabel="IVirtualBox::openMedium()" /> register media + automatically any more.</para> + </listitem> + + <listitem> + <para><xref linkend="IMachine__attachDevice" + xreflabel="IMachine::attachDevice()" /> and <xref + linkend="IMachine__mountMedium" + xreflabel="IMachine::mountMedium()" /> 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 <xref + linkend="IVirtualBox__openMedium" + xreflabel="IVirtualBox::openMedium()" />.</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 <xref linkend="ISystemProperties__infoVDSize" + xreflabel="ISystemProperties::infoVDSize" /> 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><xref linkend="IVirtualBox__createMachine" + xreflabel="IVirtualBox::createMachine()" /> 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 <xref linkend="IVirtualBox__findMachine" + xreflabel="IVirtualBox::findMachine()" />, and + <computeroutput>IMachine::getSnapshot()</computeroutput> has + been merged with <xref linkend="IMachine__findSnapshot" + xreflabel="IMachine::findSnapshot()" />.</para> + </listitem> + + <listitem> + <para><computeroutput>IVirtualBox::unregisterMachine()</computeroutput> + was replaced with <xref linkend="IMachine__unregister" + xreflabel="IMachine::unregister()" /> with additional + functionality for cleaning up machine files.</para> + </listitem> + + <listitem> + <para><computeroutput>IConsole::forgetSavedState</computeroutput> + has been renamed to <xref + linkend="IConsole__discardSavedState" + xreflabel="IConsole::discardSavedState()" />.</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 <xref linkend="IEvent" + xreflabel="events" /> 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 <xref linkend="IGuest__additionsRunLevel" + xreflabel="additionsRunLevel()" /> and <xref + linkend="IGuest__getAdditionsStatus" + xreflabel="getAdditionsStatus()" /> in order to support a more + detailed status of the current Guest Additions loading/readiness + state. <xref linkend="IGuest__additionsVersion" + xreflabel="IGuest::additionsVersion()" /> 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><xref linkend="IVirtualBox__createSharedFolder" + xreflabel="IVirtualBox::createSharedFolder()" /></para> + </listitem> + + <listitem> + <para><xref linkend="IMachine__createSharedFolder" + xreflabel="IMachine::createSharedFolder()" /></para> + </listitem> + + <listitem> + <para><xref linkend="IConsole__createSharedFolder" + xreflabel="IConsole::createSharedFolder()" /></para> + </listitem> + </itemizedlist> Also, a new property named + <computeroutput>autoMount</computeroutput> was added to the <xref + linkend="ISharedFolder" xreflabel="ISharedFolder" /> + interface.</para> + </listitem> + + <listitem> + <para>The appliance (OVF) APIs were enhanced as + follows:<itemizedlist> + <listitem> + <para><xref linkend="IMachine__export" + xreflabel="IMachine::export()" /> received an extra parameter + <computeroutput>location</computeroutput>, which is used to + decide for the disk naming.</para> + </listitem> + + <listitem> + <para><xref linkend="IAppliance__write" + xreflabel="IAppliance::write()" /> received an extra parameter + <computeroutput>manifest</computeroutput>, which can suppress + creating the manifest file on export.</para> + </listitem> + + <listitem> + <para><xref linkend="IVFSExplorer__entryList" + xreflabel="IVFSExplorer::entryList()" /> 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 <xref linkend="IVRDEServer" + xreflabel="IVRDEServer" />.</para> + </listitem> + + <listitem> + <para><computeroutput>IRemoteDisplayInfo</computeroutput> has + been renamed to <xref linkend="IVRDEServerInfo" + xreflabel="IVRDEServerInfo" />.</para> + </listitem> + + <listitem> + <para><xref linkend="IMachine__VRDEServer" + xreflabel="IMachine::VRDEServer" /> replaces + <computeroutput>VRDPServer.</computeroutput></para> + </listitem> + + <listitem> + <para><xref linkend="IConsole__VRDEServerInfo" + xreflabel="IConsole::VRDEServerInfo" /> replaces + <computeroutput>RemoteDisplayInfo</computeroutput>.</para> + </listitem> + + <listitem> + <para><xref linkend="ISystemProperties__VRDEAuthLibrary" + xreflabel="ISystemProperties::VRDEAuthLibrary" /> 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><xref linkend="IVRDEServer__setVRDEProperty" + xreflabel="IVRDEServer::setVRDEProperty" /></para> + </listitem> + + <listitem> + <para><xref linkend="IVRDEServer__getVRDEProperty" + xreflabel="IVRDEServer::getVRDEProperty" /></para> + </listitem> + + <listitem> + <para><xref linkend="IVRDEServer__VRDEProperties" + xreflabel="IVRDEServer::VRDEProperties" /></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 <xref linkend="AuthType" xreflabel="AuthType" />.</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 <xref + linkend="IMachine__getCPUProperty" + xreflabel="IMachine::getCPUProperty()" />;</para> + </listitem> + + <listitem> + <para>IMachine::setCpuProperty() is now <xref + linkend="IMachine__setCPUProperty" + xreflabel="IMachine::setCPUProperty()" />;</para> + </listitem> + + <listitem> + <para>IMachine::getCpuIdLeaf() is now <xref + linkend="IMachine__getCPUIDLeaf" + xreflabel="IMachine::getCPUIDLeaf()" />;</para> + </listitem> + + <listitem> + <para>IMachine::setCpuIdLeaf() is now <xref + linkend="IMachine__setCPUIDLeaf" + xreflabel="IMachine::setCPUIDLeaf()" />;</para> + </listitem> + + <listitem> + <para>IMachine::removeCpuIdLeaf() is now <xref + linkend="IMachine__removeCPUIDLeaf" + xreflabel="IMachine::removeCPUIDLeaf()" />;</para> + </listitem> + + <listitem> + <para>IMachine::removeAllCpuIdLeafs() is now <xref + linkend="IMachine__removeAllCPUIDLeaves" + xreflabel="IMachine::removeAllCPUIDLeaves()" />;</para> + </listitem> + + <listitem> + <para>the CpuPropertyType enum is now <xref + linkend="CPUPropertyType" + xreflabel="CPUPropertyType" />.</para> + </listitem> + + <listitem> + <para>IVirtualBoxCallback::onSnapshotDiscarded() is now + IVirtualBoxCallback::onSnapshotDeleted.</para> + </listitem> + </itemizedlist></para> + </listitem> + + <listitem> + <para>When creating a VM configuration with <xref + linkend="IVirtualBox__createMachine" + xreflabel="IVirtualBox::createMachine" />) 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 <xref + linkend="IConsole__deleteSnapshot" + xreflabel="IConsole::deleteSnapshot()" /> 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 <xref linkend="IStorageController__useHostIOCache" + xreflabel="IStorageController::useHostIOCache" />).</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><xref linkend="IMachine__querySavedThumbnailSize" + xreflabel="IMachine::querySavedThumbnailSize()" /></para> + </listitem> + + <listitem> + <para><xref linkend="IMachine__readSavedThumbnailToArray" + xreflabel="IMachine::readSavedThumbnailToArray()" /></para> + </listitem> + + <listitem> + <para><xref linkend="IMachine__querySavedScreenshotPNGSize" + xreflabel="IMachine::querySavedScreenshotPNGSize()" /></para> + </listitem> + + <listitem> + <para><xref linkend="IMachine__readSavedScreenshotPNGToArray" + xreflabel="IMachine::readSavedScreenshotPNGToArray()" /></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 <xref + linkend="IStorageController" xreflabel="IStorageController" />, + <xref linkend="IMedium" xreflabel="IMedium" />, <xref + linkend="IMediumAttachment" xreflabel="IMediumAttachment" /> and, + <xref linkend="IMachine" xreflabel="IMachine" /> 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 <xref linkend="IMedium" + xreflabel="IMedium" /> 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. <xref linkend="IMachine__attachDevice" + xreflabel="IMachine::attachDevice()" /> 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 <xref linkend="IMachine__mountMedium" + xreflabel="IMachine::mountMedium()" />.</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 <xref linkend="IMedium__state" + xreflabel="IMedium::state" xrefstyle="" /> attribute no longer + automatically performs an accessibility check; a new method <xref + linkend="IMedium__refreshState" + xreflabel="IMedium::refreshState()" /> does this. The attribute only + returns the state any more.</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 <xref + linkend="IConsole__deleteSnapshot" + xreflabel="IConsole::deleteSnapshot()" />. + IConsole::discardCurrentState and + IConsole::discardCurrentSnapshotAndState were removed; corresponding + new functionality is in <xref linkend="IConsole__restoreSnapshot" + xreflabel="IConsole::restoreSnapshot()" />. Also, when <xref + linkend="IConsole__takeSnapshot" + xreflabel="IConsole::takeSnapshot()" /> 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><xref linkend="IHost__removeHostOnlyNetworkInterface" + xreflabel="IHost::removeHostOnlyNetworkInterface()" /></para> + </listitem> + + <listitem> + <para><xref linkend="IHost__removeUSBDeviceFilter" + xreflabel="IHost::removeUSBDeviceFilter()" /></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 + <xref linkend="IMedium" xreflabel="IMedium" />.</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 <xref linkend="IVirtualBoxErrorInfo__resultCode" + xreflabel="IVirtualBoxErrorInfo::resultCode" /> 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 <xref + linkend="IConsole__powerDown" xreflabel="IConsole::powerDown" />, + and the previous method with that name was deleted. So effectively a + parameter was added.</para> + </listitem> + + <listitem> + <para>In the <xref linkend="IFramebuffer" + xreflabel="IFramebuffer" /> 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 <xref linkend="IDisplay" xreflabel="IDisplay" /> + 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 + <xref linkend="HostNetworkInterfaceMediumType" + xreflabel="HostNetworkInterfaceMediumType" /></para> + </listitem> + + <listitem> + <para>The IHostNetworkInterface::type attribute has been renamed + to <xref linkend="IHostNetworkInterface__mediumType" + xreflabel="IHostNetworkInterface::mediumType" /></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 <xref + linkend="IHost__createHostOnlyNetworkInterface" + xreflabel="createHostOnlyNetworkInterface()" /></para> + </listitem> + + <listitem> + <para>Similarly, removeHostNetworkInterface() has been renamed + to <xref linkend="IHost__removeHostOnlyNetworkInterface" + xreflabel="removeHostOnlyNetworkInterface()" /></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. <xref + linkend="ISystemProperties__defaultHardDiskFormat" + xreflabel="ISystemProperties::defaultHardDiskFormat" /> contains + the default system format.</para> + </listitem> + + <listitem> + <para>In addition, the new <xref linkend="IMedium" + xreflabel="IMedium" /> 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><xref linkend="IGuestOSType" xreflabel="IGuestOSType" /> was + extended to group operating systems into families and for 64-bit + support.</para> + </listitem> + + <listitem> + <para>The <xref linkend="IHostNetworkInterface" + xreflabel="IHostNetworkInterface" /> 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 <xref linkend="IHost__getProcessorFeature" + xreflabel="IHost::getProcessorFeature()" /> and <xref + linkend="ProcessorFeature" xreflabel="ProcessorFeature" /> + enumeration.</para> + </listitem> + + <listitem> + <para>The parameter list for <xref + linkend="IVirtualBox__createMachine" + xreflabel="IVirtualBox::createMachine()" /> was modified.</para> + </listitem> + + <listitem> + <para>Added IMachine::pushGuestProperty.</para> + </listitem> + + <listitem> + <para>New attributes in IMachine: <xref + linkend="IMachine__accelerate3DEnabled" + xreflabel="accelerate3DEnabled" />, HWVirtExVPIDEnabled, <xref + linkend="IMachine__guestPropertyNotificationPatterns" + xreflabel="guestPropertyNotificationPatterns" />, <xref + linkend="IMachine__CPUCount" xreflabel="CPUCount" />.</para> + </listitem> + + <listitem> + <para>Added <xref linkend="IConsole__powerUpPaused" + xreflabel="IConsole::powerUpPaused()" /> and <xref + linkend="IConsole__getGuestEnteredACPIMode" + xreflabel="IConsole::getGuestEnteredACPIMode()" />.</para> + </listitem> + + <listitem> + <para>Removed ResourceUsage enumeration.</para> + </listitem> + </itemizedlist> + </sect1> + </chapter> +</book> +<!-- vim: set shiftwidth=2 tabstop=2 expandtab: --> |