6728a36898fd2be125a28e84d2115d19aa4923edvboxsync<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync"http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd">
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <title>$VBOX_PRODUCT<superscript>®</superscript></title>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <subtitle>Programming Guide and Reference</subtitle>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <copyright>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </copyright>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </bookinfo>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>VirtualBox comes with comprehensive support for third-party
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync developers. This Software Development Kit (SDK) contains all the
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync documentation and interface files that are needed to write code that
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync interacts with VirtualBox.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <title>Modularity: the building blocks of VirtualBox</title>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>VirtualBox is cleanly separated into several layers, which can be
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync visualized like in the picture below:</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <mediaobject>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <imageobject>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <imagedata align="center" fileref="images/vbox-components.png"
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync width="12cm" />
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </imageobject>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </mediaobject>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>The orange area represents code that runs in kernel mode, the blue
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync area represents userspace code.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>At the bottom of the stack resides the hypervisor -- the core of
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync the virtualization engine, controlling execution of the virtual machines
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync and making sure they do not conflict with each other or whatever the
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync host computer is doing otherwise.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>On top of the hypervisor, additional internal modules provide
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync extra functionality. For example, the RDP server, which can deliver the
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync graphical output of a VM remotely to an RDP client, is a separate module
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync that is only loosely tacked into the virtual graphics device. Live
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync Migration and Resource Monitor are additional modules currently in the
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync process of being added to VirtualBox.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>What is primarily of interest for purposes of the SDK is the API
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync layer block that sits on top of all the previously mentioned blocks.
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync This API, which we call the <emphasis role="bold">"Main API"</emphasis>,
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync exposes the entire feature set of the virtualization engine below. It is
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync completely documented in this SDK Reference -- see <xref
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync linkend="sdkref_classes" /> and <xref linkend="sdkref_enums" /> -- and
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync available to anyone who wishes to control VirtualBox programmatically.
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync We chose the name "Main API" to differentiate it from other programming
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync interfaces of VirtualBox that may be publicly accessible.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>With the Main API, you can create, configure, start, stop and
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync delete virtual machines, retrieve performance statistics about running
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync VMs, configure the VirtualBox installation in general, and more. In
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync fact, internally, the front-end programs
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <computeroutput>VBoxManage</computeroutput> use nothing but this API as
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync well -- there are no hidden backdoors into the virtualization engine for
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync our own front-ends. This ensures the entire Main API is both
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync well-documented and well-tested. (The same applies to
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <computeroutput>VBoxHeadless</computeroutput>, which is not shown in the
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync image.)</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <title>Two guises of the same "Main API": the web service or
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>There are several ways in which the Main API can be called by
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync other code:<orderedlist>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>VirtualBox comes with a <emphasis role="bold">web
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync service</emphasis> that maps nearly the entire Main API. The web
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync service ships in a stand-alone executable
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync (<computeroutput>vboxwebsrv</computeroutput>) that, when running,
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync acts as an HTTP server, accepts SOAP connections and processes
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync them.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>Since the entire web service API is publicly described in a
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync web service description file (in WSDL format), you can write
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync client programs that call the web service in any language with a
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync toolkit that understands WSDL. These days, that includes most
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync programming languages that are available: Java, C++, .NET, PHP,
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync Python, Perl and probably many more.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>All of this is explained in detail in subsequent chapters of
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync this book.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>There are two ways in which you can write client code that
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync uses the web service:<orderedlist>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>For Java as well as Python, the SDK contains
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync easy-to-use classes that allow you to use the web service in
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync an object-oriented, straightforward manner. We shall refer
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync to this as the <emphasis role="bold">"object-oriented web
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>The OO bindings for Java are described in <xref
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync linkend="javaapi" />, those for Python in <xref lang=""
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </listitem>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>Alternatively, you can use the web service directly,
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync without the object-oriented client layer. We shall refer to
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>You will then have neither native object orientation
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync nor full type safety, since web services are neither
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync object-oriented nor stateful. However, in this way, you can
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync write client code even in languages for which we do not ship
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync object-oriented client code; all you need is a programming
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync language with a toolkit that can parse WSDL and generate
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync client wrapper code from it.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync linkend="raw-webservice" />, with samples for Java and
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync Perl.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </listitem>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </listitem>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>Internally, for portability and easier maintenance, the Main
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync API is implemented using the <emphasis role="bold">Component
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync Object Model (COM),</emphasis> an interprocess mechanism for
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync software components originally introduced by Microsoft for
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync Microsoft Windows. On a Windows host, VirtualBox will use
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync Microsoft COM; on other hosts where COM is not present, it ships
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync with XPCOM, a free software implementation of COM originally
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync created by the Mozilla project for their browsers.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>So, if you are familiar with COM and the C++ programming
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync language (or with any other programming language that can handle
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync COM/XPCOM objects, such as Java, Visual Basic or C#), then you can
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync use the COM/XPCOM API directly. VirtualBox comes with all
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync necessary files and documentation to build fully functional COM
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync applications. For an introduction, please see <xref
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>The VirtualBox front-ends (the graphical user interfaces as
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync well as the command line), which are all written in C++, use
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync COM/XPCOM to call the Main API. Technically, the web service is
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync another front-end to this COM API, mapping almost all of it to
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync SOAP clients.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </listitem>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>If you wonder which way to choose, here are a few
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync comparisons:<table>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <title>Comparison web service vs. COM/XPCOM</title>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <entry><emphasis role="bold">Web service</emphasis></entry>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <entry><emphasis role="bold">COM/XPCOM</emphasis></entry>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <entry><emphasis role="bold">Pro:</emphasis> Easy to use with
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync Java and Python with the object-oriented web service;
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync extensive support even with other languages (C++, .NET, PHP,
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync Perl and others)</entry>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <entry><emphasis role="bold">Con:</emphasis> Usable from
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync languages where COM bridge available (most languages on
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync Windows platform, Python and C++ on other hosts)</entry>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <entry><emphasis role="bold">Pro:</emphasis> Client can be on
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync remote machine</entry>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <entry><emphasis role="bold">Con: </emphasis>Client must be on
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync the same host where virtual machine is executed</entry>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <entry><emphasis role="bold">Con: </emphasis>Significant
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync overhead due to XML marshalling over the wire for each method
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync call</entry>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <entry><emphasis role="bold">Pro: </emphasis>Relatively low
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync invocation overhead</entry>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>In the following chapters, we will describe the different ways in
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync which to program VirtualBox, starting with the method that is easiest to
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync use and then increase complexity as we go along.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>Web services are a particular type of programming interface.
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync Whereas, with "normal" programming, a program calls an application
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync programming interface (API) defined by another program or the operating
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync system and both sides of the interface have to agree on the calling
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync convention and, in most cases, use the same programming language, web
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync services use Internet standards such as HTTP and XML to
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync communicate.<footnote>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>In some ways, web services promise to deliver the same thing
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync as CORBA and DCOM did years ago. However, while these previous
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync technologies relied on specific binary protocols and thus proved to
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync be difficult to use between diverging platforms, web services
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync circumvent these incompatibilities by using text-only standards like
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync HTTP and XML. On the downside (and, one could say, typical of things
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync related to XML), a lot of standards are involved before a web
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync service can be implemented. Many of the standards invented around
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync XML are used one way or another. As a result, web services are slow
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync and verbose, and the details can be incredibly messy. The relevant
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync standards here are called SOAP and WSDL, where SOAP describes the
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync format of the messages that are exchanged (an XML document wrapped
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync in an HTTP header), and WSDL is an XML format that describes a
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync complete API provided by a web service. WSDL in turn uses XML Schema
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync to describe types, which is not exactly terse either. However, as
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync you will see from the samples provided in this chapter, the
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync VirtualBox web service shields you from these details and is easy to
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync use.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>In order to successfully use a web service, a number of things are
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync required -- primarily, a web service accepting connections; service
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync descriptions; and then a client that connects to that web service. The
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync connections are governed by the SOAP standard, which describes how
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync messages are to be exchanged between a service and its clients; the
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync service descriptions are governed by WSDL.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>In the case of VirtualBox, this translates into the following
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync three components:<orderedlist>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>The VirtualBox web service (the "server"): this is the
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <computeroutput>vboxwebsrv</computeroutput> executable shipped
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync with VirtualBox. Once you start this executable (which acts as a
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync HTTP server on a specific TCP/IP port), clients can connect to the
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync web service and thus control a VirtualBox installation.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </listitem>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>VirtualBox also comes with WSDL files that describe the
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync services provided by the web service. You can find these files in
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync the <computeroutput>sdk/bindings/webservice/</computeroutput>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync directory. These files are understood by the web service toolkits
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync that are shipped with most programming languages and enable you to
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync easily access a web service even if you don't use our
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync object-oriented client layers. VirtualBox is shipped with
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync pregenerated web service glue code for several languages (Python,
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync Perl, Java).</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </listitem>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>A client that connects to the web service in order to
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync control the VirtualBox installation.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>Unless you play with some of the samples shipped with
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync VirtualBox, this needs to be written by you.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </listitem>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>The web service ships in an stand-alone executable,
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <computeroutput>vboxwebsrv</computeroutput>, that, when running, acts as
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync a HTTP server, accepts SOAP connections and processes them -- remotely
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync or from the same machine.<note>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>The web service executable is not contained with the
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync VirtualBox SDK, but instead ships with the standard VirtualBox
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync binary package for your specific platform. Since the SDK contains
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync only platform-independent text files and documentation, the binaries
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync are instead shipped with the platform-specific packages. For this
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync reason the information how to run it as a service is included in the
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync VirtualBox documentation.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>The <computeroutput>vboxwebsrv</computeroutput> program, which
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync implements the web service, is a text-mode (console) program which,
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync after being started, simply runs until it is interrupted with Ctrl-C or
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync a kill command.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>Once the web service is started, it acts as a front-end to the
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync VirtualBox installation of the user account that it is running under. In
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync other words, if the web service is run under the user account of
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <computeroutput>user1</computeroutput>, it will see and manipulate the
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync virtual machines and other data represented by the VirtualBox data of
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync that user (for example, on a Linux machine, under
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <computeroutput>/home/user1/.VirtualBox</computeroutput>; see the
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync VirtualBox User Manual for details on where this data is stored).</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>The web service supports the following command line
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync options:</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <itemizedlist>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <computeroutput>-h</computeroutput>): print a brief summary of
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync command line options.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </listitem>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para><computeroutput>--background</computeroutput> (or
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <computeroutput>-b</computeroutput>): run the web service as a
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync background daemon. This option is not supported on Windows
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync hosts.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </listitem>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <computeroutput>-H</computeroutput>): This specifies the host to
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync bind to and defaults to "localhost".</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </listitem>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <computeroutput>-p</computeroutput>): This specifies which port to
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync bind to on the host and defaults to 18083.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </listitem>
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync <computeroutput>-s</computeroutput>): This enables SSL support.</para>
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync </listitem>
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync <para><computeroutput>--keyfile</computeroutput> (or
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync <computeroutput>-K</computeroutput>): This specifies the file name
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync containing the server private key and the certificate. This is a
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync mandatory parameter if SSL is enabled.</para>
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync </listitem>
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync <para><computeroutput>--passwordfile</computeroutput> (or
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync <computeroutput>-a</computeroutput>): This specifies the file name
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync containing the password for the server private key. If unspecified
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync or an empty string is specified this is interpreted as an empty
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync password (i.e. the private key is not protected by a password). If
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync the file name <computeroutput>-</computeroutput> is specified then
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync then the password is read from the standard input stream, otherwise
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync from the specified file. The user is responsible for appropriate
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync access rights to protect the confidential password.</para>
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync </listitem>
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync <para><computeroutput>--cacert</computeroutput> (or
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync <computeroutput>-c</computeroutput>): This specifies the file name
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync containing the CA certificate appropriate for the server
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync certificate.</para>
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync </listitem>
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync <para><computeroutput>--capath</computeroutput> (or
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync <computeroutput>-C</computeroutput>): This specifies the directory
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync containing several CA certificates appropriate for the server
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync certificate.</para>
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync </listitem>
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync <para><computeroutput>--dhfile</computeroutput> (or
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync <computeroutput>-D</computeroutput>): This specifies the file name
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync containing the DH key. Alternatively it can contain the number of
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync bits of the DH key to generate. If left empty, RSA is used.</para>
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync </listitem>
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync <para><computeroutput>--randfile</computeroutput> (or
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync <computeroutput>-r</computeroutput>): This specifies the file name
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync containing the seed for the random number generator. If left empty,
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync an operating system specific source of the seed.</para>
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync </listitem>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para><computeroutput>--timeout</computeroutput> (or
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <computeroutput>-t</computeroutput>): This specifies the session
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync timeout, in seconds, and defaults to 300 (five minutes). A web
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync service client that has logged on but makes no calls to the web
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync service will automatically be disconnected after the number of
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync seconds specified here, as if it had called the
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <computeroutput>IWebSessionManager::logoff()</computeroutput>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync method provided by the web service itself.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>It is normally vital that each web service client call this
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync method, as the web service can accumulate large amounts of memory
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync when running, especially if a web service client does not properly
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync release managed object references. As a result, this timeout value
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync should not be set too high, especially on machines with a high
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync load on the web service, or the web service may eventually deny
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync service.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </listitem>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para><computeroutput>--check-interval</computeroutput> (or
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <computeroutput>-i</computeroutput>): This specifies the interval
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync in which the web service checks for timed-out clients, in seconds,
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync and defaults to 5. This normally does not need to be
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync changed.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </listitem>
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync <para><computeroutput>--threads</computeroutput> (or
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync <computeroutput>-T</computeroutput>): This specifies the maximum
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync number or worker threads, and defaults to 100. This normally does
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync not need to be changed.</para>
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync </listitem>
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync <para><computeroutput>--keepalive</computeroutput> (or
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync <computeroutput>-k</computeroutput>): This specifies the maximum
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync number of requests which can be sent in one web service connection,
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync and defaults to 100. This normally does not need to be changed.</para>
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync </listitem>
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync <para><computeroutput>--authentication</computeroutput> (or
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync <computeroutput>-A</computeroutput>): This specifies the desired
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync web service authentication method. If the parameter is not
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync specified or the empty string is specified it does not change the
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync authentication method, otherwise it is set to the specified value.
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync Using this parameter is a good measure against accidental
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync misconfiguration, as the web service ensures periodically that it
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync isn't changed.</para>
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync </listitem>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para><computeroutput>--verbose</computeroutput> (or
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync <computeroutput>-v</computeroutput>): Normally, the web service
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync outputs only brief messages to the console each time a request is
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync served. With this option, the web service prints much more detailed
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync data about every request and the COM methods that those requests
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync are mapped to internally, which can be useful for debugging client
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync programs.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </listitem>
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync <para><computeroutput>--pidfile</computeroutput> (or
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync <computeroutput>-P</computeroutput>): Name of the PID file which is
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync created when the daemon was started.</para>
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync </listitem>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para><computeroutput>--logfile</computeroutput> (or
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <computeroutput><file></computeroutput>: If this is
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync specified, the web service not only prints its output to the
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync console, but also writes it to the specified file. The file is
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync created if it does not exist; if it does exist, new output is
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync appended to it. This is useful if you run the web service
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync unattended and need to debug problems after they have
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync occurred.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </listitem>
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync <para><computeroutput>--logrotate</computeroutput> (or
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync <computeroutput>-R</computeroutput>): Number of old log files to
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync keep, defaults to 10. Log rotation is disabled if set to 0.</para>
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync </listitem>
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync <para><computeroutput>--logsize</computeroutput> (or
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync <computeroutput>-S</computeroutput>): Maximum size of log file in
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync bytes, defaults to 100MB. Log rotation is triggered if the file
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync grows beyond this limit.</para>
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync </listitem>
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync <para><computeroutput>--loginterval</computeroutput> (or
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync <computeroutput>-I</computeroutput>): Maximum time interval to be
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync put in a log file before rotation is triggered, in seconds, and
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync defaults to one day.</para>
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync </listitem>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </itemizedlist>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>As opposed to the COM/XPCOM variant of the Main API, a client
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync that wants to use the web service must first log on by calling the
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <computeroutput>IWebsessionManager::logon()</computeroutput> API (see
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <xref linkend="IWebsessionManager__logon" />) that is specific to the
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync web service. Logon is necessary for the web service to be stateful;
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync internally, it maintains a session for each client that connects to
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>The <computeroutput>IWebsessionManager::logon()</computeroutput>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync API takes a user name and a password as arguments, which the web
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync service then passes to a customizable authentication plugin that
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync performs the actual authentication.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>For testing purposes, it is recommended that you first disable
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync authentication with this command:<screen>VBoxManage setproperty websrvauthlibrary null</screen></para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>This will cause all logons to succeed, regardless of user
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync name or password. This should of course not be used in a
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync production environment.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </warning>Generally, the mechanism by which clients are
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync authenticated is configurable by way of the
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <computeroutput>VBoxManage</computeroutput> command:</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para><screen>VBoxManage setproperty websrvauthlibrary default|null|<library></screen></para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>This way you can specify any shared object/dynamic link module
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync that conforms with the specifications for VirtualBox external
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync authentication modules as laid out in section <emphasis
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync role="bold">VRDE authentication</emphasis> of the VirtualBox User
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync Manual; the web service uses the same kind of modules as the
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync VirtualBox VRDE server. For technical details on VirtualBox external
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync authentication modules see <xref linkend="vbox-auth" /></para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>By default, after installation, the web service uses the
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync VBoxAuth module that ships with VirtualBox. This module uses PAM on
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync Linux hosts to authenticate users. Any valid username/password
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync combination is accepted, it does not have to be the username and
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync password of the user running the web service daemon. Unless
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <computeroutput>vboxwebsrv</computeroutput> runs as root, PAM
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync authentication can fail, because sometimes the file
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <computeroutput>/etc/shadow</computeroutput>, which is used by PAM, is
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync not readable. On most Linux distribution PAM uses a suid root helper
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync internally, so make sure you test this before deploying it. One can
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync override this behavior by setting the environment variable
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <computeroutput>VBOX_PAM_ALLOW_INACTIVE</computeroutput> which will
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync suppress failures when unable to read the shadow password file. Please
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync use this variable carefully, and only if you fully understand what
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync you're doing.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>The Main API described in <xref linkend="sdkref_classes" /> and
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <xref linkend="sdkref_enums" /> is mostly identical in all the supported
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync programming environments which have been briefly mentioned in the
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync introduction of this book. As a result, the Main API's general concepts
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync described in <xref linkend="concepts" /> are the same whether you use the
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync object-oriented web service (OOWS) for JAX-WS or a raw web service
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync connection via, say, Perl, or whether you use C++ COM bindings.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>Some things are different depending on your environment, however.
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync These differences are explained in this chapter.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <title>Using the object-oriented web service (OOWS)</title>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>As explained in <xref linkend="webservice-or-com" />, VirtualBox
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync ships with client-side libraries for Java, Python and PHP that allow you
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync to use the VirtualBox web service in an intuitive, object-oriented way.
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync These libraries shield you from the client-side complications of managed
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync object references and other implementation details that come with the
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync VirtualBox web service. (If you are interested in these complications,
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync have a look at <xref linkend="raw-webservice" />).</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>We recommend that you start your experiments with the VirtualBox
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync web service by using our object-oriented client libraries for JAX-WS, a
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync web service toolkit for Java, which enables you to write code to
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync interact with VirtualBox in the simplest manner possible.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>As "interfaces", "attributes" and "methods" are COM concepts,
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync please read the documentation in <xref linkend="sdkref_classes" /> and
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <xref linkend="sdkref_enums" /> with the following notes in mind.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>The OOWS bindings attempt to map the Main API as closely as
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync possible to the Java, Python and PHP languages. In other words, objects
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync are objects, interfaces become classes, and you can call methods on
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync objects as you would on local objects.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>The main difference remains with attributes: to read an attribute,
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync call a "getXXX" method, with "XXX" being the attribute name with a
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync capitalized first letter. So when the Main API Reference says that
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <computeroutput>IMachine</computeroutput> has a "name" attribute (see
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <xref linkend="IMachine__name" xreflabel="IMachine::name" />), call
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <computeroutput>getName()</computeroutput> on an IMachine object to
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync obtain a machine's name. Unless the attribute is marked as read-only in
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync the documentation, there will also be a corresponding "set"
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync method.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <title>The object-oriented web service for JAX-WS</title>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>JAX-WS is a powerful toolkit by Sun Microsystems to build both
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync server and client code with Java. It is part of Java 6 (JDK 1.6), but
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync can also be obtained separately for Java 5 (JDK 1.5). The VirtualBox
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync SDK comes with precompiled OOWS bindings working with both Java 5 and
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>The following sections explain how to get the JAX-WS sample code
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync running and explain a few common practices when using the JAX-WS
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync object-oriented web service.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>Since JAX-WS is already integrated into Java 6, no additional
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync preparations are needed for Java 6.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>If you are using Java 5 (JDK 1.5.x), you will first need to
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync download and install an external JAX-WS implementation, as Java 5
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync does not support JAX-WS out of the box; for example, you can
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync download one from here: <ulink
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync 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>.
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync Then perform the installation (<computeroutput>java -jar
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <title>Getting started: running the sample code</title>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>To run the OOWS for JAX-WS samples that we ship with the SDK,
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync perform the following steps: <orderedlist>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>Open a terminal and change to the directory where the
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync JAX-WS samples reside.<footnote>
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync <computeroutput>sdk/bindings/glue/java/</computeroutput>.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </footnote> Examine the header of
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <computeroutput>Makefile</computeroutput> to see if the
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync supplied variables (Java compiler, Java executable) and a few
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync other details match your system settings.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </listitem>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>To start the VirtualBox web service, open a second
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync terminal and change to the directory where the VirtualBox
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync executables are located. Then type:<screen>/vboxwebsrv -v</screen></para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>The web service now waits for connections and will run
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync until you press Ctrl+C in this second terminal. The -v
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync argument causes it to log all connections to the terminal.
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync (See <xref linkend="runvboxwebsrv" os="" /> for details on how
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync to run the web service.)</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </listitem>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>Back in the first terminal and still in the samples
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync directory, to start a simple client example just type:<screen>make run16</screen></para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>if you're on a Java 6 system; on a Java 5 system, run
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <computeroutput>make run15</computeroutput> instead.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>This should work on all Unix-like systems such as Linux
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync and Solaris. For Windows systems, use commands similar to what
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync is used in the Makefile.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>This will compile the
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <computeroutput>clienttest.java</computeroutput> code on the
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync first call and then execute the resulting
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <computeroutput>clienttest</computeroutput> class to show the
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync locally installed VMs (see below).</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </listitem>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>The <computeroutput>clienttest</computeroutput> sample
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync imitates a few typical command line tasks that
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <computeroutput>VBoxManage</computeroutput>, VirtualBox's regular
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync command-line front-end, would provide (see the VirtualBox User
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync Manual for details). In particular, you can run:<itemizedlist>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync vms</computeroutput>: show the virtual machines that are
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync registered locally.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </listitem>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync hostinfo</computeroutput>: show various information about the
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync host this VirtualBox installation runs on.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </listitem>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <vmname|uuid></computeroutput>: start the given virtual
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync machine.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </listitem>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>The <computeroutput>clienttest.java</computeroutput> sample
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync code illustrates common basic practices how to use the VirtualBox
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync OOWS for JAX-WS, which we will explain in more detail in the
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync following chapters.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>Before a web service client can do anything useful, two
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync objects need to be created, as can be seen in the
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <computeroutput>clienttest</computeroutput> constructor:<orderedlist>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>An instance of <xref linkend="IWebsessionManager"
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync xreflabel="IWebsessionManager" />, which is an interface
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync provided by the web service to manage "web sessions" -- that
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync is, stateful connections to the web service with persistent
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync objects upon which methods can be invoked.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>In the OOWS for JAX-WS, the IWebsessionManager class
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync must be constructed explicitly, and a URL must be provided in
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync the constructor that specifies where the web service (the
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync server) awaits connections. The code in
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <computeroutput>clienttest.java</computeroutput> connects to
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync "http://localhost:18083/", which is the default.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>The port number, by default 18083, must match the port
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync number given to the
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <computeroutput>vboxwebsrv</computeroutput> command line; see
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </listitem>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync linkend="IWebsessionManager__logon"
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync xreflabel="IWebsessionManager::logon()" />, which is the first
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync call that actually communicates with the server. This
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync authenticates the client with the web service and returns an
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync xreflabel="IVirtualBox" />, the most fundamental interface of
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync the VirtualBox web service, from which all other functionality
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync can be derived.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>If logon doesn't work, please take another look at <xref
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </listitem>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>The current OOWS for JAX-WS has certain memory management
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync related limitations. When you no longer need an object, call its
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync xreflabel="IManagedObjectRef::release()" /> method explicitly, which
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync frees appropriate managed reference, as is required by the raw
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync web service; see <xref linkend="managed-object-references" /> for
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync details. This limitation may be reconsidered in a future version of
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync the VirtualBox SDK.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <title>The object-oriented web service for Python</title>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>VirtualBox comes with two flavors of a Python API: one for web
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync service, discussed here, and one for the COM/XPCOM API discussed in
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <xref linkend="pycom" />. The client code is mostly similar, except
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync for the initialization part, so it is up to the application developer
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync to choose the appropriate technology. Moreover, a common Python glue
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync layer exists, abstracting out concrete platform access details, see
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>As indicated in <xref linkend="webservice-or-com" />, the
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync COM/XPCOM API gives better performance without the SOAP overhead, and
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync does not require a web server to be running. On the other hand, the
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync COM/XPCOM Python API requires a suitable Python bridge for your Python
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync installation (VirtualBox ships the most important ones for each
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync platform<footnote>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>On On Mac OS X only the Python versions bundled with the OS
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync are officially supported. This means Python 2.3 for 10.4, Python
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync 2.5 for 10.5 and Python 2.5 and 2.6 for 10.6.</para>
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync </footnote>). On Windows, you can use the Main API from Python if the Win32 extensions
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync package for Python<footnote>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync url="http://sourceforge.net/project/showfiles.php?group_id=78018">http://sourceforge.net/project/showfiles.php?group_id=78018</ulink>.</para>
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync </footnote> is installed. Version of Python Win32 extensions earlier than 2.16 are known to have bugs,
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync leading to issues with VirtualBox Python bindings, and also some early builds of Python 2.5 for Windows have issues with
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync reporting platform name on some Windows versions, so please make sure to use latest available Python
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync and Win32 extensions.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>The VirtualBox OOWS for Python relies on the Python ZSI SOAP
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync implementation (see <ulink
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync url="http://pywebsvcs.sourceforge.net/zsi.html">http://pywebsvcs.sourceforge.net/zsi.html</ulink>),
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync which you will need to install locally before trying the examples.
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync Most Linux distributions come with package for ZSI, such as
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <computeroutput>python-zsi</computeroutput> in Ubuntu.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>To get started, open a terminal and change to the
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <computeroutput>bindings/glue/python/sample</computeroutput>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync directory, which contains an example of a simple interactive shell
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync able to control a VirtualBox instance. The shell is written using the
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync API layer, thereby hiding different implementation details, so it is
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync actually an example of code share among XPCOM, MSCOM and web services.
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync If you are interested in how to interact with the web services layer
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync directly, have a look at
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <computeroutput>install/vboxapi/__init__.py</computeroutput> which
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync contains the glue layer for all target platforms (i.e. XPCOM, MSCOM
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync and web services).</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>To start the shell, perform the following commands: <screen>/opt/VirtualBox/vboxwebsrv -t 0
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync # start web service with object autocollection disabled
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync # your VirtualBox installation directory
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync # where you've extracted the SDK
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync/vboxshell.py -w </screen>See <xref linkend="vboxshell" /> for more
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync details on the shell's functionality. For you, as a VirtualBox
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync application developer, the vboxshell sample could be interesting as an
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync example of how to write code targeting both local and remote cases
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync (COM/XPCOM and SOAP). The common part of the shell is the same -- the
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync only difference is how it interacts with the invocation layer. You can
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync use the <computeroutput>connect</computeroutput> shell command to
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync connect to remote VirtualBox servers; in this case you can skip
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync starting the local web server.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <title>The object-oriented web service for PHP</title>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>VirtualBox also comes with object-oriented web service (OOWS)
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync wrappers for PHP5. These wrappers rely on the PHP SOAP
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync Extension<footnote>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>See <ulink url="???">http://www.php.net/soap</ulink>.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </footnote>, which can be installed by configuring PHP with
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <computeroutput>--enable-soap</computeroutput>.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <title>Using the raw web service with any language</title>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>The following examples show you how to use the raw web service,
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync without the object-oriented client-side code that was described in the
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync previous chapter.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>Generally, when reading the documentation in <xref
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync linkend="sdkref_classes" /> and <xref linkend="sdkref_enums" />, due to
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync the limitations of SOAP and WSDL lined out in <xref
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync linkend="rawws-conventions" />, please have the following notes in
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync mind:</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>Any COM method call becomes a <emphasis role="bold">plain
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync function call</emphasis> in the raw web service, with the object
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync as an additional first parameter (before the "real" parameters
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync listed in the documentation). So when the documentation says that
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync the <computeroutput>IVirtualBox</computeroutput> interface
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync supports the <computeroutput>createMachine()</computeroutput>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync method (see <xref linkend="IVirtualBox__createMachine"
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync xreflabel="IVirtualBox::createMachine()" />), the web service
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync operation is
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <computeroutput>IVirtualBox_createMachine(...)</computeroutput>,
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync and a managed object reference to an
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <computeroutput>IVirtualBox</computeroutput> object must be passed
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync as the first argument.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </listitem>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>For <emphasis role="bold">attributes</emphasis> in
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync interfaces, there will be at least one "get" function; there will
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync also be a "set" function, unless the attribute is "readonly". The
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync attribute name will be appended to the "get" or "set" prefix, with
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync a capitalized first letter. So, the "version" readonly attribute
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync of the <computeroutput>IVirtualBox</computeroutput> interface can
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync be retrieved by calling
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <computeroutput>IVirtualBox_getVersion(vbox)</computeroutput>,
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync with <computeroutput>vbox</computeroutput> being the VirtualBox
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync object.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </listitem>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>Whenever the API documentation says that a method (or an
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync attribute getter) returns an <emphasis
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync role="bold">object</emphasis>, it will returned a managed object
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync reference in the web service instead. As said above, managed
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync object references should be released if the web service client
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync does not log off again immediately!</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </listitem>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <title>Raw web service example for Java with Axis</title>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>Axis is an older web service toolkit created by the Apache
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync foundation. If your distribution does not have it installed, you can
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync get a binary from <ulink
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync url="http://www.apache.org">http://www.apache.org</ulink>. The
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync following examples assume that you have Axis 1.4 installed.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>The VirtualBox SDK ships with an example for Axis that, again,
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync is called <computeroutput>clienttest.java</computeroutput> and that
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync imitates a few of the commands of
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <computeroutput>VBoxManage</computeroutput> over the wire.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>Then perform the following steps:<orderedlist>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>Create a working directory somewhere. Under your
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync VirtualBox installation directory, find the
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <computeroutput>sdk/webservice/samples/java/axis/</computeroutput>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync directory and copy the file
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <computeroutput>clienttest.java</computeroutput> to your working
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync directory.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </listitem>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>Open a terminal in your working directory. Execute the
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync following command:<screen> java org.apache.axis.wsdl.WSDL2Java /path/to/vboxwebService.wsdl</screen></para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>The <computeroutput>vboxwebService.wsdl</computeroutput>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync file should be located in the
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync directory.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>If this fails, your Apache Axis may not be located on your
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync system classpath, and you may have to adjust the CLASSPATH
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync environment variable. Something like this:<screen>export CLASSPATH="/path-to-axis-1_4/lib/*":$CLASSPATH</screen></para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>Use the directory where the Axis JAR files are located.
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync Mind the quotes so that your shell passes the "*" character to
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync the java executable without expanding. Alternatively, add a
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync corresponding <computeroutput>-classpath</computeroutput>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync argument to the "java" call above.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>If the command executes successfully, you should see an
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync "org" directory with subdirectories containing Java source files
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync in your working directory. These classes represent the
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync interfaces that the VirtualBox web service offers, as described
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync by the WSDL file.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>This is the bit that makes using web services so
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync attractive to client developers: if a language's toolkit
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync understands WSDL, it can generate large amounts of support code
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync automatically. Clients can then easily use this support code and
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync can be done with just a few lines of code.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </listitem>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>Next, compile the
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <computeroutput>clienttest.java</computeroutput> source:<screen>javac clienttest.java </screen></para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>This should yield a "clienttest.class" file.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </listitem>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>To start the VirtualBox web service, open a second
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync terminal and change to the directory where the VirtualBox
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync executables are located. Then type:<screen>/vboxwebsrv -v</screen></para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>The web service now waits for connections and will run
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync until you press Ctrl+C in this second terminal. The -v argument
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync causes it to log all connections to the terminal. (See <xref
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync linkend="runvboxwebsrv" os="" /> for details on how to run the
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync web service.)</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </listitem>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>Back in the original terminal where you compiled the Java
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync source, run the resulting binary, which will then connect to the
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync web service:<screen>java clienttest</screen></para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>The client sample will connect to the web service (on
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync localhost, but the code could be changed to connect remotely if
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync the web service was running on a different machine) and make a
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync number of method calls. It will output the version number of
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync your VirtualBox installation and a list of all virtual machines
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync that are currently registered (with a bit of seemingly random
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync data, which will be explained later).</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </listitem>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>We also ship a small sample for Perl. It uses the SOAP::Lite
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync perl module to communicate with the VirtualBox web service.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <computeroutput>sdk/bindings/webservice/perl/lib/</computeroutput>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync directory contains a pre-generated Perl module that allows for
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync communicating with the web service from Perl. You can generate such a
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync module yourself using the "stubmaker" tool that comes with SOAP::Lite,
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync but since that tool is slow as well as sometimes unreliable, we are
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync shipping a working module with the SDK for your convenience.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>If SOAP::Lite is not yet installed on your system, you
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync will need to install the package first. On Debian-based systems,
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync the package is called
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <computeroutput>libsoap-lite-perl</computeroutput>; on Gentoo,
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync it's <computeroutput>dev-perl/SOAP-Lite</computeroutput>.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </listitem>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>Open a terminal in the
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <computeroutput>sdk/bindings/webservice/perl/samples/</computeroutput>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync directory.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </listitem>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>To start the VirtualBox web service, open a second
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync terminal and change to the directory where the VirtualBox
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync executables are located. Then type:<screen>/vboxwebsrv -v</screen></para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>The web service now waits for connections and will run
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync until you press Ctrl+C in this second terminal. The -v argument
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync causes it to log all connections to the terminal. (See <xref
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync linkend="runvboxwebsrv" os="" /> for details on how to run the
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync web service.)</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </listitem>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>In the first terminal with the Perl sample, run the
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync clienttest.pl script:<screen>perl -I /lib clienttest.pl</screen></para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </listitem>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <title>Programming considerations for the raw web service</title>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>If you use the raw web service, you need to keep a number of
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync things in mind, or you will sooner or later run into issues that are
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync not immediately obvious. By contrast, the object-oriented client-side
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync libraries described in <xref linkend="glue" /> take care of these
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync things automatically and thus greatly simplify using the web
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync service.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>If you are familiar with other web services, you may find the
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync VirtualBox web service to behave a bit differently to accommodate
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync for the fact that VirtualBox web service more or less maps the
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync VirtualBox Main COM API. The following main differences had to be
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync taken care of:<itemizedlist>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>Web services, as expressed by WSDL, are not
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync object-oriented. Even worse, they are normally stateless (or,
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync in web services terminology, "loosely coupled"). Web service
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync operations are entirely procedural, and one cannot normally
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync make assumptions about the state of a web service between
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync function calls.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>In particular, this normally means that you cannot work
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync on objects in one method call that were created by another
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync call.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </listitem>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>By contrast, the VirtualBox Main API, being expressed in
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync COM, is object-oriented and works entirely on objects, which
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync are grouped into public interfaces, which in turn have
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync attributes and methods associated with them.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </listitem>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </itemizedlist> For the VirtualBox web service, this results in
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync three fundamental conventions:<orderedlist>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>All <emphasis role="bold">function names</emphasis> in
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync the VirtualBox web service consist of an interface name and a
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync method name, joined together by an underscore. This is because
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync there are only functions ("operations") in WSDL, but no
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync classes, interfaces, or methods.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>In addition, all calls to the VirtualBox web service
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync (except for logon, see below) take a <emphasis
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync role="bold">managed object reference</emphasis> as the first
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync argument, representing the object upon which the underlying
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync method is invoked. (Managed object references are explained in
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync detail below; see <xref
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>So, when one would normally code, in the pseudo-code of
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync an object-oriented language, to invoke a method upon an
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync object:<screen>IMachine machine;
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>In the VirtualBox web service, this looks something like
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync this (again, pseudo-code):<screen>IMachineRef machine;
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </listitem>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>To make the web service stateful, and objects persistent
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync between method calls, the VirtualBox web service introduces a
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <emphasis role="bold">session manager</emphasis> (by way of
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync xreflabel="IWebsessionManager" /> interface), which manages
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync object references. Any client wishing to interact with the web
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync service must first log on to the session manager and in turn
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync receives a managed object reference to an object that supports
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync the <xref linkend="IVirtualBox" xreflabel="IVirtualBox" />
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync interface (the basic interface in the Main API).</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </listitem>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>In other words, as opposed to other web services, <emphasis
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync role="bold">the VirtualBox web service is both object-oriented and
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <title>Example: A typical web service client session</title>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>A typical short web service session to retrieve the version
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync number of the VirtualBox web service (to be precise, the underlying
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync Main API version number) looks like this:<orderedlist>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>A client logs on to the web service by calling <xref
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync linkend="IWebsessionManager__logon"
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync xreflabel="IWebsessionManager::logon()" /> with a valid user
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync name and password. See <xref linkend="websrv_authenticate" />
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync for details about how authentication works.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </listitem>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>On the server side,
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <computeroutput>vboxwebsrv</computeroutput> creates a session,
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync which persists until the client calls <xref
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync linkend="IWebsessionManager__logoff"
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync xreflabel="IWebsessionManager::logoff()" /> or the session
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync times out after a configurable period of inactivity (see <xref
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>For the new session, the web service creates an instance
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync of <xref linkend="IVirtualBox" xreflabel="IVirtualBox" />.
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync This interface is the most central one in the Main API and
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync allows access to all other interfaces, either through
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync attributes or method calls. For example, IVirtualBox contains
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync a list of all virtual machines that are currently registered
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync (as they would be listed on the left side of the VirtualBox
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync main program).</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>The web service then creates a managed object reference
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync for this instance of IVirtualBox and returns it to the calling
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync client, which receives it as the return value of the logon
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync call. Something like this:</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <screen>string oVirtualBox;
6728a36898fd2be125a28e84d2115d19aa4923edvboxsyncoVirtualBox = webservice.IWebsessionManager_logon("user", "pass");</screen>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>(The managed object reference "oVirtualBox" is just a
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync string consisting of digits and dashes. However, it is a
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync string with a meaning and will be checked by the web service.
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync For details, see below. As hinted above, <xref
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync linkend="IWebsessionManager__logon"
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync xreflabel="IWebsessionManager::logon()" /> is the
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <emphasis>only</emphasis> operation provided by the web
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync service which does not take a managed object reference as the
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync first argument!)</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </listitem>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>The VirtualBox Main API documentation says that the
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <computeroutput>IVirtualBox</computeroutput> interface has a
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <xref linkend="IVirtualBox__version" xreflabel="version" />
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync attribute, which is a string. For each attribute, there is a
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync "get" and a "set" method in COM, which maps to according
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync operations in the web service. So, to retrieve the "version"
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync attribute of this <computeroutput>IVirtualBox</computeroutput>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync object, the web service client does this:<screen>string version;
6728a36898fd2be125a28e84d2115d19aa4923edvboxsyncversion = webservice.IVirtualBox_getVersion(oVirtualBox);
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>And it will print
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync "$VBOX_VERSION_MAJOR.$VBOX_VERSION_MINOR.$VBOX_VERSION_BUILD".</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </listitem>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync linkend="IWebsessionManager__logoff"
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync xreflabel="IWebsessionManager::logoff()" /> with the
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync VirtualBox managed object reference. This will clean up all
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync allocated resources.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </listitem>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>To a web service client, a managed object reference looks like
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync a string: two 64-bit hex numbers separated by a dash. This string,
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync however, represents a COM object that "lives" in the web service
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync process. The two 64-bit numbers encoded in the managed object
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync reference represent a session ID (which is the same for all objects
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync in the same web service session, i.e. for all objects after one
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync logon) and a unique object ID within that session.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>Managed object references are created in two
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync situations:<orderedlist>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync linkend="IWebsessionManager__logon"
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>Upon logon, the websession manager creates one instance
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync of <xref linkend="IVirtualBox" xreflabel="IVirtualBox" /> and
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync xreflabel="ISession" /> representing the web service session.
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync This can be retrieved using <xref
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync linkend="IWebsessionManager__getSessionObject"
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync xreflabel="IWebsessionManager::getSessionObject()" />.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync linkend="IVirtualBox" xreflabel="IVirtualBox" /> object, which
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync is shared between all sessions and clients, as it is a COM
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync singleton. However, each session receives its own managed
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync object reference to it. The <xref linkend="ISession"
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync xreflabel="ISession" /> object, however, is created and
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync destroyed for each session.)</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </listitem>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>Whenever a web service clients invokes an operation
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync whose COM implementation creates COM objects.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>For example, <xref linkend="IVirtualBox__createMachine"
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync xreflabel="IVirtualBox::createMachine()" /> creates a new
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync instance of <xref linkend="IMachine" xreflabel="IMachine" />;
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync the COM object returned by the COM method call is then wrapped
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync into a managed object reference by the web server, and this
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync reference is returned to the web service client.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </listitem>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>Internally, in the web service process, each managed object
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync reference is simply a small data structure, containing a COM pointer
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync to the "real" COM object, the web session ID and the object ID. This
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync structure is allocated on creation and stored efficiently in hashes,
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync so that the web service can look up the COM object quickly whenever
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync a web service client wishes to make a method call. The random
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync session ID also ensures that one web service client cannot intercept
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync the objects of another.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>Managed object references are not destroyed automatically and
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync must be released by explicitly calling <xref
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync linkend="IManagedObjectRef__release"
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync xreflabel="IManagedObjectRef::release()" />. This is important, as
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync otherwise hundreds or thousands of managed object references (and
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync corresponding COM objects, which can consume much more memory!) can
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync pile up in the web service process and eventually cause it to deny
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync service.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>To reiterate: The underlying COM object, which the reference
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync points to, is only freed if the managed object reference is
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync released. It is therefore vital that web service clients properly
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync clean up after the managed object references that are returned to
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync them.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync linkend="IWebsessionManager__logoff"
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync xreflabel="IWebsessionManager::logoff()" />, all managed object
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync references created during the session are automatically freed. For
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync short-lived sessions that do not create a lot of objects, logging
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync off may therefore be sufficient, although it is certainly not "best
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync practice".</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <title>Some more detail about web service operation</title>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>Whenever a client makes a call to a web service, this
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync involves a complicated procedure internally. These calls are
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync remote procedure calls. Each such procedure call typically
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync consists of two "message" being passed, where each message is a
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync plain-text HTTP request with a standard HTTP header and a special
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync XML document following. This XML document encodes the name of the
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync procedure to call and the argument names and values passed to
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>To give you an idea of what such a message looks like,
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync assuming that a web service provides a procedure called
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync "SayHello", which takes a string "name" as an argument and returns
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync "Hello" with a space and that name appended, the request message
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync could look like this:</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para><screen><?xml version="1.0" encoding="UTF-8"?>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync<SOAP-ENV:Envelope
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/"
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync xmlns:test="http://test/">
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync<SOAP-ENV:Body>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <test:SayHello>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <name>Peter</name>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </test:SayHello>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </SOAP-ENV:Body>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync</SOAP-ENV:Envelope></screen>A similar message -- the "response" message
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync -- would be sent back from the web service to the client,
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync containing the return value "Hello Peter".</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>Most programming languages provide automatic support to
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync generate such messages whenever code in that programming language
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync makes such a request. In other words, these programming languages
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync allow for writing something like this (in pseudo-C++ code):</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para><screen>webServiceClass service("localhost", 18083); // server and port
6728a36898fd2be125a28e84d2115d19aa4923edvboxsyncstring result = service.SayHello("Peter"); // invoke remote procedure</screen>and
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync would, for these two pseudo-lines, automatically perform these
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync steps:</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>prepare a connection to a web service running on port
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync 18083 of "localhost";</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </listitem>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>for the <computeroutput>SayHello()</computeroutput>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync function of the web service, generate a SOAP message like in
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync the above example by encoding all arguments of the remote
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync procedure call (which could involve all kinds of type
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync conversions and complex marshalling for arrays and
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync structures);</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </listitem>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>connect to the web service via HTTP and send that
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync message;</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </listitem>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>wait for the web service to send a response
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync message;</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </listitem>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>decode that response message and put the return value
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync of the remote procedure into the "result" variable.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </listitem>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>In the above explanations about SOAP, it was left open how
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync the programming language learns about how to translate function
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync calls in its own syntax into proper SOAP messages. In other words,
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync the programming language needs to know what operations the web
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync service supports and what types of arguments are required for the
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync operation's data in order to be able to properly serialize and
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync deserialize the data to and from the web service. For example, if
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync a web service operation expects a number in "double" floating
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync point format for a particular parameter, the programming language
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync cannot send to it a string instead.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>For this, the Web Service Definition Language (WSDL) was
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync invented, another XML substandard that describes exactly what
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync operations the web service supports and, for each operation, which
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync parameters and types are needed with each request and response
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync message. WSDL descriptions can be incredibly verbose, and one of
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync the few good things that can be said about this standard is that
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync it is indeed supported by most programming languages.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>So, if it is said that a programming language "supports" web
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync services, this typically means that a programming language has
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync support for parsing WSDL files and somehow integrating the remote
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync procedure calls into the native language syntax -- for example,
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync like in the Java sample shown in <xref
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>For details about how programming languages support web
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync services, please refer to the documentation that comes with the
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync individual languages. Here are a few pointers:</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <orderedlist>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>For <emphasis role="bold">C++,</emphasis> among many
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync others, the gSOAP toolkit is a good option. Parts of gSOAP are
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync also used in VirtualBox to implement the VirtualBox web
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync service.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </listitem>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>For <emphasis role="bold">Java,</emphasis> there are
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync several implementations already described in this document
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </listitem>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para><emphasis role="bold">Perl</emphasis> supports WSDL via
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync the SOAP::Lite package. This in turn comes with a tool called
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <computeroutput>stubmaker.pl</computeroutput> that allows you
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync to turn any WSDL file into a Perl package that you can import.
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync (You can also import any WSDL file "live" by having it parsed
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync every time the script runs, but that can take a while.) You
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync can then code (again, assuming the above example):<screen>my $result = servicename->sayHello("Peter");</screen></para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>A sample that uses SOAP::Lite was described in <xref
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </listitem>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </orderedlist>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>If you do not require <emphasis>remote</emphasis> procedure calls
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync such as those offered by the VirtualBox web service, and if you know
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync Python or C++ as well as COM, you might find it preferable to program
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync VirtualBox's Main API directly via COM.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>COM stands for "Component Object Model" and is a standard
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync originally introduced by Microsoft in the 1990s for Microsoft Windows.
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync It allows for organizing software in an object-oriented way and across
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync processes; code in one process may access objects that live in another
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync process.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>COM has several advantages: it is language-neutral, meaning that
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync even though all of VirtualBox is internally written in C++, programs
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync written in other languages could communicate with it. COM also cleanly
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync separates interface from implementation, so that external programs need
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync not know anything about the messy and complicated details of VirtualBox
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync internals.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>On a Windows host, all parts of VirtualBox will use the COM
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync functionality that is native to Windows. On other hosts (including
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync Linux), VirtualBox comes with a built-in implementation of XPCOM, as
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync originally created by the Mozilla project, which we have enhanced to
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync support interprocess communication on a level comparable to Microsoft
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync COM. Internally, VirtualBox has an abstraction layer that allows the
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync same VirtualBox code to work both with native COM as well as our XPCOM
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync implementation.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>On Windows, Python scripts can use COM and VirtualBox interfaces
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync to control almost all aspects of virtual machine execution. As an
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync example, use the following commands to instantiate the VirtualBox
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync object and start a VM: <screen>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync vbox = win32com.client.Dispatch("VirtualBox.VirtualBox")
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync session = win32com.client.Dispatch("VirtualBox.Session")
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync mach = vbox.findMachine("uuid or name of machine to start")
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync progress = mach.launchVMProcess(session, "gui", "")
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </screen> Also, see
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <computeroutput>/bindings/glue/python/samples/vboxshell.py</computeroutput>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync for more advanced usage scenarious. However, unless you have specific
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync requirements, we strongly recommend to use the generic glue layer
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync described in the next section to access MS COM objects.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>As different wrappers ultimately provide access to the same
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync underlying API, and to simplify porting and development of Python
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync application using the VirtualBox Main API, we developed a common glue
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync layer that abstracts out most platform-specific details from the
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync application and allows the developer to focus on application logic.
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync The VirtualBox installer automatically sets up this glue layer for the
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync system default Python install. See below for details on how to set up
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync the glue layer if you want to use a different Python
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync installation.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>In this layer, the class
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <computeroutput>VirtualBoxManager</computeroutput> hides most
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync platform-specific details. It can be used to access both the local
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync (COM) and the web service based API. The following code can be used by
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync an application to use the glue layer.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <screen># This code assumes vboxapi.py from VirtualBox distribution
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync# being in PYTHONPATH, or installed system-wide
6728a36898fd2be125a28e84d2115d19aa4923edvboxsyncfrom vboxapi import VirtualBoxManager
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync# This code initializes VirtualBox manager with default style
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync# and parameters
6728a36898fd2be125a28e84d2115d19aa4923edvboxsyncvirtualBoxManager = VirtualBoxManager(None, None)
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync# Alternatively, one can be more verbose, and initialize
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync# glue with web service backend, and provide authentication
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync# information
6728a36898fd2be125a28e84d2115d19aa4923edvboxsyncvirtualBoxManager = VirtualBoxManager("WEBSERVICE",
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync 'user':'me',
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync 'password':'secret'}) </screen>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>We supply the <computeroutput>VirtualBoxManager</computeroutput>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync constructor with 2 arguments: style and parameters. Style defines
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync which bindings style to use (could be "MSCOM", "XPCOM" or
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync "WEBSERVICE"), and if set to <computeroutput>None</computeroutput>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync defaults to usable platform bindings (MS COM on Windows, XPCOM on
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync other platforms). The second argument defines parameters, passed to
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync the platform-specific module, as we do in the second example, where we
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync pass username and password to be used to authenticate against the web
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync service.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>After obtaining the
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <computeroutput>VirtualBoxManager</computeroutput> instance, one can
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync perform operations on the IVirtualBox class. For example, the
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync following code will a start virtual machine by name or ID:</para>
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync <screen>from vboxapi import VirtualBoxManager
9562e2d410460d8fae06fa24297f172fee1d1995vboxsyncmgr = VirtualBoxManager(None, None)
6728a36898fd2be125a28e84d2115d19aa4923edvboxsyncname = "Linux"
9562e2d410460d8fae06fa24297f172fee1d1995vboxsyncprogress = mach.launchVMProcess(session, "gui", "")
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync Following code will print all registered machines and their log folders
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync <screen>from vboxapi import VirtualBoxManager
9562e2d410460d8fae06fa24297f172fee1d1995vboxsyncmgr = VirtualBoxManager(None, None)
9562e2d410460d8fae06fa24297f172fee1d1995vboxsyncfor m in mgr.getArray(vbox, 'machines'):
9562e2d410460d8fae06fa24297f172fee1d1995vboxsyncprint "Machine '%s' logs in '%s'" %(m.name, m.logFolder)
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync <para>Code above demonstartes cross-platform access to array properties
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync (certain limitations prevent one from using
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <computeroutput>vbox.machines</computeroutput> to access a list of
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync available virtual machines in case of XPCOM), and a mechanism of
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync uniform session creation and closing
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync (<computeroutput>mgr.mgr.getSessionObject()</computeroutput>).</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>In case you want to use the glue layer with a different Python
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync installation, use these steps in a shell to add the necessary
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync files:</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>C++ is the language that VirtualBox itself is written in, so C++
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync is the most direct way to use the Main API -- but it is not
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync necessarily the easiest, as using COM and XPCOM has its own set of
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync complications.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>VirtualBox ships with sample programs that demonstrate how to
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync use the Main API to implement a number of tasks on your host platform.
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync These samples can be found in the
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <computeroutput>/bindings/xpcom/samples</computeroutput> directory for
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync Linux, Mac OS X and Solaris and
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <computeroutput>/bindings/mscom/samples</computeroutput> for Windows.
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync The two samples are actually different, because the one for Windows
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync uses native COM, whereas the other uses our XPCOM implementation, as
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync described above.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>Since COM and XPCOM are conceptually very similar but vary in
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync the implementation details, we have created a "glue" layer that
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync shields COM client code from these differences. All VirtualBox uses is
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync this glue layer, so the same code written once works on both Windows
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync hosts (with native COM) as well as on other hosts (with our XPCOM
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync implementation). It is recommended to always use this glue code
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync instead of using the COM and XPCOM APIs directly, as it is very easy
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync to make your code completely independent from the platform it is
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync running on.<!-- A third sample,
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <computeroutput>tstVBoxAPIGlue.cpp</computeroutput>, illustrates how to
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync use the glue layer.
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>In order to encapsulate platform differences between Microsoft
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync COM and XPCOM, the following items should be kept in mind when using
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync the glue layer:</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync setters.</emphasis> COM has the notion of "attributes" in
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync interfaces, which roughly compare to C++ member variables in
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync classes. The difference is that for each attribute declared in
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync an interface, COM automatically provides a "get" method to
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync return the attribute's value. Unless the attribute has been
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync marked as "readonly", a "set" attribute is also provided.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>To illustrate, the IVirtualBox interface has a "version"
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync attribute, which is read-only and of the "wstring" type (the
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync standard string type in COM). As a result, you can call the
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync "get" method for this attribute to retrieve the version number
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync of VirtualBox.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>Unfortunately, the implementation differs between COM and
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync XPCOM. Microsoft COM names the "get" method like this:
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <computeroutput>get_Attribute()</computeroutput>, whereas XPCOM
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync uses this syntax:
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <computeroutput>GetAttribute()</computeroutput> (and accordingly
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync for "set" methods). To hide these differences, the VirtualBox
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync glue code provides the
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <computeroutput>COMGETTER(attrib)</computeroutput> and
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <computeroutput>COMSETTER(attrib)</computeroutput> macros. So,
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <computeroutput>COMGETTER(version)()</computeroutput> (note, two
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync pairs of brackets) expands to
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <computeroutput>get_Version()</computeroutput> on Windows and
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <computeroutput>GetVersion()</computeroutput> on other
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync platforms.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </listitem>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para><emphasis role="bold">Unicode conversions.</emphasis>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync While the rest of the modern world has pretty much settled on
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync encoding strings in UTF-8, COM, unfortunately, uses UCS-16
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync encoding. This requires a lot of conversions, in particular
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync between the VirtualBox Main API and the Qt GUI, which, like the
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync rest of Qt, likes to use UTF-8.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>To facilitate these conversions, VirtualBox provides the
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <computeroutput>com::Utf8Str</computeroutput> classes, which
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync support all kinds of conversions back and forth.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </listitem>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para><emphasis role="bold">COM autopointers.</emphasis>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync Possibly the greatest pain of using COM -- reference counting --
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync is alleviated by the
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <computeroutput>ComPtr<></computeroutput> template
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync provided by the <computeroutput>ptr.h</computeroutput> file in
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync the glue layer.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </listitem>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>Both VirtualBox client programs and frontends should
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync periodically perform processing of the main event queue, and do that
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync on the application's main thread. In case of a typical GUI Windows/Mac
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync OS application this happens automatically in the GUI's dispatch loop.
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync However, for CLI only application, the appropriate actions have to be
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync taken. For C++ applications, the VirtualBox SDK provided glue method
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync int EventQueue::processEventQueue(uint32_t cMsTimeout)
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </screen> can be used for both blocking and non-blocking operations.
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync For the Python bindings, a common layer provides the method <screen>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>Things get somewhat more complicated for situations where an
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync application using VirtualBox cannot directly control the main event
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync loop and the main event queue is separated from the event queue of the
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync programming librarly (for example in case of Qt on Unix platforms). In
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync such a case, the application developer is advised to use a
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync platform/toolkit specific event injection mechanism to force event
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync queue checks either based on periodical timer events delivered to the
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync main thread, or by using custom platform messages to notify the main
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync thread when events are available. See the VBoxSDL and Qt (VirtualBox)
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync frontends as examples.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <title>Visual Basic and Visual Basic Script (VBS) on Windows
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync hosts</title>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>On Windows hosts, one can control some of the VirtualBox Main
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync API functionality from VBS scripts, and pretty much everything from
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync Visual Basic programs.<footnote>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>The difference results from the way VBS treats COM
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync safearrays, which are used to keep lists in the Main API. VBS
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync expects every array element to be a
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <computeroutput>VARIANT</computeroutput>, which is too strict a
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync limitation for any high performance API. We may lift this
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync restriction for interface APIs in a future version, or
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync alternatively provide conversion APIs.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>VBS is scripting language available in any recent Windows
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync environment. As an example, the following VBS code will print
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync VirtualBox version: <screen>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync set vb = CreateObject("VirtualBox.VirtualBox")
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync Wscript.Echo "VirtualBox version " & vb.version
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </screen> See
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <computeroutput>bindings/mscom/vbs/sample/vboxinfo.vbs</computeroutput>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync for the complete sample.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>Visual Basic is a popular high level language capable of
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync accessing COM objects. The following VB code will iterate over all
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync available virtual machines:<screen>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync vb = CreateObject("VirtualBox.VirtualBox")
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync machines = ""
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </screen> See
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <computeroutput>bindings/mscom/vb/sample/vboxinfo.vb</computeroutput>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync for the complete sample.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>This section currently applies to Linux hosts only.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>Starting with version 2.2, VirtualBox offers a C binding for the
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync XPCOM API.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>The C binding provides a layer enabling object creation, method
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync invocation and attribute access from C.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>The following sections describe how to use the C binding in a
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync C program.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>For Linux, a sample program is provided which demonstrates use
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync of the C binding to initialize XPCOM, get handles for VirtualBox and
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync Session objects, make calls to list and start virtual machines, and
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync uninitialize resources when done. The program uses the VBoxGlue
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync library to open the C binding layer during runtime.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>The sample program
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <computeroutput>tstXPCOMCGlue</computeroutput> is located in the bin
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync directory and can be run without arguments. It lists registered
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync machines on the host along with some additional information and ask
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync for a machine to start. The source for this program is available in
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <computeroutput>sdk/bindings/xpcom/cbinding/samples/</computeroutput>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync directory. The source for the VBoxGlue library is available in the
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <computeroutput>sdk/bindings/xpcom/cbinding/</computeroutput>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync directory.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>Just like in C++, XPCOM needs to be initialized before it can
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync be used. The <computeroutput>VBoxCAPI_v2_5.h</computeroutput> header
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync provides the interface to the C binding. Here's how to initialize
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync XPCOM:</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsyncPCVBOXXPCOM g_pVBoxFuncs = NULL;
6728a36898fd2be125a28e84d2115d19aa4923edvboxsyncIVirtualBox *vbox = NULL;
6728a36898fd2be125a28e84d2115d19aa4923edvboxsyncISession *session = NULL;
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync * VBoxGetXPCOMCFunctions() is the only function exported by
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync * VBoxXPCOMC.so and the only one needed to make virtualbox
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync * work with C. This functions gives you the pointer to the
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync * function table (g_pVBoxFuncs).
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync * Once you get the function table, then how and which functions
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync * to use is explained below.
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync * g_pVBoxFuncs->pfnComInitialize does all the necessary startup
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync * action and provides us with pointers to vbox and session handles.
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync * It should be matched by a call to g_pVBoxFuncs->pfnComUninitialize()
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync * when done.
6728a36898fd2be125a28e84d2115d19aa4923edvboxsyncg_pVBoxFuncs = VBoxGetXPCOMCFunctions(VBOX_XPCOMC_VERSION);
6728a36898fd2be125a28e84d2115d19aa4923edvboxsyncg_pVBoxFuncs->pfnComInitialize(&vbox, &session);</screen>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>If either <computeroutput>vbox</computeroutput> or
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <computeroutput>NULL</computeroutput>, initialization failed and the
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync XPCOM API cannot be used.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>Method invocation is straightforward. It looks pretty much
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync like the C++ way, augmented with an extra indirection due to
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync accessing the vtable and passing a pointer to the object as the
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync first argument to serve as the <computeroutput>this</computeroutput>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync pointer.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>Using the C binding, all method invocations return a numeric
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync result code.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>If an interface is specified as returning an object, a pointer
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync to a pointer to the appropriate object must be passed as the last
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync argument. The method will then store an object pointer in that
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync location.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>In other words, to call an object's method what you need
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <screen>IObject *object;
6728a36898fd2be125a28e84d2115d19aa4923edvboxsyncnsresult rc;
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync * Calling void IObject::method(arg, ...)
6728a36898fd2be125a28e84d2115d19aa4923edvboxsyncrc = object->vtbl->Method(object, arg, ...);
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync * Calling IFoo IObject::method(arg, ...)
6728a36898fd2be125a28e84d2115d19aa4923edvboxsyncrc = object->vtbl->Method(object, args, ..., &foo);</screen>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>As a real-world example of a method invocation, let's call
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync xreflabel="IMachine::launchVMProcess" /> which returns an
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync IProgress object. Note again that the method name is
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync capitalized.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <screen>IProgress *progress;
9562e2d410460d8fae06fa24297f172fee1d1995vboxsyncrc = vbox->vtbl->LaunchVMProcess(
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync machine, /* this */
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync session, /* arg 1 */
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync sessionType, /* arg 2 */
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync env, /* arg 3 */
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync &progress /* Out */
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>A construct similar to calling non-void methods is used to
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync access object attributes. For each attribute there exists a getter
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync method, the name of which is composed of
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <computeroutput>Get</computeroutput> followed by the capitalized
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync attribute name. Unless the attribute is read-only, an analogous
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <computeroutput>Set</computeroutput> method exists. Let's apply
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync these rules to read the <xref linkend="IVirtualBox__revision"
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync xreflabel="IVirtualBox::revision" /> attribute.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>Using the <computeroutput>IVirtualBox</computeroutput> handle
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <computeroutput>vbox</computeroutput> obtained above, calling its
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <computeroutput>GetRevision</computeroutput> method looks like
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync this:</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <screen>PRUint32 rev;
6728a36898fd2be125a28e84d2115d19aa4923edvboxsyncrc = vbox->vtbl->GetRevision(vbox, &rev);
6728a36898fd2be125a28e84d2115d19aa4923edvboxsyncif (NS_SUCCEEDED(rc))
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync printf("Revision: %u\n", (unsigned)rev);
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>All objects with their methods and attributes are documented
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>When dealing with strings you have to be aware of a string's
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync encoding and ownership.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>Internally, XPCOM uses UTF-16 encoded strings. A set of
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync conversion functions is provided to convert other encodings to and
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync from UTF-16. The type of a UTF-16 character is
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <computeroutput>PRUnichar</computeroutput>. Strings of UTF-16
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync characters are arrays of that type. Most string handling functions
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync take pointers to that type. Prototypes for the following conversion
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync functions are declared in
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <computeroutput>VBoxCAPI_v2_5.h</computeroutput>.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <title>Conversion of UTF-16 to and from UTF-8</title>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <screen>int (*pfnUtf16ToUtf8)(const PRUnichar *pwszString, char **ppszString);
6728a36898fd2be125a28e84d2115d19aa4923edvboxsyncint (*pfnUtf8ToUtf16)(const char *pszString, PRUnichar **ppwszString);
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>The ownership of a string determines who is responsible for
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync releasing resources associated with the string. Whenever XPCOM
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync creates a string, ownership is transferred to the caller. To avoid
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync resource leaks, the caller should release resources once the
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync string is no longer needed.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>Uninitialization is performed by
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <computeroutput>g_pVBoxFuncs->pfnComUninitialize().</computeroutput>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync If your program can exit from more than one place, it is a good idea
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync to install this function as an exit handler with Standard C's
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <computeroutput>atexit()</computeroutput> just after calling
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <computeroutput>g_pVBoxFuncs->pfnComInitialize()</computeroutput>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync#include <stdio.h>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync * Make sure g_pVBoxFuncs->pfnComUninitialize() is called at exit, no
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync * matter if we return from the initial call to main or call exit()
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync * somewhere else. Note that atexit registered functions are not
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync * called upon abnormal termination, i.e. when calling abort() or
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync * signal(). Separate provisions must be taken for these cases.
6728a36898fd2be125a28e84d2115d19aa4923edvboxsyncif (atexit(g_pVBoxFuncs->pfnComUninitialize()) != 0) {
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync fprintf(stderr, "failed to register g_pVBoxFuncs->pfnComUninitialize()\n");
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync exit(EXIT_FAILURE);
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>Another idea would be to write your own <computeroutput>void
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync myexit(int status)</computeroutput> function, calling
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <computeroutput>g_pVBoxFuncs->pfnComUninitialize()</computeroutput>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync followed by the real <computeroutput>exit()</computeroutput>, and
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync use it instead of <computeroutput>exit()</computeroutput> throughout
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync your program and at the end of
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>If you expect the program to be terminated by a signal (e.g.
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync user types CTRL-C sending SIGINT) you might want to install a signal
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync handler setting a flag noting that a signal was sent and then
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <computeroutput>g_pVBoxFuncs->pfnComUninitialize()</computeroutput>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync later on (usually <emphasis>not</emphasis> from the handler itself
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>That said, if a client program forgets to call
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <computeroutput>g_pVBoxFuncs->pfnComUninitialize()</computeroutput>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync before it terminates, there is a mechanism in place which will
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync eventually release references held by the client. You should not
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync rely on this, however.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>A program using the C binding has to open the library during
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync runtime using the help of glue code provided and as shown in the
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync example <computeroutput>tstXPCOMCGlue.c</computeroutput>.
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync Compilation and linking can be achieved, e.g., with a makefile
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync fragment similar to</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <screen># Where is the XPCOM include directory?
6728a36898fd2be125a28e84d2115d19aa4923edvboxsyncINCS_XPCOM = /include
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync# Where is the glue code directory?
6728a36898fd2be125a28e84d2115d19aa4923edvboxsyncGLUE_DIR = ..
6728a36898fd2be125a28e84d2115d19aa4923edvboxsyncGLUE_INC = -I..
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync#Compile Glue Library
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync $(CC) $(CFLAGS) $(INCS_XPCOM) $(GLUE_INC) -o $@ -c $<
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync $(CC) $(CFLAGS) $(INCS_XPCOM) $(GLUE_INC) -o $@ -c $<
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync $(CC) -o $@ $^ -ldl</screen>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <title>Basic VirtualBox concepts; some examples</title>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>The following explains some basic VirtualBox concepts such as the
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync VirtualBox object, sessions and how virtual machines are manipulated and
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync launched using the Main API. The coding examples use a pseudo-code style
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync closely related to the object-oriented web service (OOWS) for JAX-WS.
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync Depending on which environment you are using, you will need to adjust the
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync examples.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <title>Obtaining basic machine information. Reading attributes</title>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>Any program using the Main API will first need access to the
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync global VirtualBox object (see <xref linkend="IVirtualBox"
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync xreflabel="IVirtualBox" />), from which all other functionality of the
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync API is derived. With the OOWS for JAX-WS, this is returned from the
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync xreflabel="IWebsessionManager::logon()" /> call.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>To enumerate virtual machines, one would look at the "machines"
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync array attribute in the VirtualBox object (see <xref
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync linkend="IVirtualBox__machines" xreflabel="IVirtualBox::machines" />).
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync This array contains all virtual machines currently registered with the
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync host, each of them being an instance of <xref linkend="IMachine"
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync xreflabel="IMachine" />. From each such instance, one can query
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync additional information, such as the UUID, the name, memory, operating
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync system and more by looking at the attributes; see the attributes list in
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <xref linkend="IMachine" xreflabel="IMachine documentation" />.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>As mentioned in the preceding chapters, depending on your
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync programming environment, attributes are mapped to corresponding "get"
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync and (if the attribute is not read-only) "set" methods. So when the
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync documentation says that IMachine has a "<xref linkend="IMachine__name"
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync xreflabel="name" />" attribute, this means you need to code something
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync like the following to get the machine's name:<screen>IMachine machine = ...;
6728a36898fd2be125a28e84d2115d19aa4923edvboxsyncString name = machine.getName();</screen>Boolean attribute getters can
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync sometimes be called <computeroutput>isAttribute()</computeroutput> due
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync to JAX-WS naming conventions.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>As said in the previous section, to read a machine's attribute,
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync one invokes the corresponding "get" method. One would think that to
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync change settings of a machine, it would suffice to call the corresponding
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync "set" method -- for example, to set a VM's memory to 1024 MB, one would
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync call <computeroutput>setMemorySize(1024)</computeroutput>. Try that, and
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync you will get an error: "The machine is not mutable."</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>So unfortunately, things are not that easy. VirtualBox is a
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync complicated environment in which multiple processes compete for possibly
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync the same resources, especially machine settings. As a result, machines
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync must be "locked" before they can either be modified or started. This is
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync to prevent multiple processes from making conflicting changes to a
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync machine: it should, for example, not be allowed to change the memory
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync size of a virtual machine while it is running. (You can't add more
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync memory to a real computer while it is running either, at least not to an
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync ordinary PC.) Also, two processes must not change settings at the same
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync time, or start a machine at the same time.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>These requirements are implemented in the Main API by way of
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync "sessions", in particular, the <xref linkend="ISession"
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync xreflabel="ISession" /> interface. Each process which talks to
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync VirtualBox needs its own instance of ISession. In the web service, you
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync cannot create such an object, but
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <computeroutput>vboxwebsrv</computeroutput> creates one for you when you
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync log on, which you can obtain by calling <xref
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync linkend="IWebsessionManager__getSessionObject"
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync xreflabel="IWebsessionManager::getSessionObject()" />.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>This session object must then be used like a mutex semaphore in
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync common programming environments. Before you can change machine settings,
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync you must write-lock the machine by calling <xref
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync linkend="IMachine__lockMachine" xreflabel="IMachine::lockMachine()" />
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync with your process's session object.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync linkend="ISession__machine" xreflabel="ISession::machine" /> attribute
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync contains a copy of the original IMachine object upon which the session
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync was opened, but this copy is "mutable": you can invoke "set" methods on
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>When done making the changes to the machine, you must call <xref
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync linkend="IMachine__saveSettings"
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync xreflabel="IMachine::saveSettings()" />, which will copy the changes you
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync have made from your "mutable" machine back to the real machine and write
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync them out to the machine settings XML file. This will make your changes
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync permanent.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>Finally, it is important to always unlock the machine again, by
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync xreflabel="ISession::unlockMachine()" />. Otherwise, when the calling
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync process end, the machine will receive the "aborted" state, which can
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync lead to loss of data.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>So, as an example, the sequence to change a machine's memory to
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync 1024 MB is something like this:<screen>IWebsessionManager mgr ...;
6728a36898fd2be125a28e84d2115d19aa4923edvboxsyncIVirtualBox vbox = mgr.logon(user, pass);
6728a36898fd2be125a28e84d2115d19aa4923edvboxsyncIMachine machine = ...; // read-only machine
6728a36898fd2be125a28e84d2115d19aa4923edvboxsyncISession session = mgr.getSessionObject();
6728a36898fd2be125a28e84d2115d19aa4923edvboxsyncmachine.lockMachine(session, LockType.Write); // machine is now locked for writing
6728a36898fd2be125a28e84d2115d19aa4923edvboxsyncIMachine mutable = session.getMachine(); // obtain the mutable machine copy
6728a36898fd2be125a28e84d2115d19aa4923edvboxsyncmutable.saveSettings(); // write settings to XML
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync linkend="IMachine__launchVMProcess"
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync xreflabel="IMachine::launchVMProcess()" />. In doing so, the caller
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync instructs the VirtualBox engine to start a new process with the virtual
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync machine in it, since to the host, each virtual machine looks like a
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync single process, even if it has hundreds of its own processes inside.
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync (This new VM process in turn obtains a write lock on the machine, as
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync described above, to prevent conflicting changes from other processes;
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync this is why opening another session will fail while the VM is
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync running.)</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>Starting a machine looks something like this:<screen>IWebsessionManager mgr ...;
6728a36898fd2be125a28e84d2115d19aa4923edvboxsyncIVirtualBox vbox = mgr.logon(user, pass);
6728a36898fd2be125a28e84d2115d19aa4923edvboxsyncIMachine machine = ...; // read-only machine
6728a36898fd2be125a28e84d2115d19aa4923edvboxsyncISession session = mgr.getSessionObject();
6728a36898fd2be125a28e84d2115d19aa4923edvboxsyncIProgress prog = machine.launchVMProcess(session,
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync "gui", // session type
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync ""); // possibly environment setting
6728a36898fd2be125a28e84d2115d19aa4923edvboxsyncprog.waitForCompletion(10000); // give the process 10 secs
6728a36898fd2be125a28e84d2115d19aa4923edvboxsyncif (prog.getResultCode() != 0) // check success
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync System.out.println("Cannot launch VM!")</screen></para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>The caller's session object can then be used as a sort of remote
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync control to the VM process that was launched. It contains a "console"
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync xreflabel="ISession::console" />) with which the VM can be paused,
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync stopped, snapshotted or other things.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>In VirtualBox, "events" provide a uniform mechanism to register
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync for and consume specific events. A VirtualBox client can register an
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync "event listener" (represented by the <xref linkend="IEventListener"
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync xreflabel="IEventListener" /> interface), which will then get notified
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync by the server when an event (represented by the <xref linkend="IEvent"
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>The IEvent interface is an abstract parent interface for all
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync events that can occur in VirtualBox. The actual events that the server
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync sends out are then of one of the specific subclasses, for example <xref
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync linkend="IMachineStateChangedEvent"
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync linkend="IMediumChangedEvent" xreflabel="IMediumChangedEvent" />.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>As an example, the VirtualBox GUI waits for machine events and can
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync thus update its display when the machine state changes or machine
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync settings are modified, even if this happens in another client. This is
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync how the GUI can automatically refresh its display even if you manipulate
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync a machine from another client, for example, from VBoxManage.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>To register an event listener to listen to events, use code like
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync this:<screen>EventSource es = console.getEventSource();
6728a36898fd2be125a28e84d2115d19aa4923edvboxsyncIEventListener listener = es.createListener();
6728a36898fd2be125a28e84d2115d19aa4923edvboxsyncVBoxEventType aTypes[] = (VBoxEventType.OnMachineStateChanged);
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync // list of event types to listen for
6728a36898fd2be125a28e84d2115d19aa4923edvboxsynces.registerListener(listener, aTypes, false /* active */);
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync // register passive listener
6728a36898fd2be125a28e84d2115d19aa4923edvboxsyncIEvent ev = es.getEvent(listener, 1000);
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync // wait up to one second for event to happen
6728a36898fd2be125a28e84d2115d19aa4923edvboxsyncif (ev != null)
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync // downcast to specific event interface (in this case we have only registered
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync // for one type, otherwise IEvent::type would tell us)
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync IMachineStateChangedEvent mcse = IMachineStateChangedEvent.queryInterface(ev);
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync ... // inspect and do something
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>A graphical user interface would probably best start its own
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync thread to wait for events and then process these in a loop.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>The events mechanism was introduced with VirtualBox 3.3 and
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync replaces various callback interfaces which were called for each event in
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync the interface. The callback mechanism was not compatible with scripting
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync languages, local Java bindings and remote web services as they do not
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync support callbacks. The new mechanism with events and event listeners
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync works with all of these.</para>
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync <para>To simplify developement of application using events, concept of
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync event aggregator was introduced. Essentially it's mechanism to aggregate
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync multiple event sources into single one, and then work with this single
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync aggregated event source instead of original sources. As an example, one
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync can evaluate demo recorder in VirtualBox Python shell, shipped with SDK
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync - it records mouse and keyboard events, represented as separate event
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync sources. Code is essentially like this:<screen>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync agg = console.eventSource.createAggregator([console.keyboard.eventSource, console.mouse.eventSource])
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync agg.registerListener(listener, [ctx['global'].constants.VBoxEventType_Any], False)
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync registered = True
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync end = time.time() + dur
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync while time.time() < end:
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync ev = agg.getEvent(listener, 1000)
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync processEent(ev)
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync agg.unregisterListener(listener)</screen> Without using aggregators
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync consumer have to poll on both sources, or start multiple threads to
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync block on those sources.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>VirtualBox comes with an extensible shell, which allows you to
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync control your virtual machines from the command line. It is also a
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync nontrivial example of how to use the VirtualBox APIs from Python, for all
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>You can easily extend this shell with your own commands. Create a
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync subdirectory named <computeroutput>.VirtualBox/shexts</computeroutput>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync below your home directory and put a Python file implementing your shell
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync extension commands in this directory. This file must contain an array
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync named <computeroutput>commands</computeroutput> containing your command
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync definitions: <screen>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync commands = {
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync 'cmd1': ['Command cmd1 help', cmd1],
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync 'cmd2': ['Command cmd2 help', cmd2]
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </screen> For example, to create a command for creating hard drive
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync images, the following code can be used: <screen>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync def createHdd(ctx,args):
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync # Show some meaningful error message on wrong input
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync if (len(args) < 3):
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync print "usage: createHdd sizeM location type"
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync # Get arguments
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync size = int(args[1])
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync loc = args[2]
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync if len(args) > 3:
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync format = args[3]
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync # And provide some meaningful defaults
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync format = "vdi"
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync # Call VirtualBox API, using context's fields
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync hdd = ctx['vb'].createHardDisk(format, loc)
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync # Access constants using ctx['global'].constants
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync progress = hdd.createBaseStorage(size, ctx['global'].constants.HardDiskVariant_Standard)
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync # use standard progress bar mechanism
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync ctx['progressBar'](progress)
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync # Report errors
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync print "cannot create disk (file %s exist?)" %(loc)
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync # Give user some feedback on success too
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync print "created HDD with id: %s" %(hdd.id)
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync # 0 means continue execution, other values mean exit from the interpreter
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync commands = {
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync 'myCreateHDD': ['Create virtual HDD, createHdd size location type', createHdd]
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </screen> Just store the above text in the file
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <computeroutput>createHdd</computeroutput> (or any other meaningful name)
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync in <computeroutput>.VirtualBox/shexts/</computeroutput>. Start the
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync VirtualBox shell, or just issue the
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <computeroutput>reloadExts</computeroutput> command, if the shell is
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync already running. Your new command will now be available.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <!--$VIRTUALBOX_MAIN_API_REFERENCE-->
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>The VirtualBox Host-Guest Communication Manager (HGCM) allows a
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync guest application or a guest driver to call a host shared library. The
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync following features of VirtualBox are implemented using HGCM: <itemizedlist>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </listitem>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </listitem>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </listitem>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>The shared library contains a so called HGCM service. The guest HGCM
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync clients establish connections to the service to call it. When calling a
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync HGCM service the client supplies a function code and a number of
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync parameters for the function.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>HGCM uses the VMM virtual PCI device to exchange data between the
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync guest and the host. The guest always acts as an initiator of requests. A
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync request is constructed in the guest physical memory, which must be
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync locked by the guest. The physical address is passed to the VMM device
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync using a 32 bit <computeroutput>out edx, eax</computeroutput>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync instruction. The physical memory must be allocated below 4GB by 64 bit
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync guests.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>The host parses the request header and data and queues the request
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync for a host HGCM service. The guest continues execution and usually waits
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync on a HGCM event semaphore.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>When the request has been processed by the HGCM service, the VMM
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync device sets the completion flag in the request header, sets the HGCM
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync event and raises an IRQ for the guest. The IRQ handler signals the HGCM
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync event semaphore and all HGCM callers check the completion flag in the
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync corresponding request header. If the flag is set, the request is
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync considered completed.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>The HGCM protocol definitions are contained in the
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <computeroutput>VBox/VBoxGuest.h</computeroutput></para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>HGCM request structures contains a generic header
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync (VMMDevHGCMRequestHeader): <table>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <entry><emphasis role="bold">Name</emphasis></entry>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <entry><emphasis role="bold">Description</emphasis></entry>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <entry>Version of the header, must be set to
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <entry>HGCM return code, which will be set by the VMM
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync device.</entry>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <entry>The HGCM result code, set by the VMM device.</entry>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <itemizedlist>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </listitem>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>Fields from <computeroutput>size</computeroutput> to
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <computeroutput>reserved2</computeroutput> are a standard VMM
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync device request header, which is used for other interfaces as
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync well.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </listitem>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </itemizedlist>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>The <emphasis role="bold">type</emphasis> field indicates the
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync type of the HGCM request: <table>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <entry><emphasis role="bold">Description</emphasis></entry>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <entry>VMMDevReq_HGCMConnect
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <entry>VMMDevReq_HGCMDisconnect
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <entry>VMMDevReq_HGCMCall32
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <entry>Call a HGCM function using the 32 bit
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync interface.</entry>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <entry>VMMDevReq_HGCMCall64
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <entry>Call a HGCM function using the 64 bit
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync interface.</entry>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <entry>VMMDevReq_HGCMCancel
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <entry>Cancel a HGCM request currently being processed by a
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync host HGCM service.</entry>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>The <emphasis role="bold">flags</emphasis> field may contain:
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <entry><emphasis role="bold">Description</emphasis></entry>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <entry>VBOX_HGCM_REQ_DONE
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync (<computeroutput>0x00000001</computeroutput>)</entry>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <entry>The request has been processed by the host
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync service.</entry>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <entry>VBOX_HGCM_REQ_CANCELLED
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync (<computeroutput>0x00000002</computeroutput>)</entry>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>The connection request must be issued by the guest HGCM client
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync before it can call the HGCM service (VMMDevHGCMConnect): <table>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <entry><emphasis role="bold">Name</emphasis></entry>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <entry><emphasis role="bold">Description</emphasis></entry>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <entry>The generic HGCM request header with type equal to
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync VMMDevReq_HGCMConnect
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <entry>The type of the service location information (32
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync bit).</entry>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <entry>The service location information (128 bytes).</entry>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <entry>The client identifier assigned to the connecting
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync client by the HGCM subsystem (32 bit).</entry>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </table> The <emphasis role="bold">type</emphasis> field tells the
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync HGCM how to look for the requested service: <table>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <entry><emphasis role="bold">Description</emphasis></entry>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <entry>VMMDevHGCMLoc_LocalHost
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <entry>The requested service is a shared library located on
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync the host and the location information contains the library
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync name.</entry>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <entry>VMMDevHGCMLoc_LocalHost_Existing
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <entry>The requested service is a preloaded one and the
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync location information contains the service name.</entry>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>Currently preloaded HGCM services are hard-coded in
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync VirtualBox: <itemizedlist>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </listitem>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </listitem>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </listitem>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </listitem>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </note> There is no difference between both types of HGCM services,
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync only the location mechanism is different.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>The client identifier is returned by the host and must be used
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync in all subsequent requests by the client.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>This request disconnects the client and makes the client
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync identifier invalid (VMMDevHGCMDisconnect): <table>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <entry><emphasis role="bold">Name</emphasis></entry>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <entry><emphasis role="bold">Description</emphasis></entry>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <entry>The generic HGCM request header with type equal to
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync VMMDevReq_HGCMDisconnect
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <entry>The client identifier previously returned by the
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync connect request (32 bit).</entry>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>Calls the HGCM service entry point (VMMDevHGCMCall) using 32 bit
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync or 64 bit addresses: <table>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <entry><emphasis role="bold">Name</emphasis></entry>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <entry><emphasis role="bold">Description</emphasis></entry>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <entry>The generic HGCM request header with type equal to
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync either VMMDevReq_HGCMCall32
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync VMMDevReq_HGCMCall64
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <entry>The client identifier previously returned by the
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync connect request (32 bit).</entry>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <entry>The function code to be processed by the service (32
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync bit).</entry>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <entry>The number of following parameters (32 bit). This
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync value is 0 if the function requires no parameters.</entry>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <entry>An array of parameter description structures
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync (HGCMFunctionParameter32 or
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync HGCMFunctionParameter64).</entry>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>The 32 bit parameter description (HGCMFunctionParameter32)
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync consists of 32 bit type field and 8 bytes of an opaque value, so 12
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync bytes in total. The 64 bit variant (HGCMFunctionParameter64) consists
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync of the type and 12 bytes of a value, so 16 bytes in total.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <entry><emphasis role="bold">Type</emphasis></entry>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <entry>A 32 bit size followed by a 32 bit or 64 bit guest
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync physical address.</entry>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <entry>A 32 bit size followed by a 32 bit or 64 bit guest
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync linear address. The buffer is used both for guest to host
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync and for host to guest data.</entry>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <entry>Same as VMMDevHGCMParmType_LinAddr but the buffer is
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync used only for host to guest data.</entry>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <entry>Same as VMMDevHGCMParmType_LinAddr but the buffer is
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync used only for guest to host data.</entry>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <entry>VMMDevHGCMParmType_LinAddr_Locked (7)</entry>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <entry>Same as VMMDevHGCMParmType_LinAddr but the buffer is
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync already locked by the guest.</entry>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <entry>VMMDevHGCMParmType_LinAddr_Locked_In (1)</entry>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <entry>Same as VMMDevHGCMParmType_LinAddr_In but the buffer
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync is already locked by the guest.</entry>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <entry>VMMDevHGCMParmType_LinAddr_Locked_Out (1)</entry>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <entry>Same as VMMDevHGCMParmType_LinAddr_Out but the buffer
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync is already locked by the guest.</entry>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>This request cancels a call request (VMMDevHGCMCancel): <table>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <entry><emphasis role="bold">Name</emphasis></entry>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <entry><emphasis role="bold">Description</emphasis></entry>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <entry>The generic HGCM request header with type equal to
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync VMMDevReq_HGCMCancel
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>The guest HGCM clients can call HGCM services from both drivers
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync and applications.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>The driver interface is implemented in the VirtualBox guest
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync additions driver (VBoxGuest), which works with the VMM virtual device.
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync Drivers must use the VBox Guest Library (VBGL), which provides an API
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync for HGCM clients (<computeroutput>VBox/VBoxGuestLib.h</computeroutput>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync and <computeroutput>VBox/VBoxGuest.h</computeroutput>).</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsyncDECLVBGL(int) VbglHGCMConnect (VBGLHGCMHANDLE *pHandle, VBoxGuestHGCMConnectInfo *pData);
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync VBoxGuestHGCMConnectInfo data;
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync memset (&data, sizeof (VBoxGuestHGCMConnectInfo));
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync data.result = VINF_SUCCESS;
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync data.Loc.type = VMMDevHGCMLoc_LocalHost_Existing;
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync strcpy (data.Loc.u.host.achName, "VBoxSharedFolders");
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync rc = VbglHGCMConnect (&handle, &data);
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync if (RT_SUCCESS (rc))
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync if (RT_SUCCESS (rc))
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync /* Get the assigned client identifier. */
6728a36898fd2be125a28e84d2115d19aa4923edvboxsyncDECLVBGL(int) VbglHGCMDisconnect (VBGLHGCMHANDLE handle, VBoxGuestHGCMDisconnectInfo *pData);
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync VBoxGuestHGCMDisconnectInfo data;
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync RtlZeroMemory (&data, sizeof (VBoxGuestHGCMDisconnectInfo));
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync data.result = VINF_SUCCESS;
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync rc = VbglHGCMDisconnect (handle, &data);
6728a36898fd2be125a28e84d2115d19aa4923edvboxsyncDECLVBGL(int) VbglHGCMCall (VBGLHGCMHANDLE handle, VBoxGuestHGCMCallInfo *pData, uint32_t cbData);
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </screen> Calls a function in the service. <screen>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsynctypedef struct _VBoxSFRead
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync VBoxGuestHGCMCallInfo callInfo;
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync /** pointer, in: SHFLROOT
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync * Root handle of the mapping which name is queried.
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync HGCMFunctionParameter root;
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync /** value64, in:
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync * SHFLHANDLE of object to read from.
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync HGCMFunctionParameter handle;
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync /** value64, in:
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync * Offset to read from.
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync HGCMFunctionParameter offset;
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync HGCMFunctionParameter cb;
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync /** pointer, out:
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync * Buffer to place data to.
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync HGCMFunctionParameter buffer;
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync} VBoxSFRead;
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync/** Number of parameters */
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync#define SHFL_CPARMS_READ (5)
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync VBoxSFRead data;
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync /* The call information. */
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync data.callInfo.result = VINF_SUCCESS; /* Will be returned by HGCM. */
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync data.callInfo.u32ClientID = ulClientID; /* Client identifier. */
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync data.callInfo.u32Function = SHFL_FN_READ; /* The function code. */
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync data.callInfo.cParms = SHFL_CPARMS_READ; /* Number of parameters. */
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync /* Initialize parameters. */
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync data.root.type = VMMDevHGCMParmType_32bit;
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync data.root.u.value32 = pMap->root;
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync data.handle.type = VMMDevHGCMParmType_64bit;
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync data.offset.type = VMMDevHGCMParmType_64bit;
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync data.cb.type = VMMDevHGCMParmType_32bit;
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync data.buffer.type = VMMDevHGCMParmType_LinAddr_Out;
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync data.buffer.u.Pointer.u.linearAddr = (uintptr_t)pBuffer;
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync rc = VbglHGCMCall (handle, &data.callInfo, sizeof (data));
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync if (RT_SUCCESS (rc))
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync *pcbBuffer = data.cb.u.value32; /* This is returned by the HGCM service. */
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>Applications call the VirtualBox Guest Additions driver to
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync utilize the HGCM interface. There are IOCTL's which correspond to the
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <computeroutput>Vbgl*</computeroutput> functions: <itemizedlist>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para><computeroutput>VBOXGUEST_IOCTL_HGCM_CONNECT</computeroutput></para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </listitem>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para><computeroutput>VBOXGUEST_IOCTL_HGCM_DISCONNECT</computeroutput></para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </listitem>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para><computeroutput>VBOXGUEST_IOCTL_HGCM_CALL</computeroutput></para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </listitem>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>These IOCTL's get the same input buffer as
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <computeroutput>VbglHGCM*</computeroutput> functions and the output
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync buffer has the same format as the input buffer. The same address can
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync be used as the input and output buffers.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>For example see the guest part of shared clipboard, which runs
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync as an application and uses the HGCM interface.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>The HGCM service is a shared library with a specific set of entry
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync points. The library must export the
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <computeroutput>VBoxHGCMSvcLoad</computeroutput> entry point: <screen>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsyncextern "C" DECLCALLBACK(DECLEXPORT(int)) VBoxHGCMSvcLoad (VBOXHGCMSVCFNTABLE *ptable)
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>The service must check the
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <computeroutput>ptable->cbSize</computeroutput> and
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <computeroutput>ptable->u32Version</computeroutput> fields of the
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync input structure and fill the remaining fields with function pointers of
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync entry points and the size of the required client buffer size.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>The HGCM service gets a dedicated thread, which calls service
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync entry points synchronously, that is the service will be called again
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync only when a previous call has returned. However, the guest calls can be
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync processed asynchronously. The service must call a completion callback
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync when the operation is actually completed. The callback can be issued
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync from another thread as well.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>Service entry points are listed in the
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <computeroutput>VBox/hgcmsvc.h</computeroutput> in the
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <computeroutput>VBOXHGCMSVCFNTABLE</computeroutput> structure. <table>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <entry><emphasis role="bold">Entry</emphasis></entry>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <entry><emphasis role="bold">Description</emphasis></entry>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <entry>A client <computeroutput>u32ClientID</computeroutput>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync is connected to the service. The
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <computeroutput>pvClient</computeroutput> parameter points to
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync an allocated memory buffer which can be used by the service to
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync store the client information.</entry>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <entry>A guest client calls a service function. The
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <computeroutput>callHandle</computeroutput> must be used in
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync the VBOXHGCMSVCHELPERS::pfnCallComplete callback when the call
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync has been processed.</entry>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <entry>Called by the VirtualBox host components to perform
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync functions which should be not accessible by the guest. Usually
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync this entry point is used by VirtualBox to configure the
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync service.</entry>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <entry>The VM state is being saved and the service must save
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync relevant information using the SSM API
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync (<computeroutput>VBox/ssm.h</computeroutput>).</entry>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <entry>The VM is being restored from the saved state and the
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync service must load the saved information and be able to
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync continue operations from the saved state.</entry>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>The VirtualBox <emphasis>RDP Web Control</emphasis> (RDPWeb)
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync provides remote access to a running VM. RDPWeb is a RDP (Remote Desktop
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync Protocol) client based on Flash technology and can be used from a Web
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync browser with a Flash plugin.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>RDPWeb is embedded into a Web page and can connect to VRDP server
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync in order to displays the VM screen and pass keyboard and mouse events to
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync the VM.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>RDPWeb consists of two required components:<itemizedlist>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>Flash movie
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <computeroutput>RDPClientUI.swf</computeroutput></para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </listitem>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>JavaScript helpers
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <computeroutput>webclient.js</computeroutput></para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </listitem>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>The VirtualBox SDK contains sample HTML code
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync including:<itemizedlist>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>JavaScript library for embedding Flash content
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <computeroutput>SWFObject.js</computeroutput></para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </listitem>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>Sample HTML page
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <computeroutput>webclient3.html</computeroutput></para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </listitem>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para><computeroutput>RDPClientUI.swf</computeroutput> and
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <computeroutput>webclient.js</computeroutput> work with each other.
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync JavaScript code is responsible for a proper SWF initialization,
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync delivering mouse events to the SWF and processing resize requests from
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync the SWF. On the other hand, the SWF contains a few JavaScript callable
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync methods, which are used both from
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <computeroutput>webclient.js</computeroutput> and the user HTML
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync page.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para><computeroutput>webclient.js</computeroutput> contains helper
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync functions. In the following table ElementId refers to an HTML
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync element name or attribute, and Element to the HTML element itself.
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync HTML code<programlisting>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <div id="FlashRDP">
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </div>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync</programlisting> would have ElementId equal to FlashRDP and Element equal to
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync the div element.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <programlisting>RDPWebClient.embedSWF(SWFFileName, ElementId)</programlisting>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>Uses SWFObject library to replace the HTML element with
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync the Flash movie.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </listitem>
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync <programlisting>RDPWebClient.isRDPWebControlById(ElementId)</programlisting>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>Returns true if the given id refers to a RDPWeb Flash
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync element.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </listitem>
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync <programlisting>RDPWebClient.isRDPWebControlByElement(Element)</programlisting>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>Returns true if the given element is a RDPWeb Flash
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync element.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </listitem>
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync <programlisting>RDPWebClient.getFlashById(ElementId)</programlisting>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>Returns an element, which is referenced by the given id.
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync This function will try to resolve any element, event if it is
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync not a Flash movie.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </listitem>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <title>Flash methods callable from JavaScript</title>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para><computeroutput>RDPWebClienUI.swf</computeroutput> methods can
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync be called directly from JavaScript code on a HTML page.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <itemizedlist>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </listitem>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </listitem>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </listitem>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </listitem>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </listitem>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </itemizedlist>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para><computeroutput>RDPWebClienUI.swf</computeroutput> calls
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync JavaScript functions provided by the HTML page.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>It is necessary to include
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <computeroutput>webclient.js</computeroutput> helper script. If
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync SWFObject library is used, the
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <computeroutput>swfobject.js</computeroutput> must be also included
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync and RDPWeb flash content can be embedded to a Web page using dynamic
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync HTML. The HTML must include a "placeholder", which consists of 2
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <computeroutput>div</computeroutput> elements.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <itemizedlist>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para><computeroutput>keyboardLayout</computeroutput>,
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <computeroutput>UUID</computeroutput> properties.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </listitem>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>Support for German keyboard layout on the client.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </listitem>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </listitem>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </itemizedlist>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <itemizedlist>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para><computeroutput>webclient.js</computeroutput> is a part of
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync the distribution package.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </listitem>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para><computeroutput>lastError</computeroutput> property.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </listitem>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para><computeroutput>keyboardSendScancodes</computeroutput> and
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <computeroutput>keyboardSendCAD</computeroutput> methods.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </listitem>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </itemizedlist>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <itemizedlist>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </listitem>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </itemizedlist>
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync <title>VirtualBox external authentication modules</title>
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync <para>VirtualBox supports arbitrary external modules to perform
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync authentication. The module is used when the authentication method is set
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync to "external" for a particular VM VRDE access and the library was
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync specified with <computeroutput>VBoxManage setproperty
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync vrdeauthlibrary</computeroutput>. Web service also use the authentication
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync module which was specified with <computeroutput>VBoxManage setproperty
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync <para>This library will be loaded by the VM or web service process on
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync demand, i.e. when the first remote desktop connection is made by a client
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync or when a client that wants to use the web service logs on.</para>
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync <para>External authentication is the most flexible as the external handler
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync can both choose to grant access to everyone (like the "null"
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync authentication method would) and delegate the request to the guest
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync authentication component. When delegating the request to the guest
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync component, the handler will still be called afterwards with the option to
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync override the result.</para>
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync <para>An authentication library is required to implement exactly one entry
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync point:</para>
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync * Authentication library entry point.
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync * Parameters:
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync * szCaller The name of the component which calls the library (UTF8).
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync * pUuid Pointer to the UUID of the accessed virtual machine. Can be NULL.
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync * guestJudgement Result of the guest authentication.
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync * szUser User name passed in by the client (UTF8).
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync * szPassword Password passed in by the client (UTF8).
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync * szDomain Domain passed in by the client (UTF8).
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync * fLogon Boolean flag. Indicates whether the entry point is called
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync * for a client logon or the client disconnect.
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync * clientId Server side unique identifier of the client.
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync * Return code:
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync * AuthResultAccessDenied Client access has been denied.
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync * AuthResultAccessGranted Client has the right to use the
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync * virtual machine.
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync * AuthResultDelegateToGuest Guest operating system must
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync * authenticate the client and the
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync * library must be called again with
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync * the result of the guest
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync * authentication.
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync * Note: When 'fLogon' is 0, only pszCaller, pUuid and clientId are valid and the return
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync * code is ignored.
9562e2d410460d8fae06fa24297f172fee1d1995vboxsyncAuthResult AUTHCALL AuthEntry(
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync const char *szCaller,
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync PAUTHUUID pUuid,
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync AuthGuestJudgement guestJudgement,
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync const char *szUser,
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync const char *szPassword
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync const char *szDomain
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync int fLogon,
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync unsigned clientId)
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync /* Process request against your authentication source of choice. */
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync // if (authSucceeded(...))
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync // return AuthResultAccessGranted;
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync return AuthResultAccessDenied;
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync <para>A note regarding the UUID implementation of the
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync <computeroutput>pUuid</computeroutput> argument: VirtualBox uses a
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync consistent binary representation of UUIDs on all platforms. For this
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync reason the integer fields comprising the UUID are stored as little endian
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync values. If you want to pass such UUIDs to code which assumes that the
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync integer fields are big endian (often also called network byte order), you
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync need to adjust the contents of the UUID to e.g. achieve the same string
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync representation. The required changes are:<itemizedlist>
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync <para>reverse the order of byte 0, 1, 2 and 3</para>
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync </listitem>
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync </listitem>
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync </listitem>
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync </itemizedlist>Using this conversion you will get identical results when
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync converting the binary UUID to the string representation.</para>
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync <para>The <computeroutput>guestJudgement</computeroutput> argument
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync contains information about the guest authentication status. For the first
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync call, it is always set to
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync <computeroutput>AuthGuestNotAsked</computeroutput>. In case the
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync <computeroutput>AuthEntry</computeroutput> function returns
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync <computeroutput>AuthResultDelegateToGuest</computeroutput>, a guest
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync authentication will be attempted and another call to the
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync <computeroutput>AuthEntry</computeroutput> is made with its result. This
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync can be either granted / denied or no judgement (the guest component chose
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync for whatever reason to not make a decision). In case there is a problem
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync with the guest authentication module (e.g. the Additions are not installed
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync or not running or the guest did not respond within a timeout), the "not
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync reacted" status will be returned.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>VirtualBox can be controlled by a Java API, both locally
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync (COM/XPCOM) and from remote (SOAP) clients. As with the Python bindings,
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync a generic glue layer tries to hide all platform differences, allowing
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync for source and binary compatibility on different platforms.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>To use the Java bindings, there are certain requirements depending
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync on the platform. First of all, you need JDK 1.5 (Java 5) or later. Also
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync please make sure that the version of the VirtualBox API .jar file
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync exactly matches the version of VirtualBox you use. To avoid confusion,
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync the VirtualBox API provides versioning in the Java package name, e.g.
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync the package is named <computeroutput>org.virtualbox_3_2</computeroutput>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync for VirtualBox version 3.2. <itemizedlist>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para><emphasis role="bold">XPCOM:</emphasis> - for all platforms,
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync but Microsoft Windows. A Java bridge based on JavaXPCOM is shipped
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync with VirtualBox. The classpath must contain
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <computeroutput>vboxjxpcom.jar</computeroutput> and the
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <computeroutput>vbox.home</computeroutput> property must be set to
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync location where the VirtualBox binaries are. Please make sure that
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync the JVM bitness matches bitness of VirtualBox you use as the XPCOM
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync bridge relies on native libraries.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>Start your application like this: <programlisting>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync java -cp vboxjxpcom.jar -Dvbox.home=/opt/virtualbox MyProgram
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </listitem>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para><emphasis role="bold">COM:</emphasis> - for Microsoft
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync Windows. We rely on <computeroutput>Jacob</computeroutput> - a
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync generic Java to COM bridge - which has to be installed seperately.
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync url="http://sourceforge.net/projects/jacob-project/">http://sourceforge.net/projects/jacob-project/</ulink>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync for installation instructions. Also, the VirtualBox provided
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <computeroutput>vboxjmscom.jar</computeroutput> must be in the
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync class path.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>Start your application like this: <programlisting>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync java -cp vboxjmscom.jar;c:\jacob\jacob.jar -Djava.library.path=c:\jacob MyProgram
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </listitem>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para><emphasis role="bold">SOAP</emphasis> - all platforms. Java
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync 6 is required, as it comes with builtin support for SOAP via the
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync JAX-WS library. Also, the VirtualBox provided
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <computeroutput>vbojws.jar</computeroutput> must be in the class
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync path. In the SOAP case it's possible to create several
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync VirtualBoxManager instances to communicate with multiple
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync VirtualBox hosts.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>Start your application like this: <programlisting>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync java -cp vboxjws.jar MyProgram
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </listitem>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>Exception handling is also generalized by the generic glue layer,
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync so that all methods could throw
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <computeroutput>VBoxException</computeroutput> containing human-readable
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync text message (see <computeroutput>getMessage()</computeroutput> method)
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync along with wrapped original exception (see
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <computeroutput>getWrapped()</computeroutput> method).</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>This example shows a simple use case of the Java API. Differences
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync for SOAP vs. local version are minimal, and limited to the connection
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync setup phase (see <computeroutput>ws</computeroutput> variable). In the
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync SOAP case it's possible to create several VirtualBoxManager instances to
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync communicate with multiple VirtualBox hosts. <programlisting>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync VirtualBoxManager mgr = VirtualBoxManager.createInstance(null);
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync boolean ws = false; // or true, if we need the SOAP version
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync String url = "http://myhost:18034";
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync String user = "test";
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync String passwd = "test";
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync mgr.connect(url, user, passwd);
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync IVirtualBox vbox = mgr.getVBox();
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync System.out.println("VirtualBox version: " + vbox.getVersion() + "\n");
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync // get first VM name
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync String m = vbox.getMachines().get(0).getName();
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync System.out.println("\nAttempting to start VM '" + m + "'");
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync // start it
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync mgr.startVm(m, null, 7000);
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </programlisting> For more a complete example, see
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <computeroutput>TestVBox.java</computeroutput>, shipped with the
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync SDK.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>The sample code files shipped with the SDK are generally licensed
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync liberally to make it easy for anyone to use this code for their own
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync application code.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>The Java files under
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <computeroutput>bindings/webservice/java/jax-ws/</computeroutput> (library
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync files for the object-oriented web service) are, by contrast, licensed
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync under the GNU Lesser General Public License (LGPL) V2.1.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <computeroutput>sdk/bindings/webservice/java/jax-ws/src/COPYING.LIB</computeroutput>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync for the full text of the LGPL 2.1.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>When in doubt, please refer to the individual source code files
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync shipped with this SDK.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>Generally, VirtualBox will maintain API compatibility within a major
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync release; a major release occurs when the first or the second of the three
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync version components of VirtualBox change (that is, in the x.y.z scheme, a
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync major release is one where x or y change, but not when only z
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync changes).</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>In other words, updates like those from 2.0.0 to 2.0.2 will not come
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync with API breakages.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>Migration between major releases most likely will lead to API
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync breakage, so please make sure you updated code accordingly. The OOWS Java
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync wrappers enforce that mechanism by putting VirtualBox classes into
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync version-specific packages such as
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <computeroutput>org.virtualbox_2_2</computeroutput>. This approach allows
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync for connecting to multiple VirtualBox versions simultaneously from the
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync same Java application.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>The following sections list incompatible changes that the Main API
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync underwent since the original release of this SDK Reference with VirtualBox
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync 2.0. A change is deemed "incompatible" only if it breaks existing client
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync code (e.g. changes in method parameter lists, renamed or removed
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync interfaces and similar). In other words, the list does not contain new
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync interfaces, methods or attributes or other changes that do not affect
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync existing client code.</para>
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync <title>Incompatible API changes with version 4.2</title>
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync <itemizedlist>
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync <para>Guest control APIs for executing guest processes, working with
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync guest files or directories have been moved to the newly introduced
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync <xref linkend="IGuestSession" xreflabel="IGuestSession" /> interface which
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync can be created by calling <xref linkend="IGuest__createSession"
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync <para>A guest session will act as a
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync guest user's impersonation so that the guest credentials only have to
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync be provided when creating a new guest session. There can be up to 32
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync guest sessions at once per VM, each session serving up to 2048 guest
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync processes running or files opened.</para>
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync <para>Instead of working with process or directory handles before
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync version 4.2, there now are the dedicated interfaces
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync <xref linkend="IGuestProcess" xreflabel="IGuestProcess" />,
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync <xref linkend="IGuestDirectory" xreflabel="IGuestDirectory" /> and
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync <xref linkend="IGuestFile" xreflabel="IGuestFile" />. To retrieve more
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync information of a file system object the new interface
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync <xref linkend="IGuestFsObjInfo" xreflabel="IGuestFsObjInfo" /> has been
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync introduced.</para>
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync <para>Even though the guest control API was changed it is backwards
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync compatible so that it can be used with older installed Guest
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync Additions. However, to use upcoming features like process termination
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync or waiting for input / output new Guest Additions must be installed when
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync these features got implemented.</para>
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync <para>The following limitations apply:
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync <itemizedlist>
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync <listitem><para>The <xref linkend="IGuestFile" xreflabel="IGuestFile" />
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync interface is not fully implemented yet.</para>
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync </listitem>
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync xreflabel="IGuestSession::symlinkCreate()" />,
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync xreflabel="IGuestSession::symlinkExists()" />,
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync xreflabel="IGuestSession::symlinkRead()" />,
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync <xref linkend="IGuestSession__symlinkRemoveDirectory"
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync xreflabel="IGuestSession::symlinkRemoveDirectory()" /> and
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync xreflabel="IGuestSession::symlinkRemoveFile()" /> are not
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync implemented yet.</para>
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync </listitem>
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync xreflabel="IGuestSession::directoryRemove()" />,
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync <xref linkend="IGuestSession__directoryRemoveRecursive"
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync xreflabel="IGuestSession::directoryRemoveRecursive()" />,
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync xreflabel="IGuestSession::directoryRename()" /> and
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync xreflabel="IGuestSession::directorySetACL()" /> are not
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync implemented yet.</para>
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync </listitem>
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync xreflabel="IGuestSession::fileCreateTemp()" /> is not
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync implemented yet.</para>
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync </listitem>
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync xreflabel="IProcess::terminate()" /> is not
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync implemented yet.</para>
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync </listitem>
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync <listitem><para>Waiting for guest process output via
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync <xref linkend="ProcessWaitForFlag__StdOut" xreflabel="ProcessWaitForFlag::StdOut" />
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync and <xref linkend="ProcessWaitForFlag__StdErr" xreflabel="ProcessWaitForFlag::StdErr" />
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync is not implemented yet.</para><para>To wait for process output, <xref linkend="IProcess__read"
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync xreflabel="IProcess::read()" /> with appropriate flags still can be used to periodically
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync check for new output data to arrive. Note that <xref linkend="ProcessCreateFlag__WaitForStdOut"
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync xreflabel="ProcessCreateFlag::WaitForStdOut" /> and / or
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync <xref linkend="ProcessCreateFlag__WaitForStdErr" xreflabel="ProcessCreateFlag::WaitForStdErr" />
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync need to be specified when creating a guest process via <xref linkend="IGuestSession__processCreate"
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync xreflabel="IGuestSession::processCreate()" /> or <xref linkend="IGuestSession__processCreateEx"
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync xreflabel="IGuestSession::processCreateEx()" />.</para>
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync </listitem>
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync <para>ACL (Access Control List) handling in general is not implemented yet.</para>
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync </listitem>
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync </itemizedlist>
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync </listitem>
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync <para>The <xref linkend="LockType" xreflabel="LockType" />
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync enumeration now has an additional value <computeroutput>VM</computeroutput>
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync xreflabel="IMachine::lockMachine()" /> to create a full-blown
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync object structure for running a VM. This was the previous behavior
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync with <computeroutput>Write</computeroutput>, which now only creates
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync the minimal object structure to save time and resources (at the
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync moment the Console object is still created, but all sub-objects
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync such as Display, Keyboard, Mouse, Guest are not.</para>
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync </listitem>
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync <para>Machines can be put in groups (actually an array of groups).
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync The primary group affects the default placement of files belonging
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync to a VM. <xref linkend="IVirtualBox__createMachine"
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync xreflabel="IVirtualBox::createMachine()"/> and
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync <xref linkend="IVirtualBox__composeMachineFilename"
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync xreflabel="IVirtualBox::composeMachineFilename()"/> have been
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync adjusted accordingly, the former taking an array of groups as an
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync additional parameter and the latter taking a group as an additional
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync parameter. The create option handling has been changed for those two
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync methods, too.</para>
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync </listitem>
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync <para>The method IVirtualBox::findMedium() has been removed, since
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync it provides a subset of the functionality of <xref linkend="IVirtualBox__openMedium"
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync </listitem>
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync <para>The use of acronyms in API enumeration, interface, attribute
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync and method names has been made much more consistent, previously they
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync sometimes were lowercase and sometimes mixed case. They are now
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync consistently all caps:<table>
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync <title>Renamed identifiers in VirtualBox 4.2</title>
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync <entry><emphasis role="bold">Old name</emphasis></entry>
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync <entry><emphasis role="bold">New name</emphasis></entry>
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync <entry><xref linkend="PointingHIDType" xreflabel="PointingHIDType"/></entry>
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync <entry><xref linkend="KeyboardHIDType" xreflabel="KeyboardHIDType"/></entry>
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync <entry><xref linkend="IPCIAddress" xreflabel="IPCIAddress"/></entry>
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync <entry><xref linkend="IPCIDeviceAttachment" xreflabel="IPCIDeviceAttachment"/></entry>
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync <entry><xref linkend="IMachine__pointingHIDType" xreflabel="IMachine::pointingHIDType"/></entry>
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync <entry><xref linkend="IMachine__keyboardHIDType" xreflabel="IMachine::keyboardHIDType"/></entry>
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync <entry><xref linkend="IMachine__HPETEnabled" xreflabel="IMachine::HPETEnabled"/></entry>
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync <entry><xref linkend="IMachine__sessionPID" xreflabel="IMachine::sessionPID"/></entry>
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync <entry><xref linkend="IMachine__IOCacheEnabled" xreflabel="IMachine::IOCacheEnabled"/></entry>
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync <entry><xref linkend="IMachine__IOCacheSize" xreflabel="IMachine::IOCacheSize"/></entry>
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync <entry><xref linkend="IMachine__PCIDeviceAssignments" xreflabel="IMachine::PCIDeviceAssignments"/></entry>
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync <entry><xref linkend="IMachine__attachHostPCIDevice" xreflabel="IMachine::attachHostPCIDevice"/></entry>
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync <entry><xref linkend="IMachine__detachHostPCIDevice" xreflabel="IMachine::detachHostPCIDevice()"/></entry>
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync <entry><xref linkend="IConsole__attachedPCIDevices" xreflabel="IConsole::attachedPCIDevices"/></entry>
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync <entry><xref linkend="IHostNetworkInterface__DHCPEnabled" xreflabel="IHostNetworkInterface::DHCPEnabled"/></entry>
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync <entry>IHostNetworkInterface::enableStaticIpConfig()</entry>
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync <entry><xref linkend="IHostNetworkInterface__enableStaticIPConfig" xreflabel="IHostNetworkInterface::enableStaticIPConfig()"/></entry>
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync <entry>IHostNetworkInterface::enableStaticIpConfigV6()</entry>
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync <entry><xref linkend="IHostNetworkInterface__enableStaticIPConfigV6" xreflabel="IHostNetworkInterface::enableStaticIPConfigV6()"/></entry>
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync <entry>IHostNetworkInterface::enableDynamicIpConfig()</entry>
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync <entry><xref linkend="IHostNetworkInterface__enableDynamicIPConfig" xreflabel="IHostNetworkInterface::enableDynamicIPConfig()"/></entry>
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync <entry>IHostNetworkInterface::dhcpRediscover()</entry>
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync <entry><xref linkend="IHostNetworkInterface__DHCPRediscover" xreflabel="IHostNetworkInterface::DHCPRediscover()"/></entry>
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync <entry><xref linkend="IHost__acceleration3DAvailable" xreflabel="IHost::acceleration3DAvailable"/></entry>
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync <entry><xref linkend="IGuestOSType__recommendedPAE" xreflabel="IGuestOSType::recommendedPAE"/></entry>
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync <entry>IGuestOSType::recommendedDvdStorageController</entry>
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync <entry><xref linkend="IGuestOSType__recommendedDVDStorageController" xreflabel="IGuestOSType::recommendedDVDStorageController"/></entry>
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync <entry>IGuestOSType::recommendedDvdStorageBus</entry>
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync <entry><xref linkend="IGuestOSType__recommendedDVDStorageBus" xreflabel="IGuestOSType::recommendedDVDStorageBus"/></entry>
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync <entry>IGuestOSType::recommendedHdStorageController</entry>
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync <entry><xref linkend="IGuestOSType__recommendedHDStorageController" xreflabel="IGuestOSType::recommendedHDStorageController"/></entry>
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync <entry>IGuestOSType::recommendedHdStorageBus</entry>
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync <entry><xref linkend="IGuestOSType__recommendedHDStorageBus" xreflabel="IGuestOSType::recommendedHDStorageBus"/></entry>
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync <entry><xref linkend="IGuestOSType__recommendedUSBHID" xreflabel="IGuestOSType::recommendedUSBHID"/></entry>
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync <entry><xref linkend="IGuestOSType__recommendedHPET" xreflabel="IGuestOSType::recommendedHPET"/></entry>
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync <entry><xref linkend="IGuestOSType__recommendedUSBTablet" xreflabel="IGuestOSType::recommendedUSBTablet"/></entry>
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync <entry><xref linkend="IGuestOSType__recommendedRTCUseUTC" xreflabel="IGuestOSType::recommendedRTCUseUTC"/></entry>
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync <entry><xref linkend="IGuestOSType__recommendedUSB" xreflabel="IGuestOSType::recommendedUSB"/></entry>
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync <entry><xref linkend="INetworkAdapter__NATEngine" xreflabel="INetworkAdapter::NATEngine"/></entry>
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync <entry><xref linkend="IUSBController__enabledEHCI" xreflabel="IUSBController::enabledEHCI"/></entry>
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync <entry><xref linkend="INATEngine__TFTPPrefix" xreflabel="INATEngine::TFTPPrefix"/></entry>
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync <entry><xref linkend="INATEngine__TFTPBootFile" xreflabel="INATEngine::TFTPBootFile"/></entry>
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync <entry><xref linkend="INATEngine__TFTPNextServer" xreflabel="INATEngine::TFTPNextServer"/></entry>
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync <entry><xref linkend="INATEngine__DNSPassDomain" xreflabel="INATEngine::DNSPassDomain"/></entry>
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync <entry><xref linkend="INATEngine__DNSProxy" xreflabel="INATEngine::DNSProxy"/></entry>
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync <entry><xref linkend="INATEngine__DNSUseHostResolver" xreflabel="INATEngine::DNSUseHostResolver"/></entry>
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync <entry><xref linkend="VBoxEventType__OnHostPCIDevicePlug" xreflabel="VBoxEventType::OnHostPCIDevicePlug"/></entry>
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync <entry><xref linkend="ICPUChangedEvent__CPU" xreflabel="ICPUChangedEvent::CPU"/></entry>
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync <entry><xref linkend="INATRedirectEvent__hostIP" xreflabel="INATRedirectEvent::hostIP"/></entry>
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync <entry><xref linkend="INATRedirectEvent__guestIP" xreflabel="INATRedirectEvent::guestIP"/></entry>
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync <entry><xref linkend="IHostPCIDevicePlugEvent" xreflabel="IHostPCIDevicePlugEvent"/></entry>
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync </listitem>
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync </itemizedlist>
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync <title>Incompatible API changes with version 4.1</title>
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync <itemizedlist>
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync <para>The method <xref linkend="IAppliance__importMachines"
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync xreflabel="IAppliance::importMachines()" /> has one more parameter
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync now, which allows to configure the import process in more detail.
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync </listitem>
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync <para>The method <xref linkend="IVirtualBox__openMedium"
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync xreflabel="IVirtualBox::openMedium()" /> has one more parameter
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync now, which allows resolving duplicate medium UUIDs without the need
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync for external tools.</para>
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync </listitem>
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync <para>The <xref linkend="INetworkAdapter" xreflabel="INetworkAdapter"/>
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync interface has been cleaned up. The various methods to activate an
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync attachment type have been replaced by the
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync <xref linkend="INetworkAdapter__attachmentType" xreflabel="INetworkAdapter::attachmentType"/> setter.</para>
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync <para>Additionally each attachment mode now has its own attribute,
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync which means that host only networks no longer share the settings with
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync bridged interfaces.</para>
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync <para>To allow introducing new network attachment implementations
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync without making API changes, the concept of a generic network
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync attachment driver has been introduced, which is configurable through
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync </listitem>
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync <para>This version introduces the guest facilities concept. A guest
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync facility either represents a module or feature the guest is running or
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync offering, which is defined by <xref linkend="AdditionsFacilityType"
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync xreflabel="AdditionsFacilityType"/>. Each facility is member of a
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync <xref linkend="AdditionsFacilityClass" xreflabel="AdditionsFacilityClass"/>
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync and has a current status indicated by <xref linkend="AdditionsFacilityStatus"
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync xreflabel="AdditionsFacilityStatus"/>, together with a timestamp (in ms) of
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync the last status update.</para>
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync <para>To address the above concept, the following changes were made:
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync <itemizedlist>
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync In the <xref linkend="IGuest" xreflabel="IGuest"/> interface, the following were removed:
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync <itemizedlist>
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync <para>the <computeroutput>supportsSeamless</computeroutput> attribute;</para>
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync </listitem>
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync <para>the <computeroutput>supportsGraphics</computeroutput> attribute;</para>
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync </listitem>
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync </itemizedlist>
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync </listitem>
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync The function <xref linkend="IGuest__getFacilityStatus" xreflabel="IGuest::getFacilityStatus()"/>
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync was added. It quickly provides a facility's status without the need to get the facility
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync collection with <xref linkend="IGuest__facilities" xreflabel="IGuest::facilities"/>.
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync </listitem>
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync The attribute <xref linkend="IGuest__facilities" xreflabel="IGuest::facilities"/>
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync was added to provide an easy to access collection of all currently known guest
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync facilities, that is, it contains all facilies where at least one status update was
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync made since the guest was started.
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync </listitem>
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync The interface <xref linkend="IAdditionsFacility" xreflabel="IAdditionsFacility"/>
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync was added to represent a single facility returned by
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync <xref linkend="IGuest__facilities" xreflabel="IGuest::facilities"/>.
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync </listitem>
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync <xref linkend="AdditionsFacilityStatus" xreflabel="AdditionsFacilityStatus"/>
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync was added to represent a facility's overall status.
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync </listitem>
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync <xref linkend="AdditionsFacilityType" xreflabel="AdditionsFacilityType"/> and
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync <xref linkend="AdditionsFacilityClass" xreflabel="AdditionsFacilityClass"/> were
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync added to represent the facility's type and class.
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync </listitem>
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync </itemizedlist>
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync </listitem>
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync </itemizedlist>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <title>Incompatible API changes with version 4.0</title>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <itemizedlist>
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync <para>A new Java glue layer replacing the previous OOWS JAX-WS
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync bindings was introduced. The new library allows for uniform code
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync targeting both local (COM/XPCOM) and remote (SOAP) transports. Now,
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync instead of <computeroutput>IWebsessionManager</computeroutput>, the
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync new class <computeroutput>VirtualBoxManager</computeroutput> must be
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync used. See <xref linkend="javaapi" xreflabel="Java API chapter" />
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync for details.</para>
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync </listitem>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>The confusingly named and impractical session APIs were
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync changed. In existing client code, the following changes need to be
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync made:<itemizedlist>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>Replace any
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <computeroutput>IVirtualBox::openSession(uuidMachine,
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync ...)</computeroutput> API call with the machine's <xref
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync linkend="IMachine__lockMachine"
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync xreflabel="IMachine::lockMachine()" /> call and a
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <computeroutput>LockType.Write</computeroutput> argument. The
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync functionality is unchanged, but instead of "opening a direct
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync session on a machine" all documentation now refers to
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync "obtaining a write lock on a machine for the client
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync session".</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </listitem>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>Similarly, replace any
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <computeroutput>IVirtualBox::openExistingSession(uuidMachine,
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync ...)</computeroutput> call with the machine's <xref
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync linkend="IMachine__lockMachine"
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync xreflabel="IMachine::lockMachine()" /> call and a
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <computeroutput>LockType.Shared</computeroutput> argument.
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync Whereas it was previously impossible to connect a client
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync session to a running VM process in a race-free manner, the new
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync API will atomically either write-lock the machine for the
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync current session or establish a remote link to an existing
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync session. Existing client code which tried calling both
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <computeroutput>openExistingSession()</computeroutput> can now
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync use this one call instead.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </listitem>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>Third, replace any
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <computeroutput>IVirtualBox::openRemoteSession(uuidMachine,
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync ...)</computeroutput> call with the machine's <xref
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync linkend="IMachine__launchVMProcess"
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync xreflabel="IMachine::launchVMProcess()" /> call. The
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync functionality is unchanged.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </listitem>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync xreflabel="SessionState" /> enum was adjusted accordingly:
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync "Open" is now "Locked", "Closed" is now "Unlocked", "Closing"
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync is now "Unlocking".</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </listitem>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </listitem>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>Virtual machines created with VirtualBox 4.0 or later no
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync longer register their media in the global media registry in the
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <computeroutput>VirtualBox.xml</computeroutput> file. Instead, such
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync machines list all their media in their own machine XML files. As a
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync result, a number of media-related APIs had to be modified again.
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <itemizedlist>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>Neither <xref linkend="IVirtualBox__createHardDisk"
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync xreflabel="IVirtualBox::createHardDisk()" /> nor <xref
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync linkend="IVirtualBox__openMedium"
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync xreflabel="IVirtualBox::openMedium()" /> register media
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync automatically any more.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </listitem>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync linkend="IMachine__mountMedium"
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync xreflabel="IMachine::mountMedium()" /> now take an IMedium
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync object instead of a UUID as an argument. It is these two calls
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync which add media to a registry now (either a machine registry
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync for machines created with VirtualBox 4.0 or later or the
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync global registry otherwise). As a consequence, if a medium is
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync opened but never attached to a machine, it is no longer added
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync to any registry any more.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </listitem>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>To reduce code duplication, the APIs
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync IVirtualBox::findHardDisk(), getHardDisk(), findDVDImage(),
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync getDVDImage(), findFloppyImage() and getFloppyImage() have all
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync been merged into IVirtualBox::findMedium(), and
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync IVirtualBox::openHardDisk(), openDVDImage() and
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync openFloppyImage() have all been merged into <xref
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync linkend="IVirtualBox__openMedium"
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </listitem>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>The rare use case of changing the UUID and parent UUID
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync of a medium previously handled by
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync <computeroutput>openHardDisk()</computeroutput> is now in a
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync separate IMedium::setIDs method.</para>
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync </listitem>
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync <para><computeroutput>ISystemProperties::get/setDefaultHardDiskFolder()</computeroutput>
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync have been removed since disk images are now by default placed
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync in each machine's folder.</para>
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync </listitem>
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync <para>The <xref linkend="ISystemProperties__infoVDSize"
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync xreflabel="ISystemProperties::infoVDSize" /> attribute
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync replaces the <computeroutput>getMaxVDISize()</computeroutput>
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync API call; this now uses bytes instead of megabytes.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </listitem>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </listitem>
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync <para>Machine management APIs were enhanced as follows:<itemizedlist>
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync xreflabel="IVirtualBox::createMachine()" /> is no longer
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync restricted to creating machines in the default "Machines"
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync folder, but can now create machines at arbitrary locations.
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync For this to work, the parameter list had to be changed.</para>
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync </listitem>
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync <para>The long-deprecated
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync <computeroutput>IVirtualBox::createLegacyMachine()</computeroutput>
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync API has been removed.</para>
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync </listitem>
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync <para>To reduce code duplication and for consistency with the
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync aforementioned media APIs,
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync <computeroutput>IVirtualBox::getMachine()</computeroutput> has
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync been merged with <xref linkend="IVirtualBox__findMachine"
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync xreflabel="IVirtualBox::findMachine()" />, and
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync <computeroutput>IMachine::getSnapshot()</computeroutput> has
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync been merged with <xref linkend="IMachine__findSnapshot"
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync </listitem>
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync <para><computeroutput>IVirtualBox::unregisterMachine()</computeroutput>
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync was replaced with <xref linkend="IMachine__unregister"
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync xreflabel="IMachine::unregister()" /> with additional
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync functionality for cleaning up machine files.</para>
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync </listitem>
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync <para><computeroutput>IConsole::forgetSavedState</computeroutput>
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync has been renamed to <xref
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync linkend="IConsole__discardSavedState"
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync xreflabel="IConsole::discardSavedState()" />.</para>
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync </listitem>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </listitem>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>All event callbacks APIs were replaced with a new, generic
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync event mechanism that can be used both locally (COM, XPCOM) and
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync remotely (web services). Also, the new mechanism is usable from
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync scripting languages and a local Java. See <xref linkend="IEvent"
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync xreflabel="events" /> for details. The new concept will require
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync changes to all clients that used event callbacks.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </listitem>
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync <para><computeroutput>additionsActive()</computeroutput> was
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync replaced with <xref linkend="IGuest__additionsRunLevel"
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync linkend="IGuest__getAdditionsStatus"
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync xreflabel="getAdditionsStatus()" /> in order to support a more
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync detailed status of the current Guest Additions loading/readiness
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync xreflabel="IGuest::additionsVersion()" /> no longer returns the
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync Guest Additions interface version but the installed Guest Additions
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync version and revision in form of
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync <computeroutput>3.3.0r12345</computeroutput>.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </listitem>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>To address shared folders auto-mounting support, the following
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync APIs were extended to require an additional
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <computeroutput>automount</computeroutput> parameter: <itemizedlist>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para><xref linkend="IVirtualBox__createSharedFolder"
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync xreflabel="IVirtualBox::createSharedFolder()" /></para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </listitem>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync xreflabel="IMachine::createSharedFolder()" /></para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </listitem>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync xreflabel="IConsole::createSharedFolder()" /></para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </listitem>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </itemizedlist> Also, a new property named
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <computeroutput>autoMount</computeroutput> was added to the <xref
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync linkend="ISharedFolder" xreflabel="ISharedFolder" />
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync interface.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </listitem>
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync <para>The appliance (OVF) APIs were enhanced as
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync follows:<itemizedlist>
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync xreflabel="IMachine::export()" /> received an extra parameter
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync <computeroutput>location</computeroutput>, which is used to
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync decide for the disk naming.</para>
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync </listitem>
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync xreflabel="IAppliance::write()" /> received an extra parameter
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync <computeroutput>manifest</computeroutput>, which can suppress
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync creating the manifest file on export.</para>
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync </listitem>
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync xreflabel="IVFSExplorer::entryList()" /> received two extra
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync parameters <computeroutput>sizes</computeroutput> and
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync <computeroutput>modes</computeroutput>, which contains the
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync sizes (in bytes) and the file access modes (in octal form) of
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync the returned files.</para>
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync </listitem>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </listitem>
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync <para>Support for remote desktop access to virtual machines has been
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync cleaned up to allow third party implementations of the remote
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync desktop server. This is called the VirtualBox Remote Desktop
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync Extension (VRDE) and can be added to VirtualBox by installing the
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync corresponding extension package; see the VirtualBox User Manual for
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync details.</para>
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync <para>The following API changes were made to support the VRDE
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync interface: <itemizedlist>
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync <para><computeroutput>IVRDPServer</computeroutput> has been
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync </listitem>
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync <para><computeroutput>IRemoteDisplayInfo</computeroutput> has
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync </listitem>
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync xreflabel="IMachine::VRDEServer" /> replaces
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync <computeroutput>VRDPServer.</computeroutput></para>
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync </listitem>
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync xreflabel="IConsole::VRDEServerInfo" /> replaces
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync <computeroutput>RemoteDisplayInfo</computeroutput>.</para>
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync </listitem>
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync <para><xref linkend="ISystemProperties__VRDEAuthLibrary"
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync xreflabel="ISystemProperties::VRDEAuthLibrary" /> replaces
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync <computeroutput>RemoteDisplayAuthLibrary</computeroutput>.</para>
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync </listitem>
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync <para>The following methods have been implemented in
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync <computeroutput>IVRDEServer</computeroutput> to support
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync generic VRDE properties: <itemizedlist>
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync </listitem>
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync </listitem>
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync </listitem>
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync <para>A few implementation-specific attributes of the old
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync <computeroutput>IVRDPServer</computeroutput> interface have
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync been removed and replaced with properties: <itemizedlist>
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync <para><computeroutput>IVRDPServer::Ports</computeroutput>
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync has been replaced with the
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync <computeroutput>"TCP/Ports"</computeroutput> property.
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync The property value is a string, which contains a
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync comma-separated list of ports or ranges of ports. Use a
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync dash between two port numbers to specify a range.
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync <computeroutput>"5000,5010-5012"</computeroutput></para>
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync </listitem>
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync <para><computeroutput>IVRDPServer::NetAddress</computeroutput>
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync has been replaced with the
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync <computeroutput>"TCP/Address"</computeroutput> property.
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync The property value is an IP address string. Example:
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync <computeroutput>"127.0.0.1"</computeroutput></para>
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync </listitem>
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync <para><computeroutput>IVRDPServer::VideoChannel</computeroutput>
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync has been replaced with the
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync <computeroutput>"VideoChannel/Enabled"</computeroutput>
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync property. The property value is either
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync </listitem>
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync <para><computeroutput>IVRDPServer::VideoChannelQuality</computeroutput>
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync has been replaced with the
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync <computeroutput>"VideoChannel/Quality"</computeroutput>
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync property. The property value is a string which contain a
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync decimal number in range 10..100. Invalid values are
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync ignored and the quality is set to the default value 75.
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync Example: <computeroutput>"50"</computeroutput></para>
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync </listitem>
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync </listitem>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </listitem>
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync <para>The VirtualBox external authentication module interface has
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync been updated and made more generic. Because of that,
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync <computeroutput>VRDPAuthType</computeroutput> enumeration has been
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync renamed to <xref linkend="AuthType" xreflabel="AuthType" />.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </listitem>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </itemizedlist>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <title>Incompatible API changes with version 3.2</title>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <itemizedlist>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>The following interfaces were renamed for consistency:
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <itemizedlist>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync linkend="IMachine__getCPUProperty"
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </listitem>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync linkend="IMachine__setCPUProperty"
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </listitem>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync linkend="IMachine__getCPUIDLeaf"
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </listitem>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync linkend="IMachine__setCPUIDLeaf"
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </listitem>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync linkend="IMachine__removeCPUIDLeaf"
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </listitem>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync linkend="IMachine__removeAllCPUIDLeaves"
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync xreflabel="IMachine::removeAllCPUIDLeaves()" />;</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </listitem>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync linkend="CPUPropertyType"
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </listitem>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>IVirtualBoxCallback::onSnapshotDiscarded() is now
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync IVirtualBoxCallback::onSnapshotDeleted.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </listitem>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </listitem>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync linkend="IVirtualBox__createMachine"
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync xreflabel="IVirtualBox::createMachine" />) it is now possible to
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync ignore existing configuration files which would previously have
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync caused a failure. For this the
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <computeroutput>override</computeroutput> parameter was
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync added.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </listitem>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync linkend="IConsole__deleteSnapshot"
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync xreflabel="IConsole::deleteSnapshot()" /> is now possible while the
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync associated VM is running in almost all cases. The API is unchanged,
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync but client code that verifies machine states to determine whether
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync snapshots can be deleted may need to be adjusted.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </listitem>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>The IoBackendType enumeration was replaced with a boolean flag
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync (see <xref linkend="IStorageController__useHostIOCache"
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync xreflabel="IStorageController::useHostIOCache" />).</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </listitem>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>To address multi-monitor support, the following APIs were
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync extended to require an additional
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <computeroutput>screenId</computeroutput> parameter: <itemizedlist>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para><xref linkend="IMachine__querySavedThumbnailSize"
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync xreflabel="IMachine::querySavedThumbnailSize()" /></para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </listitem>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para><xref linkend="IMachine__readSavedThumbnailToArray"
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync xreflabel="IMachine::readSavedThumbnailToArray()" /></para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </listitem>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para><xref linkend="IMachine__querySavedScreenshotPNGSize"
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync xreflabel="IMachine::querySavedScreenshotPNGSize()" /></para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </listitem>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para><xref linkend="IMachine__readSavedScreenshotPNGToArray"
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync xreflabel="IMachine::readSavedScreenshotPNGToArray()" /></para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </listitem>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </listitem>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>The <computeroutput>shape</computeroutput> parameter of
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync IConsoleCallback::onMousePointerShapeChange was changed from a
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync implementation-specific pointer to a safearray, enabling scripting
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync languages to process pointer shapes.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </listitem>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </itemizedlist>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <title>Incompatible API changes with version 3.1</title>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <itemizedlist>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>Due to the new flexibility in medium attachments that was
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync introduced with version 3.1 (in particular, full flexibility with
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync attaching CD/DVD drives to arbitrary controllers), we seized the
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync opportunity to rework all interfaces dealing with storage media to
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync make the API more flexible as well as logical. The <xref
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync linkend="IStorageController" xreflabel="IStorageController" />,
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <xref linkend="IMedium" xreflabel="IMedium" />, <xref
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync linkend="IMediumAttachment" xreflabel="IMediumAttachment" /> and,
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <xref linkend="IMachine" xreflabel="IMachine" /> interfaces were
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync affected the most. Existing code using them to configure storage and
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync media needs to be carefully checked.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>All media (hard disks, floppies and CDs/DVDs) are now
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync uniformly handled through the <xref linkend="IMedium"
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync xreflabel="IMedium" /> interface. The device-specific interfaces
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <code>IHostDVDDrive</code>, <code>IFloppyImage</code> and
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <code>IHostFloppyDrive</code>) have been merged into IMedium; CD/DVD
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync and floppy media no longer need special treatment. The device type
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync of a medium determines in which context it can be used. Some
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync functionality was moved to the other storage-related
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync interfaces.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para><code>IMachine::attachHardDisk</code> and similar methods have
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync been renamed and generalized to deal with any type of drive and
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync xreflabel="IMachine::attachDevice()" /> is the API method for adding
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync any drive to a storage controller. The floppy and DVD/CD drives are
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync no longer handled specially, and that means you can have more than
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync one of them. As before, drives can only be changed while the VM is
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync powered off. Mounting (or unmounting) removable media at runtime is
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync possible with <xref linkend="IMachine__mountMedium"
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>Newly created virtual machines have no storage controllers
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync associated with them. Even the IDE Controller needs to be created
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync explicitly. The floppy controller is now visible as a separate
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync controller, with a new storage bus type. For each storage bus type
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync you can query the device types which can be attached, so that it is
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync not necessary to hardcode any attachment rules.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>This required matching changes e.g. in the callback interfaces
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync (the medium specific change notification was replaced by a generic
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync medium change notification) and removing associated enums (e.g.
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <code>DriveState</code>). In many places the incorrect use of the
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync plural form "media" was replaced by "medium", to improve
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync consistency.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </listitem>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync xreflabel="IMedium::state" xrefstyle="" /> attribute no longer
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync automatically performs an accessibility check; a new method <xref
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync linkend="IMedium__refreshState"
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync xreflabel="IMedium::refreshState()" /> does this. The attribute only
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync returns the state any more.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </listitem>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>There were substantial changes related to snapshots, triggered
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync by the "branched snapshots" functionality introduced with version
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync 3.1. IConsole::discardSnapshot was renamed to <xref
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync linkend="IConsole__deleteSnapshot"
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync xreflabel="IConsole::deleteSnapshot()" />.
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync IConsole::discardCurrentState and
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync IConsole::discardCurrentSnapshotAndState were removed; corresponding
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync new functionality is in <xref linkend="IConsole__restoreSnapshot"
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync xreflabel="IConsole::restoreSnapshot()" />. Also, when <xref
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync linkend="IConsole__takeSnapshot"
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync xreflabel="IConsole::takeSnapshot()" /> is called on a running
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync virtual machine, a live snapshot will be created. The old behavior
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync was to temporarily pause the virtual machine while creating an
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync online snapshot.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </listitem>
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync <para>The <computeroutput>IVRDPServer</computeroutput>,
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync <computeroutput>IRemoteDisplayInfo"</computeroutput> and
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync <computeroutput>IConsoleCallback</computeroutput> interfaces were
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync changed to reflect VRDP server ability to bind to one of available
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync ports from a list of ports.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>The <computeroutput>IVRDPServer::port</computeroutput>
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync attribute has been replaced with
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync <computeroutput>IVRDPServer::ports</computeroutput>, which is a
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync comma-separated list of ports or ranges of ports.</para>
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync <para>An <computeroutput>IRemoteDisplayInfo::port"</computeroutput>
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync attribute has been added for querying the actual port VRDP server
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync listens on.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>An IConsoleCallback::onRemoteDisplayInfoChange() notification
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync callback has been added.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </listitem>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>The parameter lists for the following functions were
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync modified:<itemizedlist>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para><xref linkend="IHost__removeHostOnlyNetworkInterface"
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync xreflabel="IHost::removeHostOnlyNetworkInterface()" /></para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </listitem>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync xreflabel="IHost::removeUSBDeviceFilter()" /></para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </listitem>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </listitem>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>In the OOWS bindings for JAX-WS, the behavior of structures
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync changed: for one, we implemented natural structures field access so
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync you can just call a "get" method to obtain a field. Secondly,
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync setters in structures were disabled as they have no expected effect
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync and were at best misleading.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </listitem>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </itemizedlist>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <title>Incompatible API changes with version 3.0</title>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <itemizedlist>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>In the object-oriented web service bindings for JAX-WS, proper
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync inheritance has been introduced for some classes, so explicit
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync casting is no longer needed to call methods from a parent class. In
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync particular, IHardDisk and other classes now properly derive from
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <xref linkend="IMedium" xreflabel="IMedium" />.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </listitem>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>All object identifiers (machines, snapshots, disks, etc)
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync switched from GUIDs to strings (now still having string
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync representation of GUIDs inside). As a result, no particular internal
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync structure can be assumed for object identifiers; instead, they
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync should be treated as opaque unique handles. This change mostly
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync affects Java and C++ programs; for other languages, GUIDs are
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync transparently converted to strings.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </listitem>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>The uses of NULL strings have been changed greatly. All out
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync parameters now use empty strings to signal a null value. For in
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync parameters both the old NULL and empty string is allowed. This
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync change was necessary to support more client bindings, especially
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync using the web service API. Many of them either have no special NULL
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync value or have trouble dealing with it correctly in the respective
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync library code.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </listitem>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>Accidentally, the <code>TSBool</code> interface still appeared
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync in 3.0.0, and was removed in 3.0.2. This is an SDK bug, do not use
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync the SDK for VirtualBox 3.0.0 for developing clients.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </listitem>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>The type of <xref linkend="IVirtualBoxErrorInfo__resultCode"
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync xreflabel="IVirtualBoxErrorInfo::resultCode" /> changed from
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </listitem>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>The parameter list of IVirtualBox::openHardDisk was
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync changed.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </listitem>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>The method IConsole::discardSavedState was renamed to
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync IConsole::forgetSavedState, and a parameter was added.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </listitem>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>The method IConsole::powerDownAsync was renamed to <xref
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync linkend="IConsole__powerDown" xreflabel="IConsole::powerDown" />,
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync and the previous method with that name was deleted. So effectively a
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync parameter was added.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </listitem>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync xreflabel="IFramebuffer" /> interface, the following were
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync removed:<itemizedlist>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>the <computeroutput>operationSupported</computeroutput>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync attribute;</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>(as a result, the
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <computeroutput>FramebufferAccelerationOperation</computeroutput>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync enum was no longer needed and removed as well);</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </listitem>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>the <computeroutput>solidFill()</computeroutput>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync method;</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </listitem>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>the <computeroutput>copyScreenBits()</computeroutput>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync method.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </listitem>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </listitem>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>In the <xref linkend="IDisplay" xreflabel="IDisplay" />
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync interface, the following were removed:<itemizedlist>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <computeroutput>setupInternalFramebuffer()</computeroutput>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync method;</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </listitem>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>the <computeroutput>lockFramebuffer()</computeroutput>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync method;</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </listitem>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>the <computeroutput>unlockFramebuffer()</computeroutput>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync method;</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </listitem>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <computeroutput>registerExternalFramebuffer()</computeroutput>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync method.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </listitem>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </listitem>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </itemizedlist>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <title>Incompatible API changes with version 2.2</title>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <itemizedlist>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>Added explicit version number into JAX-WS Java package names,
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync such as <computeroutput>org.virtualbox_2_2</computeroutput>,
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync allowing connect to multiple VirtualBox clients from single Java
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync application.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </listitem>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>The interfaces having a "2" suffix attached to them with
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync version 2.1 were renamed again to have that suffix removed. This
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync time around, this change involves only the name, there are no
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync functional differences.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>As a result, IDVDImage2 is now IDVDImage; IHardDisk2 is now
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync IHardDisk; IHardDisk2Attachment is now IHardDiskAttachment.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>Consequentially, all related methods and attributes that had a
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync "2" suffix have been renamed; for example, IMachine::attachHardDisk2
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync now becomes IMachine::attachHardDisk().</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </listitem>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>IVirtualBox::openHardDisk has an extra parameter for opening a
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </listitem>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>The remaining collections were replaced by more performant
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync safe-arrays. This affects the following collections:</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <itemizedlist>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </listitem>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </listitem>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </listitem>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </listitem>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </listitem>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </listitem>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </listitem>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </listitem>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </listitem>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </listitem>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </itemizedlist>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </listitem>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>Since "Host Interface Networking" was renamed to "bridged
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync networking" and host-only networking was introduced, all associated
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync interfaces needed renaming as well. In detail:</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <itemizedlist>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>The HostNetworkInterfaceType enum has been renamed to
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync xreflabel="HostNetworkInterfaceMediumType" /></para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </listitem>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>The IHostNetworkInterface::type attribute has been renamed
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync to <xref linkend="IHostNetworkInterface__mediumType"
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync xreflabel="IHostNetworkInterface::mediumType" /></para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </listitem>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>INetworkAdapter::attachToHostInterface() has been renamed
9562e2d410460d8fae06fa24297f172fee1d1995vboxsync to INetworkAdapter::attachToBridgedInterface</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </listitem>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>In the IHost interface, createHostNetworkInterface() has
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync been renamed to <xref
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync linkend="IHost__createHostOnlyNetworkInterface"
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync xreflabel="createHostOnlyNetworkInterface()" /></para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </listitem>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>Similarly, removeHostNetworkInterface() has been renamed
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync to <xref linkend="IHost__removeHostOnlyNetworkInterface"
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync xreflabel="removeHostOnlyNetworkInterface()" /></para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </listitem>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </itemizedlist>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </listitem>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </itemizedlist>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <title>Incompatible API changes with version 2.1</title>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <itemizedlist>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>With VirtualBox 2.1, error codes were added to many error
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync infos that give the caller a machine-readable (numeric) feedback in
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync addition to the error string that has always been available. This is
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync an ongoing process, and future versions of this SDK reference will
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync document the error codes for each method call.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </listitem>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>The hard disk and other media interfaces were completely
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync redesigned. This was necessary to account for the support of VMDK,
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync VHD and other image types; since backwards compatibility had to be
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync broken anyway, we seized the moment to redesign the interfaces in a
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync more logical way.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <itemizedlist>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>Previously, the old IHardDisk interface had several
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync derivatives called IVirtualDiskImage, IVMDKImage, IVHDImage,
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync IISCSIHardDisk and ICustomHardDisk for the various disk formats
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync supported by VirtualBox. The new IHardDisk2 interface that comes
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync with version 2.1 now supports all hard disk image formats
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync itself.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </listitem>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>IHardDiskFormat is a new interface to describe the
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync available back-ends for hard disk images (e.g. VDI, VMDK, VHD or
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync iSCSI). The IHardDisk2::format attribute can be used to find out
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync the back-end that is in use for a particular hard disk image.
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync ISystemProperties::hardDiskFormats[] contains a list of all
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync back-ends supported by the system. <xref
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync linkend="ISystemProperties__defaultHardDiskFormat"
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync xreflabel="ISystemProperties::defaultHardDiskFormat" /> contains
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync the default system format.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </listitem>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync xreflabel="IMedium" /> interface is a generic interface for hard
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync disk, DVD and floppy images that contains the attributes and
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync methods shared between them. It can be considered a parent class
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync of the more specific interfaces for those images, which are now
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync IHardDisk2, IDVDImage2 and IFloppyImage2.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>In each case, the "2" versions of these interfaces replace
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync the earlier versions that did not have the "2" suffix.
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync Previously, the IDVDImage and IFloppyImage interfaces were
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync entirely unrelated to IHardDisk.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </listitem>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>As a result, all parts of the API that previously
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync referenced IHardDisk, IDVDImage or IFloppyImage or any of the
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync old subclasses are gone and will have replacements that use
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync IHardDisk2, IDVDImage2 and IFloppyImage2; see, for example,
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync IMachine::attachHardDisk2.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </listitem>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>In particular, the IVirtualBox::hardDisks2 array replaces
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync the earlier IVirtualBox::hardDisks collection.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </listitem>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </itemizedlist>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </listitem>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para><xref linkend="IGuestOSType" xreflabel="IGuestOSType" /> was
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync extended to group operating systems into families and for 64-bit
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync support.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </listitem>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync xreflabel="IHostNetworkInterface" /> interface was completely
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync rewritten to account for the changes in how Host Interface
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync Networking is now implemented in VirtualBox 2.1.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </listitem>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>The IVirtualBox::machines2[] array replaces the former
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync IVirtualBox::machines collection.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </listitem>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>Added <xref linkend="IHost__getProcessorFeature"
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync xreflabel="IHost::getProcessorFeature()" /> and <xref
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync linkend="ProcessorFeature" xreflabel="ProcessorFeature" />
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync enumeration.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </listitem>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync linkend="IVirtualBox__createMachine"
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync xreflabel="IVirtualBox::createMachine()" /> was modified.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </listitem>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </listitem>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync linkend="IMachine__accelerate3DEnabled"
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync xreflabel="accelerate3DEnabled" />, HWVirtExVPIDEnabled, <xref
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync linkend="IMachine__guestPropertyNotificationPatterns"
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync xreflabel="guestPropertyNotificationPatterns" />, <xref
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync linkend="IMachine__CPUCount" xreflabel="CPUCount" />.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </listitem>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync <para>Added <xref linkend="IConsole__powerUpPaused"
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync linkend="IConsole__getGuestEnteredACPIMode"
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync xreflabel="IConsole::getGuestEnteredACPIMode()" />.</para>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </listitem>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </listitem>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync </itemizedlist>
6728a36898fd2be125a28e84d2115d19aa4923edvboxsync<!-- vim: set shiftwidth=2 tabstop=2 expandtab: -->