SDKRef.xml revision 917817a983e71a3fb56452c46caba04b0d59f72e
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
bcd589d9db90b68d3af5d6839c1d613bb64d4c04vboxsync"http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd">
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync <title>$VBOX_PRODUCT<superscript>®</superscript></title>
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync <subtitle>Programming Guide and Reference</subtitle>
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync <copyright>
c4bfe32373c55416bf49dc29ebf45dfa560b4692vboxsync </copyright>
c4bfe32373c55416bf49dc29ebf45dfa560b4692vboxsync </bookinfo>
61f058cfcc81ec889fc17ac84c25a118a91d1423vboxsync <para>VirtualBox comes with comprehensive support for third-party
90fd0059d671978f9db54fab8d5daa3635a4b25avboxsync developers. This Software Development Kit (SDK) contains all the
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync documentation and interface files that are needed to write code that
bcd589d9db90b68d3af5d6839c1d613bb64d4c04vboxsync interacts with VirtualBox.</para>
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync <title>Modularity: the building blocks of VirtualBox</title>
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync <para>VirtualBox is cleanly separated into several layers, which can be
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync visualized like in the picture below:</para>
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync <mediaobject>
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync <imageobject>
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync <imagedata align="center" fileref="images/vbox-components.png"
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync width="12cm" />
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync </imageobject>
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync </mediaobject>
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync <para>The orange area represents code that runs in kernel mode, the blue
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync area represents userspace code.</para>
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync <para>At the bottom of the stack resides the hypervisor -- the core of
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync the virtualization engine, controlling execution of the virtual machines
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync and making sure they do not conflict with each other or whatever the
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync host computer is doing otherwise.</para>
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync <para>On top of the hypervisor, additional internal modules provide
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync extra functionality. For example, the RDP server, which can deliver the
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync graphical output of a VM remotely to an RDP client, is a separate module
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync that is only loosely tacked into the virtual graphics device. Live
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync Migration and Resource Monitor are additional modules currently in the
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync process of being added to VirtualBox.</para>
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync <para>What is primarily of interest for purposes of the SDK is the API
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync layer block that sits on top of all the previously mentioned blocks.
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync This API, which we call the <emphasis role="bold">"Main API"</emphasis>,
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync exposes the entire feature set of the virtualization engine below. It is
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync completely documented in this SDK Reference -- see <xref
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync linkend="sdkref_classes" /> and <xref linkend="sdkref_enums" /> -- and
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync available to anyone who wishes to control VirtualBox programmatically.
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync We chose the name "Main API" to differentiate it from other programming
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync interfaces of VirtualBox that may be publicly accessible.</para>
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync <para>With the Main API, you can create, configure, start, stop and
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync delete virtual machines, retrieve performance statistics about running
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync VMs, configure the VirtualBox installation in general, and more. In
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync fact, internally, the front-end programs
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync <computeroutput>VBoxManage</computeroutput> use nothing but this API as
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync well -- there are no hidden backdoors into the virtualization engine for
730f8be51b729e8a3c1e32c756cd0f4ec088dd4dvboxsync our own front-ends. This ensures the entire Main API is both
bcd589d9db90b68d3af5d6839c1d613bb64d4c04vboxsync well-documented and well-tested. (The same applies to
bcd589d9db90b68d3af5d6839c1d613bb64d4c04vboxsync <computeroutput>VBoxHeadless</computeroutput>, which is not shown in the
730f8be51b729e8a3c1e32c756cd0f4ec088dd4dvboxsync image.)</para>
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync <title>Two guises of the same "Main API": the web service or
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync <para>There are several ways in which the Main API can be called by
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync other code:<orderedlist>
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync <para>VirtualBox comes with a <emphasis role="bold">web
bcd589d9db90b68d3af5d6839c1d613bb64d4c04vboxsync service</emphasis> that maps nearly the entire Main API. The web
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync service ships in a stand-alone executable
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync (<computeroutput>vboxwebsrv</computeroutput>) that, when running,
bcd589d9db90b68d3af5d6839c1d613bb64d4c04vboxsync acts as an HTTP server, accepts SOAP connections and processes
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync them.</para>
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync <para>Since the entire web service API is publicly described in a
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync web service description file (in WSDL format), you can write
bcd589d9db90b68d3af5d6839c1d613bb64d4c04vboxsync client programs that call the web service in any language with a
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync toolkit that understands WSDL. These days, that includes most
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync programming languages that are available: Java, C++, .NET, PHP,
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync Python, Perl and probably many more.</para>
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync <para>All of this is explained in detail in subsequent chapters of
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync this book.</para>
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync <para>There are two ways in which you can write client code that
aa131431882ca8e44b0480d4af0b5d139f1bde21vboxsync uses the web service:<orderedlist>
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync <para>For Java as well as Python, the SDK contains
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync easy-to-use classes that allow you to use the web service in
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync an object-oriented, straightforward manner. We shall refer
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync to this as the <emphasis role="bold">"object-oriented web
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync <para>The OO bindings for Java are described in <xref
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync linkend="javaapi" />, those for Python in <xref lang=""
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync </listitem>
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync <para>Alternatively, you can use the web service directly,
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync without the object-oriented client layer. We shall refer to
bcd589d9db90b68d3af5d6839c1d613bb64d4c04vboxsync <para>You will then have neither native object orientation
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync nor full type safety, since web services are neither
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync object-oriented nor stateful. However, in this way, you can
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync write client code even in languages for which we do not ship
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync object-oriented client code; all you need is a programming
bcd589d9db90b68d3af5d6839c1d613bb64d4c04vboxsync language with a toolkit that can parse WSDL and generate
bcd589d9db90b68d3af5d6839c1d613bb64d4c04vboxsync client wrapper code from it.</para>
bcd589d9db90b68d3af5d6839c1d613bb64d4c04vboxsync linkend="raw-webservice" />, with samples for Java and
bcd589d9db90b68d3af5d6839c1d613bb64d4c04vboxsync Perl.</para>
bcd589d9db90b68d3af5d6839c1d613bb64d4c04vboxsync </listitem>
bcd589d9db90b68d3af5d6839c1d613bb64d4c04vboxsync </listitem>
bcd589d9db90b68d3af5d6839c1d613bb64d4c04vboxsync <para>Internally, for portability and easier maintenance, the Main
bcd589d9db90b68d3af5d6839c1d613bb64d4c04vboxsync API is implemented using the <emphasis role="bold">Component
bcd589d9db90b68d3af5d6839c1d613bb64d4c04vboxsync Object Model (COM),</emphasis> an interprocess mechanism for
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync software components originally introduced by Microsoft for
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync Microsoft Windows. On a Windows host, VirtualBox will use
bcd589d9db90b68d3af5d6839c1d613bb64d4c04vboxsync Microsoft COM; on other hosts where COM is not present, it ships
bcd589d9db90b68d3af5d6839c1d613bb64d4c04vboxsync with XPCOM, a free software implementation of COM originally
bcd589d9db90b68d3af5d6839c1d613bb64d4c04vboxsync created by the Mozilla project for their browsers.</para>
bcd589d9db90b68d3af5d6839c1d613bb64d4c04vboxsync <para>So, if you are familiar with COM and the C++ programming
bcd589d9db90b68d3af5d6839c1d613bb64d4c04vboxsync language (or with any other programming language that can handle
bcd589d9db90b68d3af5d6839c1d613bb64d4c04vboxsync COM/XPCOM objects, such as Java, Visual Basic or C#), then you can
bcd589d9db90b68d3af5d6839c1d613bb64d4c04vboxsync use the COM/XPCOM API directly. VirtualBox comes with all
bcd589d9db90b68d3af5d6839c1d613bb64d4c04vboxsync necessary files and documentation to build fully functional COM
bcd589d9db90b68d3af5d6839c1d613bb64d4c04vboxsync applications. For an introduction, please see <xref
bcd589d9db90b68d3af5d6839c1d613bb64d4c04vboxsync <para>The VirtualBox front-ends (the graphical user interfaces as
bcd589d9db90b68d3af5d6839c1d613bb64d4c04vboxsync well as the command line), which are all written in C++, use
bcd589d9db90b68d3af5d6839c1d613bb64d4c04vboxsync COM/XPCOM to call the Main API. Technically, the web service is
bcd589d9db90b68d3af5d6839c1d613bb64d4c04vboxsync another front-end to this COM API, mapping almost all of it to
bcd589d9db90b68d3af5d6839c1d613bb64d4c04vboxsync SOAP clients.</para>
bcd589d9db90b68d3af5d6839c1d613bb64d4c04vboxsync </listitem>
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync <para>If you wonder which way to choose, here are a few
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync comparisons:<table>
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync <title>Comparison web service vs. COM/XPCOM</title>
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync <entry><emphasis role="bold">Web service</emphasis></entry>
416817daa142e9bb7eaf14a1b10577978a5e691bvboxsync <entry><emphasis role="bold">COM/XPCOM</emphasis></entry>
bcd589d9db90b68d3af5d6839c1d613bb64d4c04vboxsync <entry><emphasis role="bold">Pro:</emphasis> Easy to use with
bcd589d9db90b68d3af5d6839c1d613bb64d4c04vboxsync Java and Python with the object-oriented web service;
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync extensive support even with other languages (C++, .NET, PHP,
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync Perl and others)</entry>
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync <entry><emphasis role="bold">Con:</emphasis> Usable from
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync languages where COM bridge available (most languages on
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync Windows platform, Python and C++ on other hosts)</entry>
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync <entry><emphasis role="bold">Pro:</emphasis> Client can be on
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync remote machine</entry>
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync <entry><emphasis role="bold">Con: </emphasis>Client must be on
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync the same host where virtual machine is executed</entry>
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync <entry><emphasis role="bold">Con: </emphasis>Significant
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync overhead due to XML marshalling over the wire for each method
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync call</entry>
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync <entry><emphasis role="bold">Pro: </emphasis>Relatively low
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync invocation overhead</entry>
416817daa142e9bb7eaf14a1b10577978a5e691bvboxsync <para>In the following chapters, we will describe the different ways in
416817daa142e9bb7eaf14a1b10577978a5e691bvboxsync which to program VirtualBox, starting with the method that is easiest to
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync use and then increase complexity as we go along.</para>
416817daa142e9bb7eaf14a1b10577978a5e691bvboxsync <para>Web services are a particular type of programming interface.
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync Whereas, with "normal" programming, a program calls an application
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync programming interface (API) defined by another program or the operating
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync system and both sides of the interface have to agree on the calling
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync convention and, in most cases, use the same programming language, web
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync services use Internet standards such as HTTP and XML to
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync communicate.<footnote>
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync <para>In some ways, web services promise to deliver the same thing
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync as CORBA and DCOM did years ago. However, while these previous
bcd589d9db90b68d3af5d6839c1d613bb64d4c04vboxsync technologies relied on specific binary protocols and thus proved to
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync be difficult to use between diverging platforms, web services
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync circumvent these incompatibilities by using text-only standards like
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync HTTP and XML. On the downside (and, one could say, typical of things
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync related to XML), a lot of standards are involved before a web
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync service can be implemented. Many of the standards invented around
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync XML are used one way or another. As a result, web services are slow
2dd7b4388106de88d20f33a8aa6c85c8babf507bvboxsync and verbose, and the details can be incredibly messy. The relevant
2dd7b4388106de88d20f33a8aa6c85c8babf507bvboxsync standards here are called SOAP and WSDL, where SOAP describes the
2dd7b4388106de88d20f33a8aa6c85c8babf507bvboxsync format of the messages that are exchanged (an XML document wrapped
2dd7b4388106de88d20f33a8aa6c85c8babf507bvboxsync in an HTTP header), and WSDL is an XML format that describes a
2dd7b4388106de88d20f33a8aa6c85c8babf507bvboxsync complete API provided by a web service. WSDL in turn uses XML Schema
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync to describe types, which is not exactly terse either. However, as
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync you will see from the samples provided in this chapter, the
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync VirtualBox web service shields you from these details and is easy to
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync use.</para>
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync <para>In order to successfully use a web service, a number of things are
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync required -- primarily, a web service accepting connections; service
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync descriptions; and then a client that connects to that web service. The
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync connections are governed by the SOAP standard, which describes how
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync messages are to be exchanged between a service and its clients; the
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync service descriptions are governed by WSDL.</para>
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync <para>In the case of VirtualBox, this translates into the following
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync three components:<orderedlist>
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync <para>The VirtualBox web service (the "server"): this is the
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync <computeroutput>vboxwebsrv</computeroutput> executable shipped
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync with VirtualBox. Once you start this executable (which acts as a
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync HTTP server on a specific TCP/IP port), clients can connect to the
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync web service and thus control a VirtualBox installation.</para>
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync </listitem>
416817daa142e9bb7eaf14a1b10577978a5e691bvboxsync <para>VirtualBox also comes with WSDL files that describe the
416817daa142e9bb7eaf14a1b10577978a5e691bvboxsync services provided by the web service. You can find these files in
416817daa142e9bb7eaf14a1b10577978a5e691bvboxsync the <computeroutput>sdk/bindings/webservice/</computeroutput>
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync directory. These files are understood by the web service toolkits
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync that are shipped with most programming languages and enable you to
bcd589d9db90b68d3af5d6839c1d613bb64d4c04vboxsync easily access a web service even if you don't use our
bcd589d9db90b68d3af5d6839c1d613bb64d4c04vboxsync object-oriented client layers. VirtualBox is shipped with
bcd589d9db90b68d3af5d6839c1d613bb64d4c04vboxsync pregenerated web service glue code for several languages (Python,
bcd589d9db90b68d3af5d6839c1d613bb64d4c04vboxsync Perl, Java).</para>
bcd589d9db90b68d3af5d6839c1d613bb64d4c04vboxsync </listitem>
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync <para>A client that connects to the web service in order to
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync control the VirtualBox installation.</para>
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync <para>Unless you play with some of the samples shipped with
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync VirtualBox, this needs to be written by you.</para>
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync </listitem>
bcd589d9db90b68d3af5d6839c1d613bb64d4c04vboxsync <para>The web service ships in an stand-alone executable,
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync <computeroutput>vboxwebsrv</computeroutput>, that, when running, acts as
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync a HTTP server, accepts SOAP connections and processes them -- remotely
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync or from the same machine.<note>
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync <para>The web service executable is not contained with the
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync VirtualBox SDK, but instead ships with the standard VirtualBox
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync binary package for your specific platform. Since the SDK contains
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync only platform-independent text files and documentation, the binaries
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync are instead shipped with the platform-specific packages.</para>
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync <para>The <computeroutput>vboxwebsrv</computeroutput> program, which
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync implements the web service, is a text-mode (console) program which,
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync after being started, simply runs until it is interrupted with Ctrl-C or
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync a kill command.</para>
416817daa142e9bb7eaf14a1b10577978a5e691bvboxsync <para>Once the web service is started, it acts as a front-end to the
416817daa142e9bb7eaf14a1b10577978a5e691bvboxsync VirtualBox installation of the user account that it is running under. In
416817daa142e9bb7eaf14a1b10577978a5e691bvboxsync other words, if the web service is run under the user account of
416817daa142e9bb7eaf14a1b10577978a5e691bvboxsync <computeroutput>user1</computeroutput>, it will see and manipulate the
416817daa142e9bb7eaf14a1b10577978a5e691bvboxsync virtual machines and other data represented by the VirtualBox data of
416817daa142e9bb7eaf14a1b10577978a5e691bvboxsync that user (e.g., on a Linux machine, under
416817daa142e9bb7eaf14a1b10577978a5e691bvboxsync <computeroutput>/home/user1/.VirtualBox</computeroutput>; see the
416817daa142e9bb7eaf14a1b10577978a5e691bvboxsync VirtualBox User Manual for details on where this data is stored).</para>
416817daa142e9bb7eaf14a1b10577978a5e691bvboxsync <para>The web service supports the following command line
416817daa142e9bb7eaf14a1b10577978a5e691bvboxsync options:</para>
416817daa142e9bb7eaf14a1b10577978a5e691bvboxsync <itemizedlist>
416817daa142e9bb7eaf14a1b10577978a5e691bvboxsync <computeroutput>-h</computeroutput>): print a brief summary of
416817daa142e9bb7eaf14a1b10577978a5e691bvboxsync command line options.</para>
416817daa142e9bb7eaf14a1b10577978a5e691bvboxsync </listitem>
416817daa142e9bb7eaf14a1b10577978a5e691bvboxsync <para><computeroutput>--background</computeroutput> (or
416817daa142e9bb7eaf14a1b10577978a5e691bvboxsync <computeroutput>-b</computeroutput>): run the web service as a
416817daa142e9bb7eaf14a1b10577978a5e691bvboxsync background daemon. This option is not supported on Windows
416817daa142e9bb7eaf14a1b10577978a5e691bvboxsync hosts.</para>
416817daa142e9bb7eaf14a1b10577978a5e691bvboxsync </listitem>
416817daa142e9bb7eaf14a1b10577978a5e691bvboxsync <computeroutput>-H</computeroutput>): This specifies the host to
416817daa142e9bb7eaf14a1b10577978a5e691bvboxsync bind to and defaults to "localhost".</para>
416817daa142e9bb7eaf14a1b10577978a5e691bvboxsync </listitem>
416817daa142e9bb7eaf14a1b10577978a5e691bvboxsync <computeroutput>-p</computeroutput>): This specifies which port to
416817daa142e9bb7eaf14a1b10577978a5e691bvboxsync bind to on the host and defaults to 18083.</para>
416817daa142e9bb7eaf14a1b10577978a5e691bvboxsync </listitem>
416817daa142e9bb7eaf14a1b10577978a5e691bvboxsync <para><computeroutput>--timeout</computeroutput> (or
416817daa142e9bb7eaf14a1b10577978a5e691bvboxsync <computeroutput>-t</computeroutput>): This specifies the session
416817daa142e9bb7eaf14a1b10577978a5e691bvboxsync timeout, in seconds, and defaults to 300 (five minutes). A web
416817daa142e9bb7eaf14a1b10577978a5e691bvboxsync service client that has logged on but makes no calls to the web
416817daa142e9bb7eaf14a1b10577978a5e691bvboxsync service will automatically be disconnected after the number of
416817daa142e9bb7eaf14a1b10577978a5e691bvboxsync seconds specified here, as if it had called the
416817daa142e9bb7eaf14a1b10577978a5e691bvboxsync <computeroutput>IWebSessionManager::logoff()</computeroutput>
416817daa142e9bb7eaf14a1b10577978a5e691bvboxsync method provided by the web service itself.</para>
416817daa142e9bb7eaf14a1b10577978a5e691bvboxsync <para>It is normally vital that each web service client call this
416817daa142e9bb7eaf14a1b10577978a5e691bvboxsync method, as the web service can accumulate large amounts of memory
416817daa142e9bb7eaf14a1b10577978a5e691bvboxsync when running, especially if a web service client does not properly
416817daa142e9bb7eaf14a1b10577978a5e691bvboxsync release managed object references. As a result, this timeout value
416817daa142e9bb7eaf14a1b10577978a5e691bvboxsync should not be set too high, especially on machines with a high
416817daa142e9bb7eaf14a1b10577978a5e691bvboxsync load on the web service, or the web service may eventually deny
416817daa142e9bb7eaf14a1b10577978a5e691bvboxsync service.</para>
416817daa142e9bb7eaf14a1b10577978a5e691bvboxsync </listitem>
416817daa142e9bb7eaf14a1b10577978a5e691bvboxsync <para><computeroutput>--check-interval</computeroutput> (or
416817daa142e9bb7eaf14a1b10577978a5e691bvboxsync <computeroutput>-i</computeroutput>): This specifies the interval
416817daa142e9bb7eaf14a1b10577978a5e691bvboxsync in which the web service checks for timed-out clients, in seconds,
416817daa142e9bb7eaf14a1b10577978a5e691bvboxsync and defaults to 5. This normally does not need to be
416817daa142e9bb7eaf14a1b10577978a5e691bvboxsync changed.</para>
416817daa142e9bb7eaf14a1b10577978a5e691bvboxsync </listitem>
416817daa142e9bb7eaf14a1b10577978a5e691bvboxsync <para><computeroutput>--verbose</computeroutput> (or
416817daa142e9bb7eaf14a1b10577978a5e691bvboxsync <computeroutput>-v</computeroutput>): Normally, the webservice
2dd7b4388106de88d20f33a8aa6c85c8babf507bvboxsync outputs only brief messages to the console each time a request is
2dd7b4388106de88d20f33a8aa6c85c8babf507bvboxsync served. With this option, the webservice prints much more detailed
2dd7b4388106de88d20f33a8aa6c85c8babf507bvboxsync data about every request and the COM methods that those requests
2dd7b4388106de88d20f33a8aa6c85c8babf507bvboxsync are mapped to internally, which can be useful for debugging client
2dd7b4388106de88d20f33a8aa6c85c8babf507bvboxsync programs.</para>
2dd7b4388106de88d20f33a8aa6c85c8babf507bvboxsync </listitem>
2dd7b4388106de88d20f33a8aa6c85c8babf507bvboxsync <para><computeroutput>--logfile</computeroutput> (or
2dd7b4388106de88d20f33a8aa6c85c8babf507bvboxsync <computeroutput><file></computeroutput>: If this is
2dd7b4388106de88d20f33a8aa6c85c8babf507bvboxsync specified, the webservice not only prints its output to the
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync console, but also writes it to the specified file. The file is
2dd7b4388106de88d20f33a8aa6c85c8babf507bvboxsync created if it does not exist; if it does exist, new output is
2dd7b4388106de88d20f33a8aa6c85c8babf507bvboxsync appended to it. This is useful if you run the webservice
2dd7b4388106de88d20f33a8aa6c85c8babf507bvboxsync unattended and need to debug problems after they have
2dd7b4388106de88d20f33a8aa6c85c8babf507bvboxsync occurred.</para>
2dd7b4388106de88d20f33a8aa6c85c8babf507bvboxsync </listitem>
416817daa142e9bb7eaf14a1b10577978a5e691bvboxsync </itemizedlist>
416817daa142e9bb7eaf14a1b10577978a5e691bvboxsync <para>As opposed to the COM/XPCOM variant of the Main API, a client
416817daa142e9bb7eaf14a1b10577978a5e691bvboxsync that wants to use the web service must first log on by calling the
416817daa142e9bb7eaf14a1b10577978a5e691bvboxsync <computeroutput>IWebsessionManager::logon()</computeroutput> API (see
416817daa142e9bb7eaf14a1b10577978a5e691bvboxsync <xref linkend="IWebsessionManager__logon" />) that is specific to the
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync web service. Logon is necessary for the web service to be stateful;
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync internally, it maintains a session for each client that connects to
416817daa142e9bb7eaf14a1b10577978a5e691bvboxsync <para>The <computeroutput>IWebsessionManager::logon()</computeroutput>
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync API takes a user name and a password as arguments, which the web
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync service then passes to a customizable authentication plugin that
416817daa142e9bb7eaf14a1b10577978a5e691bvboxsync performs the actual authentication.</para>
416817daa142e9bb7eaf14a1b10577978a5e691bvboxsync <para>For testing purposes, it is recommended that you first disable
416817daa142e9bb7eaf14a1b10577978a5e691bvboxsync authentication with this command:<screen>VBoxManage setproperty websrvauthlibrary null</screen></para>
416817daa142e9bb7eaf14a1b10577978a5e691bvboxsync <para>This will cause all logons to succeed, regardless of user
416817daa142e9bb7eaf14a1b10577978a5e691bvboxsync name or password. This should of course not be used in a
416817daa142e9bb7eaf14a1b10577978a5e691bvboxsync production environment.</para>
416817daa142e9bb7eaf14a1b10577978a5e691bvboxsync </warning>Generally, the mechanism by which clients are
416817daa142e9bb7eaf14a1b10577978a5e691bvboxsync authenticated is configurable by way of the
416817daa142e9bb7eaf14a1b10577978a5e691bvboxsync <computeroutput>VBoxManage</computeroutput> command:</para>
416817daa142e9bb7eaf14a1b10577978a5e691bvboxsync <para><screen>VBoxManage setproperty websrvauthlibrary default|null|<library></screen></para>
416817daa142e9bb7eaf14a1b10577978a5e691bvboxsync <para>This way you can specify any shared object/dynamic link module
416817daa142e9bb7eaf14a1b10577978a5e691bvboxsync that conforms with the specifications for authentication modules as
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync laid out in section 9.3 of the VirtualBox User Manual; the web service
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync uses the same kind of modules as the VirtualBox RDP server.</para>
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync <para>By default, after installation, the web service uses the
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync VRDPAuth module that ships with VirtualBox. This module uses PAM on
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync Linux hosts to authenticate users. Any valid username/password
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync combination is accepted, it does not have to be the username and
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync password of the user running the webservice daemon. Unless
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync <computeroutput>vboxwebsrv</computeroutput> runs as root, PAM
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync authentication can fail, because sometimes the file
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync <computeroutput>/etc/shadow</computeroutput>, which is used by PAM, is
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync not readable. On most Linux distribution PAM uses a suid root helper
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync internally, so make sure you test this before deploying it. One can
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync override this behavior by setting the environment variable
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync <computeroutput>VBOX_PAM_ALLOW_INACTIVE</computeroutput> which will
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync suppress failures when unable to read the shadow password file. Please
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync use this variable carefully, and only if you fully understand what
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync you're doing.</para>
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync <title>Solaris host: starting the web service via SMF</title>
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync <para>On Solaris hosts, the VirtualBox web service daemon is
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync integrated into the SMF framework. You can change the parameters, but
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync don't have to if the defaults below already match your needs:<screen>svccfg -s svc:/application/virtualbox/webservice:default setprop config/host=localhost
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsyncsvccfg -s svc:/application/virtualbox/webservice:default setprop config/port=18083
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsyncsvccfg -s svc:/application/virtualbox/webservice:default setprop config/user=root</screen></para>
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync <para>If you made any change, don't forget to run the following
c9a593aa048a154e59b52d1237d89e3cdaee9b3dvboxsync command to put the changes into effect immediately:<screen>svcadm refresh svc:/application/virtualbox/webservice:default</screen></para>
c9a593aa048a154e59b52d1237d89e3cdaee9b3dvboxsync <para>If you forget the above command then the previous settings will
c9a593aa048a154e59b52d1237d89e3cdaee9b3dvboxsync be used when enabling the service. Check the current property settings
c9a593aa048a154e59b52d1237d89e3cdaee9b3dvboxsync with:<screen>svcprop -p config svc:/application/virtualbox/webservice:default</screen></para>
c9a593aa048a154e59b52d1237d89e3cdaee9b3dvboxsync <para>When everything is configured correctly you can start the
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync VirtualBox webservice with the following command:<screen>svcadm enable svc:/application/virtualbox/webservice:default</screen></para>
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync <para>For more information about SMF, please refer to the Solaris
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync documentation.</para>
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync <para>The Main API described in <xref linkend="sdkref_classes" /> and
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync <xref linkend="sdkref_enums" /> is mostly identical in all the supported
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync programming environments which have been briefly mentioned in the
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync introduction of this book. As a result, the Main API's general concepts
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync described in <xref linkend="concepts" /> are the same whether you use the
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync object-oriented web service (OOWS) for JAX-WS or a raw web service
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync connection via, say, Perl, or whether you use C++ COM bindings.</para>
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync <para>Some things are different depending on your environment, however.
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync These differences are explained in this chapter.</para>
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync <title>Using the object-oriented web service (OOWS)</title>
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync <para>As explained in <xref linkend="webservice-or-com" />, VirtualBox
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync ships with client-side libraries for Java, Python and PHP that allow you
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync to use the VirtualBox web service in an intuitive, object-oriented way.
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync These libraries shield you from the client-side complications of managed
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync object references and other implementation details that come with the
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync VirtualBox web service. (If you are interested in these complications,
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync have a look at <xref linkend="raw-webservice" />).</para>
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync <para>We recommend that you start your experiments with the VirtualBox
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync web service by using our object-oriented client libraries for JAX-WS, a
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync web service toolkit for Java, which enables you to write code to
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync interact with VirtualBox in the simplest manner possible.</para>
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync <para>As "interfaces", "attributes" and "methods" are COM concepts,
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync please read the documentation in <xref linkend="sdkref_classes" /> and
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync <xref linkend="sdkref_enums" /> with the following notes in mind.</para>
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync <para>The OOWS bindings attempt to map the Main API as closely as
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync possible to the Java, Python and PHP languages. In other words, objects
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync are objects, interfaces become classes, and you can call methods on
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync objects as you would on local objects.</para>
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync <para>The main difference remains with attributes: to read an attribute,
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync call a "getXXX" method, with "XXX" being the attribute name with a
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync capitalized first letter. So when the Main API Reference says that
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync <computeroutput>IMachine</computeroutput> has a "name" attribute (see
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync <xref linkend="IMachine__name" xreflabel="IMachine::name" />), call
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync <computeroutput>getName()</computeroutput> on an IMachine object to
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync obtain a machine's name. Unless the attribute is marked as read-only in
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync the documentation, there will also be a corresponding "set"
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync method.</para>
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync <title>The object-oriented web service for JAX-WS</title>
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync <para>JAX-WS is a powerful toolkit by Sun Microsystems to build both
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync server and client code with Java. It is part of Java 6 (JDK 1.6), but
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync can also be obtained separately for Java 5 (JDK 1.5). The VirtualBox
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync SDK comes with precompiled OOWS bindings working with both Java 5 and
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync <para>The following sections explain how to get the JAX-WS sample code
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync running and explain a few common practices when using the JAX-WS
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync object-oriented web service.</para>
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync <para>Since JAX-WS is already integrated into Java 6, no additional
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync preparations are needed for Java 6.</para>
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync <para>If you are using Java 5 (JDK 1.5.x), you will first need to
416817daa142e9bb7eaf14a1b10577978a5e691bvboxsync download and install an external JAX-WS implementation, as Java 5
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync does not support JAX-WS out of the box; for example, you can
2dd7b4388106de88d20f33a8aa6c85c8babf507bvboxsync download one from here: <ulink
2dd7b4388106de88d20f33a8aa6c85c8babf507bvboxsync 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>.
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync Then perform the installation (<computeroutput>java -jar
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync <title>Getting started: running the sample code</title>
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync <para>To run the OOWS for JAX-WS samples that we ship with the SDK,
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync perform the following steps: <orderedlist>
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync <para>Open a terminal and change to the directory where the
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync JAX-WS samples reside.<footnote>
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync <computeroutput>sdk/bindings/webservice/java/jax-ws/samples/</computeroutput>.</para>
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync </footnote> Examine the header of
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync <computeroutput>Makefile</computeroutput> to see if the
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync supplied variables (Java compiler, Java executable) and a few
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync other details match your system settings.</para>
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync </listitem>
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync <para>To start the VirtualBox web service, open a second
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync terminal and change to the directory where the VirtualBox
416817daa142e9bb7eaf14a1b10577978a5e691bvboxsync executables are located. Then type:<screen>/vboxwebsrv -v</screen></para>
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync <para>The web service now waits for connections and will run
416817daa142e9bb7eaf14a1b10577978a5e691bvboxsync until you press Ctrl+C in this second terminal. The -v
416817daa142e9bb7eaf14a1b10577978a5e691bvboxsync argument causes it to log all connections to the terminal.
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync (See <xref linkend="runvboxwebsrv" os="" /> for details on how
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync to run the web service.)</para>
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync </listitem>
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync <para>Back in the first terminal and still in the samples
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync directory, to start a simple client example just type:<screen>make run16</screen></para>
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync <para>if you're on a Java 6 system; on a Java 5 system, run
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync <computeroutput>make run15</computeroutput> instead.</para>
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync <para>This should work on all Unix-like systems such as Linux
416817daa142e9bb7eaf14a1b10577978a5e691bvboxsync and Solaris. For Windows systems, use commands similar to what
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync is used in the Makefile.</para>
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync <para>This will compile the
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync <computeroutput>clienttest.java</computeroutput> code on the
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync first call and then execute the resulting
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync <computeroutput>clienttest</computeroutput> class to show the
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync locally installed VMs (see below).</para>
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync </listitem>
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync <para>The <computeroutput>clienttest</computeroutput> sample
416817daa142e9bb7eaf14a1b10577978a5e691bvboxsync imitates a few typical command line tasks that
416817daa142e9bb7eaf14a1b10577978a5e691bvboxsync <computeroutput>VBoxManage</computeroutput>, VirtualBox's regular
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync command-line front-end, would provide (see the VirtualBox User
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync Manual for details). In particular, you can run:<itemizedlist>
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync vms</computeroutput>: show the virtual machines that are
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync registered locally.</para>
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync </listitem>
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync hostinfo</computeroutput>: show various information about the
416817daa142e9bb7eaf14a1b10577978a5e691bvboxsync host this VirtualBox installation runs on.</para>
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync </listitem>
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync <vmname|uuid></computeroutput>: start the given virtual
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync machine.</para>
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync </listitem>
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync <para>The <computeroutput>clienttest.java</computeroutput> sample
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync code illustrates common basic practices how to use the VirtualBox
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync OOWS for JAX-WS, which we will explain in more detail in the
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync following chapters.</para>
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync <para>Before a web service client can do anything useful, two
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync objects need to be created, as can be seen in the
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync <computeroutput>clienttest</computeroutput> constructor:<orderedlist>
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync <para>An instance of <xref linkend="IWebsessionManager"
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync xreflabel="IWebsessionManager" />, which is an interface
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync provided by the web service to manage "web sessions" -- that
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync is, stateful connections to the web service with persistent
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync objects upon which methods can be invoked.</para>
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync <para>In the OOWS for JAX-WS, the IWebsessionManager class
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync must be constructed explicitly, and a URL must be provided in
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync the constructor that specifies where the web service (the
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync server) awaits connections. The code in
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync <computeroutput>clienttest.java</computeroutput> connects to
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync "http://localhost:18083/", which is the default.</para>
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync <para>The port number, by default 18083, must match the port
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync number given to the
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync <computeroutput>vboxwebsrv</computeroutput> command line; see
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync </listitem>
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync linkend="IWebsessionManager__logon"
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync xreflabel="IWebsessionManager::logon()" />, which is the first
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync call that actually communicates with the server. This
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync authenticates the client with the web service and returns an
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync xreflabel="IVirtualBox" />, the most fundamental interface of
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync the VirtualBox web service, from which all other functionality
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync can be derived.</para>
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync <para>If logon doesn't work, please take another look at <xref
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync </listitem>
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync <para>The current OOWS for JAX-WS has certain memory management
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync related limitations. When you no longer need an object, call its
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync xreflabel="IManagedObjectRef::release()" /> method explicitly, which
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync frees appropriate managed reference, as is required by the raw
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync webservice; see <xref linkend="managed-object-references" /> for
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync details. This limitation may be reconsidered in a future version of
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync the VirtualBox SDK.</para>
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync <title>The object-oriented web service for Python</title>
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync <para>VirtualBox comes with two flavors of a Python API: one for web
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync service, discussed here, and one for the COM/XPCOM API discussed in
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync <xref linkend="pycom" />. The client code is mostly similar, except
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync for the initialization part, so it is up to the application developer
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync to choose the appropriate technology. Moreover, a common Python glue
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync layer exists, abstracting out concrete platform access details, see
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync <para>As indicated in <xref linkend="webservice-or-com" />, the
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync COM/XPCOM API gives better performance without the SOAP overhead, and
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync does not require a web server to be running. On the other hand, the
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync COM/XPCOM Python API requires a suitable Python bridge for your Python
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync installation (VirtualBox ships the most important ones for each
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync platform<footnote>
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync <para>On On Mac OS X only the Python versions bundled with the OS
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync are officially supported. This means Python 2.3 for 10.4, Python
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync 2.5 for 10.5 and Python 2.5 and 2.6 for 10.6.</para>
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync </footnote>), and you cannot connect to VirtualBox remotely. On
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync Windows, you can use the Main API from Python if the Win32 extensions
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync package for Python<footnote>
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync url="http://sourceforge.net/project/showfiles.php?group_id=78018">http://sourceforge.net/project/showfiles.php?group_id=78018</ulink>.</para>
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync <para>The VirtualBox OOWS for Python relies on the Python ZSI SOAP
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync implementation (see <ulink
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync url="http://pywebsvcs.sourceforge.net/zsi.html">http://pywebsvcs.sourceforge.net/zsi.html</ulink>),
2dd7b4388106de88d20f33a8aa6c85c8babf507bvboxsync which you will need to install locally before trying the examples.
2dd7b4388106de88d20f33a8aa6c85c8babf507bvboxsync Most Linux distributions come with package for ZSI, such as
2dd7b4388106de88d20f33a8aa6c85c8babf507bvboxsync <computeroutput>python-zsi</computeroutput> in Ubuntu.</para>
2dd7b4388106de88d20f33a8aa6c85c8babf507bvboxsync <para>To get started, open a terminal and change to the
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync <computeroutput>bindings/glue/python/sample</computeroutput>
2dd7b4388106de88d20f33a8aa6c85c8babf507bvboxsync directory, which contains an example of a simple interactive shell
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync able to control a VirtualBox instance. The shell is written using the
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync API layer, thereby hiding different implementation details, so it is
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync actually an example of code share among XPCOM, MSCOM and web services.
2dd7b4388106de88d20f33a8aa6c85c8babf507bvboxsync If you are interested in how to interact with the webservices layer
2dd7b4388106de88d20f33a8aa6c85c8babf507bvboxsync directly, have a look at
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync <computeroutput>install/vboxapi/__init__.py</computeroutput> which
2dd7b4388106de88d20f33a8aa6c85c8babf507bvboxsync contains the glue layer for all target platforms (i.e. XPCOM, MSCOM
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync and web services).</para>
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync <para>To start the shell, perform the following commands: <screen>/opt/VirtualBox/vboxwebsrv -t 0
2dd7b4388106de88d20f33a8aa6c85c8babf507bvboxsync # start webservice with object autocollection disabled
2dd7b4388106de88d20f33a8aa6c85c8babf507bvboxsync # your VirtualBox installation directory
2dd7b4388106de88d20f33a8aa6c85c8babf507bvboxsync # where you've extracted the SDK
2dd7b4388106de88d20f33a8aa6c85c8babf507bvboxsync/vboxshell.py -w </screen>See <xref linkend="vboxshell" /> for more
2dd7b4388106de88d20f33a8aa6c85c8babf507bvboxsync details on the shell's functionality. For you, as a VirtualBox
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync application developer, the vboxshell sample could be interesting as an
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync example of how to write code targeting both local and remote cases
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync (COM/XPCOM and SOAP). The common part of the shell is the same -- the
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync only difference is how it interacts with the invocation layer. You can
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync use the <computeroutput>connect</computeroutput> shell command to
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync connect to remote VirtualBox servers; in this case you can skip
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync starting the local webserver.</para>
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync <title>The object-oriented web service for PHP</title>
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync <para>VirtualBox also comes with object-oriented web service (OOWS)
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync wrappers for PHP5. These wrappers rely on the PHP SOAP
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync Extension<footnote>
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync <para>See <ulink url="???">http://www.php.net/soap</ulink>.</para>
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync </footnote>, which can be installed by configuring PHP with
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync <computeroutput>--enable-soap</computeroutput>.</para>
aa131431882ca8e44b0480d4af0b5d139f1bde21vboxsync <title>Using the raw web service with any language</title>
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync <para>The following examples show you how to use the raw web service,
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync without the object-oriented client-side code that was described in the
aa131431882ca8e44b0480d4af0b5d139f1bde21vboxsync previous chapter.</para>
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync <para>Generally, when reading the documentation in <xref
aa131431882ca8e44b0480d4af0b5d139f1bde21vboxsync linkend="sdkref_classes" /> and <xref linkend="sdkref_enums" />, due to
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync the limitations of SOAP and WSDL lined out in <xref
aa131431882ca8e44b0480d4af0b5d139f1bde21vboxsync linkend="rawws-conventions" />, please have the following notes in
aa131431882ca8e44b0480d4af0b5d139f1bde21vboxsync mind:</para>
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync <para>Any COM method call becomes a <emphasis role="bold">plain
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync function call</emphasis> in the raw web service, with the object
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync as an additional first parameter (before the "real" parameters
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync listed in the documentation). So when the documentation says that
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync the <computeroutput>IVirtualBox</computeroutput> interface
416817daa142e9bb7eaf14a1b10577978a5e691bvboxsync supports the <computeroutput>createMachine()</computeroutput>
416817daa142e9bb7eaf14a1b10577978a5e691bvboxsync method (see <xref linkend="IVirtualBox__createMachine"
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync xreflabel="IVirtualBox::createMachine()" />), the web service
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync operation is
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync <computeroutput>IVirtualBox_createMachine(...)</computeroutput>,
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync and a managed object reference to an
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync <computeroutput>IVirtualBox</computeroutput> object must be passed
416817daa142e9bb7eaf14a1b10577978a5e691bvboxsync as the first argument.</para>
416817daa142e9bb7eaf14a1b10577978a5e691bvboxsync </listitem>
416817daa142e9bb7eaf14a1b10577978a5e691bvboxsync <para>For <emphasis role="bold">attributes</emphasis> in
416817daa142e9bb7eaf14a1b10577978a5e691bvboxsync interfaces, there will be at least one "get" function; there will
416817daa142e9bb7eaf14a1b10577978a5e691bvboxsync also be a "set" function, unless the attribute is "readonly". The
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync attribute name will be appended to the "get" or "set" prefix, with
416817daa142e9bb7eaf14a1b10577978a5e691bvboxsync a capitalized first letter. So, the "version" readonly attribute
416817daa142e9bb7eaf14a1b10577978a5e691bvboxsync of the <computeroutput>IVirtualBox</computeroutput> interface can
416817daa142e9bb7eaf14a1b10577978a5e691bvboxsync be retrieved by calling
416817daa142e9bb7eaf14a1b10577978a5e691bvboxsync <computeroutput>IVirtualBox_getVersion(vbox)</computeroutput>,
416817daa142e9bb7eaf14a1b10577978a5e691bvboxsync with <computeroutput>vbox</computeroutput> being the VirtualBox
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync object.</para>
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync </listitem>
416817daa142e9bb7eaf14a1b10577978a5e691bvboxsync <para>Whenever the API documentation says that a method (or an
416817daa142e9bb7eaf14a1b10577978a5e691bvboxsync attribute getter) returns an <emphasis
416817daa142e9bb7eaf14a1b10577978a5e691bvboxsync role="bold">object</emphasis>, it will returned a managed object
416817daa142e9bb7eaf14a1b10577978a5e691bvboxsync reference in the web service instead. As said above, managed
416817daa142e9bb7eaf14a1b10577978a5e691bvboxsync object references should be released if the web service client
416817daa142e9bb7eaf14a1b10577978a5e691bvboxsync does not log off again immediately!</para>
416817daa142e9bb7eaf14a1b10577978a5e691bvboxsync </listitem>
416817daa142e9bb7eaf14a1b10577978a5e691bvboxsync <title>Raw web service example for Java with Axis</title>
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync <para>Axis is an older web service toolkit created by the Apache
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync foundation. If your distribution does not have it installed, you can
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync get a binary from <ulink
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync url="http://www.apache.org">http://www.apache.org</ulink>. The
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync following examples assume that you have Axis 1.4 installed.</para>
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync <para>The VirtualBox SDK ships with an example for Axis that, again,
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync is called <computeroutput>clienttest.java</computeroutput> and that
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync imitates a few of the commands of
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync <computeroutput>VBoxManage</computeroutput> over the wire.</para>
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync <para>Then perform the following steps:<orderedlist>
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync <para>Create a working directory somewhere. Under your
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync VirtualBox installation directory, find the
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync <computeroutput>sdk/webservice/samples/java/axis/</computeroutput>
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync directory and copy the file
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync <computeroutput>clienttest.java</computeroutput> to your working
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync directory.</para>
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync </listitem>
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync <para>Open a terminal in your working directory. Execute the
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync following command:<screen> java org.apache.axis.wsdl.WSDL2Java /path/to/vboxwebService.wsdl</screen></para>
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync <para>The <computeroutput>vboxwebService.wsdl</computeroutput>
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync file should be located in the
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync directory.</para>
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync <para>If this fails, your Apache Axis may not be located on your
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync system classpath, and you may have to adjust the CLASSPATH
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync environment variable. Something like this:<screen>export CLASSPATH="/path-to-axis-1_4/lib/*":$CLASSPATH</screen></para>
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync <para>Use the directory where the Axis JAR files are located.
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync Mind the quotes so that your shell passes the "*" character to
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync the java executable without expanding. Alternatively, add a
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync corresponding <computeroutput>-classpath</computeroutput>
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync argument to the "java" call above.</para>
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync <para>If the command executes successfully, you should see an
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync "org" directory with subdirectories containing Java source files
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync in your working directory. These classes represent the
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync interfaces that the VirtualBox web service offers, as described
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync by the WSDL file.</para>
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync <para>This is the bit that makes using web services so
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync attractive to client developers: if a language's toolkit
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync understands WSDL, it can generate large amounts of support code
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync automatically. Clients can then easily use this support code and
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync can be done with just a few lines of code.</para>
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync </listitem>
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync <para>Next, compile the
416817daa142e9bb7eaf14a1b10577978a5e691bvboxsync <computeroutput>clienttest.java</computeroutput> source:<screen>javac clienttest.java </screen></para>
416817daa142e9bb7eaf14a1b10577978a5e691bvboxsync <para>This should yield a "clienttest.class" file.</para>
416817daa142e9bb7eaf14a1b10577978a5e691bvboxsync </listitem>
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync <para>To start the VirtualBox web service, open a second
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync terminal and change to the directory where the VirtualBox
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync executables are located. Then type:<screen>/vboxwebsrv -v</screen></para>
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync <para>The web service now waits for connections and will run
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync until you press Ctrl+C in this second terminal. The -v argument
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync causes it to log all connections to the terminal. (See <xref
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync linkend="runvboxwebsrv" os="" /> for details on how to run the
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync web service.)</para>
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync </listitem>
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync <para>Back in the original terminal where you compiled the Java
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync source, run the resulting binary, which will then connect to the
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync web service:<screen>java clienttest</screen></para>
f78f5019eca211061be2ee77e84dd9f423767183vboxsync <para>The client sample will connect to the web service (on
f78f5019eca211061be2ee77e84dd9f423767183vboxsync localhost, but the code could be changed to connect remotely if
18c375d98041304c1269b040da9feda2f78ca5d9vboxsync the web service was running on a different machine) and make a
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync number of method calls. It will output the version number of
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync your VirtualBox installation and a list of all virtual machines
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync that are currently registered (with a bit of seemingly random
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync data, which will be explained later).</para>
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync </listitem>
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync <para>We also ship a small sample for Perl. It uses the SOAP::Lite
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync perl module to communicate with the VirtualBox web service.</para>
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync <computeroutput>sdk/bindings/webservice/perl/lib/</computeroutput>
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync directory contains a pre-generated Perl module that allows for
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync communicating with the web service from Perl. You can generate such a
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync module yourself using the "stubmaker" tool that comes with SOAP::Lite,
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync but since that tool is slow as well as sometimes unreliable, we are
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync shipping a working module with the SDK for your convenience.</para>
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync <para>If SOAP::Lite is not yet installed on your system, you
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync will need to install the package first. On Debian-based systems,
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync the package is called
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync <computeroutput>libsoap-lite-perl</computeroutput>; on Gentoo,
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync it's <computeroutput>dev-perl/SOAP-Lite</computeroutput>.</para>
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync </listitem>
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync <para>Open a terminal in the
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync <computeroutput>sdk/bindings/webservice/perl/samples/</computeroutput>
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync directory.</para>
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync </listitem>
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync <para>To start the VirtualBox web service, open a second
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync terminal and change to the directory where the VirtualBox
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync executables are located. Then type:<screen>/vboxwebsrv -v</screen></para>
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync <para>The web service now waits for connections and will run
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync until you press Ctrl+C in this second terminal. The -v argument
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync causes it to log all connections to the terminal. (See <xref
aa131431882ca8e44b0480d4af0b5d139f1bde21vboxsync linkend="runvboxwebsrv" os="" /> for details on how to run the
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync web service.)</para>
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync </listitem>
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync <para>In the first terminal with the Perl sample, run the
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync clienttest.pl script:<screen>perl -I /lib clienttest.pl</screen></para>
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync </listitem>
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync <title>Programming considerations for the raw web service</title>
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync <para>If you use the raw web service, you need to keep a number of
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync things in mind, or you will sooner or later run into issues that are
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync not immediately obvious. By contrast, the object-oriented client-side
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync libraries described in <xref linkend="glue" /> take care of these
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync things automatically and thus greatly simplify using the web
b8cb4b19424947b4dbd41fd2ce4e03641b3377cavboxsync service.</para>
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync <para>If you are familiar with other web services, you may find the
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync VirtualBox web service to behave a bit differently to accommodate
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync for the fact that VirtualBox web service more or less maps the
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync VirtualBox Main COM API. The following main differences had to be
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync taken care of:<itemizedlist>
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync <para>Web services, as expressed by WSDL, are not
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync object-oriented. Even worse, they are normally stateless (or,
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync in web services terminology, "loosely coupled"). Web service
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync operations are entirely procedural, and one cannot normally
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync make assumptions about the state of a web service between
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync function calls.</para>
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync <para>In particular, this normally means that you cannot work
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync on objects in one method call that were created by another
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync call.</para>
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync </listitem>
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync <para>By contrast, the VirtualBox Main API, being expressed in
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync COM, is object-oriented and works entirely on objects, which
ad27e1d5e48ca41245120c331cc88b50464813cevboxsync are grouped into public interfaces, which in turn have
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync attributes and methods associated with them.</para>
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync </listitem>
416817daa142e9bb7eaf14a1b10577978a5e691bvboxsync </itemizedlist> For the VirtualBox web service, this results in
fabb3e1e51b589494ebe849b7c000e8bcc9ff473vboxsync three fundamental conventions:<orderedlist>
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync <para>All <emphasis role="bold">function names</emphasis> in
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync the VirtualBox web service consist of an interface name and a
416817daa142e9bb7eaf14a1b10577978a5e691bvboxsync method name, joined together by an underscore. This is because
416817daa142e9bb7eaf14a1b10577978a5e691bvboxsync there are only functions ("operations") in WSDL, but no
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync classes, interfaces, or methods.</para>
416817daa142e9bb7eaf14a1b10577978a5e691bvboxsync <para>In addition, all calls to the VirtualBox web service
416817daa142e9bb7eaf14a1b10577978a5e691bvboxsync (except for logon, see below) take a <emphasis
416817daa142e9bb7eaf14a1b10577978a5e691bvboxsync role="bold">managed object reference</emphasis> as the first
416817daa142e9bb7eaf14a1b10577978a5e691bvboxsync argument, representing the object upon which the underlying
416817daa142e9bb7eaf14a1b10577978a5e691bvboxsync method is invoked. (Managed object references are explained in
416817daa142e9bb7eaf14a1b10577978a5e691bvboxsync detail below; see <xref
416817daa142e9bb7eaf14a1b10577978a5e691bvboxsync <para>So, when one would normally code, in the pseudo-code of
416817daa142e9bb7eaf14a1b10577978a5e691bvboxsync an object-oriented language, to invoke a method upon an
aa131431882ca8e44b0480d4af0b5d139f1bde21vboxsync object:<screen>IMachine machine;
416817daa142e9bb7eaf14a1b10577978a5e691bvboxsync <para>In the VirtualBox web service, this looks something like
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync this (again, pseudo-code):<screen>IMachineRef machine;
416817daa142e9bb7eaf14a1b10577978a5e691bvboxsync </listitem>
416817daa142e9bb7eaf14a1b10577978a5e691bvboxsync <para>To make the web service stateful, and objects persistent
416817daa142e9bb7eaf14a1b10577978a5e691bvboxsync between method calls, the VirtualBox web service introduces a
416817daa142e9bb7eaf14a1b10577978a5e691bvboxsync <emphasis role="bold">session manager</emphasis> (by way of
416817daa142e9bb7eaf14a1b10577978a5e691bvboxsync xreflabel="IWebsessionManager" /> interface), which manages
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync object references. Any client wishing to interact with the web
416817daa142e9bb7eaf14a1b10577978a5e691bvboxsync service must first log on to the session manager and in turn
f78f5019eca211061be2ee77e84dd9f423767183vboxsync receives a managed object reference to an object that supports
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync the <xref linkend="IVirtualBox" xreflabel="IVirtualBox" />
416817daa142e9bb7eaf14a1b10577978a5e691bvboxsync interface (the basic interface in the Main API).</para>
416817daa142e9bb7eaf14a1b10577978a5e691bvboxsync </listitem>
416817daa142e9bb7eaf14a1b10577978a5e691bvboxsync <para>In other words, as opposed to other web services, <emphasis
416817daa142e9bb7eaf14a1b10577978a5e691bvboxsync role="bold">the VirtualBox web service is both object-oriented and
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync <title>Example: A typical web service client session</title>
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync <para>A typical short web service session to retrieve the version
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync number of the VirtualBox web service (to be precise, the underlying
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync Main API version number) looks like this:<orderedlist>
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync <para>A client logs on to the web service by calling <xref
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync linkend="IWebsessionManager__logon"
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync xreflabel="IWebsessionManager::logon()" /> with a valid user
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync name and password. See <xref linkend="websrv_authenticate" />
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync for details about how authentication works.</para>
aa131431882ca8e44b0480d4af0b5d139f1bde21vboxsync </listitem>
aa131431882ca8e44b0480d4af0b5d139f1bde21vboxsync <para>On the server side,
aa131431882ca8e44b0480d4af0b5d139f1bde21vboxsync <computeroutput>vboxwebsrv</computeroutput> creates a session,
aa131431882ca8e44b0480d4af0b5d139f1bde21vboxsync which persists until the client calls <xref
aa131431882ca8e44b0480d4af0b5d139f1bde21vboxsync linkend="IWebsessionManager__logoff"
aa131431882ca8e44b0480d4af0b5d139f1bde21vboxsync xreflabel="IWebsessionManager::logoff()" /> or the session
aa131431882ca8e44b0480d4af0b5d139f1bde21vboxsync times out after a configurable period of inactivity (see <xref
aa131431882ca8e44b0480d4af0b5d139f1bde21vboxsync <para>For the new session, the web service creates an instance
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync of <xref linkend="IVirtualBox" xreflabel="IVirtualBox" />.
aa131431882ca8e44b0480d4af0b5d139f1bde21vboxsync This interface is the most central one in the Main API and
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync allows access to all other interfaces, either through
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync attributes or method calls. For example, IVirtualBox contains
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync a list of all virtual machines that are currently registered
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync (as they would be listed on the left side of the VirtualBox
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync main program).</para>
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync <para>The web service then creates a managed object reference
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync for this instance of IVirtualBox and returns it to the calling
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync client, which receives it as the return value of the logon
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync call. Something like this:</para>
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync <screen>string oVirtualBox;
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsyncoVirtualBox = webservice.IWebsessionManager_logon("user", "pass");</screen>
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync <para>(The managed object reference "oVirtualBox" is just a
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync string consisting of digits and dashes. However, it is a
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync string with a meaning and will be checked by the web service.
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync For details, see below. As hinted above, <xref
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync linkend="IWebsessionManager__logon"
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync xreflabel="IWebsessionManager::logon()" /> is the
aa131431882ca8e44b0480d4af0b5d139f1bde21vboxsync <emphasis>only</emphasis> operation provided by the web
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync service which does not take a managed object reference as the
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync first argument!)</para>
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync </listitem>
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync <para>The VirtualBox Main API documentation says that the
aa131431882ca8e44b0480d4af0b5d139f1bde21vboxsync <computeroutput>IVirtualBox</computeroutput> interface has a
416817daa142e9bb7eaf14a1b10577978a5e691bvboxsync <xref linkend="IVirtualBox__version" xreflabel="version" />
416817daa142e9bb7eaf14a1b10577978a5e691bvboxsync attribute, which is a string. For each attribute, there is a
416817daa142e9bb7eaf14a1b10577978a5e691bvboxsync "get" and a "set" method in COM, which maps to according
416817daa142e9bb7eaf14a1b10577978a5e691bvboxsync operations in the web service. So, to retrieve the "version"
416817daa142e9bb7eaf14a1b10577978a5e691bvboxsync attribute of this <computeroutput>IVirtualBox</computeroutput>
416817daa142e9bb7eaf14a1b10577978a5e691bvboxsync object, the web service client does this:<screen>string version;
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsyncversion = webservice.IVirtualBox_getVersion(oVirtualBox);
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync <para>And it will print
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync "$VBOX_VERSION_MAJOR.$VBOX_VERSION_MINOR.$VBOX_VERSION_BUILD".</para>
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync </listitem>
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync linkend="IWebsessionManager__logoff"
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync xreflabel="IWebsessionManager::logoff()" /> with the
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync VirtualBox managed object reference. This will clean up all
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync allocated resources.</para>
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync </listitem>
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync <para>To a web service client, a managed object reference looks like
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync a string: two 64-bit hex numbers separated by a dash. This string,
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync however, represents a COM object that "lives" in the web service
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync process. The two 64-bit numbers encoded in the managed object
129986ce8b48d5e5973ad84edae4465788db89aavboxsync reference represent a session ID (which is the same for all objects
129986ce8b48d5e5973ad84edae4465788db89aavboxsync in the same web service session, i.e. for all objects after one
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync logon) and a unique object ID within that session.</para>
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync <para>Managed object references are created in two
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync situations:<orderedlist>
129986ce8b48d5e5973ad84edae4465788db89aavboxsync linkend="IWebsessionManager__logon"
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync <para>Upon logon, the websession manager creates one instance
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync of <xref linkend="IVirtualBox" xreflabel="IVirtualBox" /> and
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync xreflabel="ISession" /> representing the web service session.
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync This can be retrieved using <xref
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync linkend="IWebsessionManager__getSessionObject"
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync xreflabel="IWebsessionManager::getSessionObject()" />.</para>
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync linkend="IVirtualBox" xreflabel="IVirtualBox" /> object, which
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync is shared between all sessions and clients, as it is a COM
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync singleton. However, each session receives its own managed
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync object reference to it. The <xref linkend="ISession"
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync xreflabel="ISession" /> object, however, is created and
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync destroyed for each session.)</para>
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync </listitem>
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync <para>Whenever a web service clients invokes an operation
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync whose COM implementation creates COM objects.</para>
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync <para>For example, <xref linkend="IVirtualBox__createMachine"
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync xreflabel="IVirtualBox::createMachine()" /> creates a new
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync instance of <xref linkend="IMachine" xreflabel="IMachine" />;
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync the COM object returned by the COM method call is then wrapped
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync into a managed object reference by the web server, and this
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync reference is returned to the web service client.</para>
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync </listitem>
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync <para>Internally, in the web service process, each managed object
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync reference is simply a small data structure, containing a COM pointer
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync to the "real" COM object, the web session ID and the object ID. This
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync structure is allocated on creation and stored efficiently in hashes,
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync so that the web service can look up the COM object quickly whenever
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync a web service client wishes to make a method call. The random
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync session ID also ensures that one web service client cannot intercept
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync the objects of another.</para>
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync <para>Managed object references are not destroyed automatically and
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync must be released by explicitly calling <xref
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync linkend="IManagedObjectRef__release"
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync xreflabel="IManagedObjectRef::release()" />. This is important, as
fabb3e1e51b589494ebe849b7c000e8bcc9ff473vboxsync otherwise hundreds or thousands of managed object references (and
fabb3e1e51b589494ebe849b7c000e8bcc9ff473vboxsync corresponding COM objects, which can consume much more memory!) can
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync pile up in the web service process and eventually cause it to deny
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync service.</para>
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync <para>To reiterate: The underlying COM object, which the reference
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync points to, is only freed if the managed object reference is
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync released. It is therefore vital that web service clients properly
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync clean up after the managed object references that are returned to
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync them.</para>
fabb3e1e51b589494ebe849b7c000e8bcc9ff473vboxsync linkend="IWebsessionManager__logoff"
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync xreflabel="IWebsessionManager::logoff()" />, all managed object
fabb3e1e51b589494ebe849b7c000e8bcc9ff473vboxsync references created during the session are automatically freed. For
fabb3e1e51b589494ebe849b7c000e8bcc9ff473vboxsync short-lived sessions that do not create a lot of objects, logging
fabb3e1e51b589494ebe849b7c000e8bcc9ff473vboxsync off may therefore be sufficient, although it is certainly not "best
fabb3e1e51b589494ebe849b7c000e8bcc9ff473vboxsync practice".</para>
fabb3e1e51b589494ebe849b7c000e8bcc9ff473vboxsync <title>Some more detail about web service operation</title>
fabb3e1e51b589494ebe849b7c000e8bcc9ff473vboxsync <para>Whenever a client makes a call to a web service, this
fabb3e1e51b589494ebe849b7c000e8bcc9ff473vboxsync involves a complicated procedure internally. These calls are
fabb3e1e51b589494ebe849b7c000e8bcc9ff473vboxsync remote procedure calls. Each such procedure call typically
fabb3e1e51b589494ebe849b7c000e8bcc9ff473vboxsync consists of two "message" being passed, where each message is a
fabb3e1e51b589494ebe849b7c000e8bcc9ff473vboxsync plain-text HTTP request with a standard HTTP header and a special
fabb3e1e51b589494ebe849b7c000e8bcc9ff473vboxsync XML document following. This XML document encodes the name of the
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync procedure to call and the argument names and values passed to
fabb3e1e51b589494ebe849b7c000e8bcc9ff473vboxsync <para>To give you an idea of what such a message looks like,
fabb3e1e51b589494ebe849b7c000e8bcc9ff473vboxsync assuming that a web service provides a procedure called
fabb3e1e51b589494ebe849b7c000e8bcc9ff473vboxsync "SayHello", which takes a string "name" as an argument and returns
fabb3e1e51b589494ebe849b7c000e8bcc9ff473vboxsync "Hello" with a space and that name appended, the request message
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync could look like this:</para>
fabb3e1e51b589494ebe849b7c000e8bcc9ff473vboxsync <para><screen><?xml version="1.0" encoding="UTF-8"?>
fabb3e1e51b589494ebe849b7c000e8bcc9ff473vboxsync<SOAP-ENV:Envelope
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
fabb3e1e51b589494ebe849b7c000e8bcc9ff473vboxsync xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/"
fabb3e1e51b589494ebe849b7c000e8bcc9ff473vboxsync xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync xmlns:test="http://test/">
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync<SOAP-ENV:Body>
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync <test:SayHello>
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync <name>Peter</name>
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync </test:SayHello>
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync </SOAP-ENV:Body>
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync</SOAP-ENV:Envelope></screen>A similar message -- the "response" message
fabb3e1e51b589494ebe849b7c000e8bcc9ff473vboxsync -- would be sent back from the web service to the client,
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync containing the return value "Hello Peter".</para>
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync <para>Most programming languages provide automatic support to
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync generate such messages whenever code in that programming language
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync makes such a request. In other words, these programming languages
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync allow for writing something like this (in pseudo-C++ code):</para>
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync <para><screen>webServiceClass service("localhost", 18083); // server and port
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsyncstring result = service.SayHello("Peter"); // invoke remote procedure</screen>and
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync would, for these two pseudo-lines, automatically perform these
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync steps:</para>
fabb3e1e51b589494ebe849b7c000e8bcc9ff473vboxsync <para>prepare a connection to a web service running on port
fabb3e1e51b589494ebe849b7c000e8bcc9ff473vboxsync 18083 of "localhost";</para>
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync </listitem>
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync <para>for the <computeroutput>SayHello()</computeroutput>
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync function of the web service, generate a SOAP message like in
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync the above example by encoding all arguments of the remote
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync procedure call (which could involve all kinds of type
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync conversions and complex marshalling for arrays and
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync structures);</para>
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync </listitem>
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync <para>connect to the web service via HTTP and send that
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync message;</para>
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync </listitem>
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync <para>wait for the web service to send a response
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync message;</para>
fabb3e1e51b589494ebe849b7c000e8bcc9ff473vboxsync </listitem>
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync <para>decode that response message and put the return value
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync of the remote procedure into the "result" variable.</para>
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync </listitem>
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync <para>In the above explanations about SOAP, it was left open how
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync the programming language learns about how to translate function
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync calls in its own syntax into proper SOAP messages. In other words,
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync the programming language needs to know what operations the web
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync service supports and what types of arguments are required for the
fabb3e1e51b589494ebe849b7c000e8bcc9ff473vboxsync operation's data in order to be able to properly serialize and
fabb3e1e51b589494ebe849b7c000e8bcc9ff473vboxsync deserialize the data to and from the web service. For example, if
fabb3e1e51b589494ebe849b7c000e8bcc9ff473vboxsync a web service operation expects a number in "double" floating
fabb3e1e51b589494ebe849b7c000e8bcc9ff473vboxsync point format for a particular parameter, the programming language
fabb3e1e51b589494ebe849b7c000e8bcc9ff473vboxsync cannot send to it a string instead.</para>
fabb3e1e51b589494ebe849b7c000e8bcc9ff473vboxsync <para>For this, the Web Service Definition Language (WSDL) was
fabb3e1e51b589494ebe849b7c000e8bcc9ff473vboxsync invented, another XML substandard that describes exactly what
fabb3e1e51b589494ebe849b7c000e8bcc9ff473vboxsync operations the web service supports and, for each operation, which
fabb3e1e51b589494ebe849b7c000e8bcc9ff473vboxsync parameters and types are needed with each request and response
fabb3e1e51b589494ebe849b7c000e8bcc9ff473vboxsync message. WSDL descriptions can be incredibly verbose, and one of
fabb3e1e51b589494ebe849b7c000e8bcc9ff473vboxsync the few good things that can be said about this standard is that
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync it is indeed supported by most programming languages.</para>
fabb3e1e51b589494ebe849b7c000e8bcc9ff473vboxsync <para>So, if it is said that a programming language "supports" web
fabb3e1e51b589494ebe849b7c000e8bcc9ff473vboxsync services, this typically means that a programming language has
fabb3e1e51b589494ebe849b7c000e8bcc9ff473vboxsync support for parsing WSDL files and somehow integrating the remote
fabb3e1e51b589494ebe849b7c000e8bcc9ff473vboxsync procedure calls into the native language syntax -- for example,
fabb3e1e51b589494ebe849b7c000e8bcc9ff473vboxsync like in the Java sample shown in <xref
fabb3e1e51b589494ebe849b7c000e8bcc9ff473vboxsync <para>For details about how programming languages support web
fabb3e1e51b589494ebe849b7c000e8bcc9ff473vboxsync services, please refer to the documentation that comes with the
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync individual languages. Here are a few pointers:</para>
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync <orderedlist>
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync <para>For <emphasis role="bold">C++,</emphasis> among many
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync others, the gSOAP toolkit is a good option. Parts of gSOAP are
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync also used in VirtualBox to implement the VirtualBox web
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync service.</para>
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync </listitem>
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync <para>For <emphasis role="bold">Java,</emphasis> there are
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync several implementations already described in this document
fabb3e1e51b589494ebe849b7c000e8bcc9ff473vboxsync </listitem>
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync <para><emphasis role="bold">Perl</emphasis> supports WSDL via
fabb3e1e51b589494ebe849b7c000e8bcc9ff473vboxsync the SOAP::Lite package. This in turn comes with a tool called
fabb3e1e51b589494ebe849b7c000e8bcc9ff473vboxsync <computeroutput>stubmaker.pl</computeroutput> that allows you
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync to turn any WSDL file into a Perl package that you can import.
fabb3e1e51b589494ebe849b7c000e8bcc9ff473vboxsync (You can also import any WSDL file "live" by having it parsed
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync every time the script runs, but that can take a while.) You
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync can then code (again, assuming the above example):<screen>my $result = servicename->sayHello("Peter");</screen></para>
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync <para>A sample that uses SOAP::Lite was described in <xref
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync </listitem>
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync </orderedlist>
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync <para>If you do not require <emphasis>remote</emphasis> procedure calls
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync such as those offered by the VirtualBox web service, and if you know
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync Python or C++ as well as COM, you might find it preferable to program
fabb3e1e51b589494ebe849b7c000e8bcc9ff473vboxsync VirtualBox's Main API directly via COM.</para>
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync <para>COM stands for "Component Object Model" and is a standard
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync originally introduced by Microsoft in the 1990s for Microsoft Windows.
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync It allows for organizing software in an object-oriented way and across
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync processes; code in one process may access objects that live in another
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync process.</para>
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync <para>COM has several advantages: it is language-neutral, meaning that
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync even though all of VirtualBox is internally written in C++, programs
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync written in other languages could communicate with it. COM also cleanly
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync separates interface from implementation, so that external programs need
fabb3e1e51b589494ebe849b7c000e8bcc9ff473vboxsync not know anything about the messy and complicated details of VirtualBox
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync internals.</para>
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync <para>On a Windows host, all parts of VirtualBox will use the COM
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync functionality that is native to Windows. On other hosts (including
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync Linux), VirtualBox comes with a built-in implementation of XPCOM, as
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync originally created by the Mozilla project, which we have enhanced to
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync support interprocess communication on a level comparable to Microsoft
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync COM. Internally, VirtualBox has an abstraction layer that allows the
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync same VirtualBox code to work both with native COM as well as our XPCOM
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync implementation.</para>
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync <para>On Windows, Python scripts can use COM and VirtualBox interfaces
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync to control almost all aspects of virtual machine execution. As an
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync example, use the following commands to instantiate the VirtualBox
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync object and start a VM: <screen>
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync vbox = win32com.client.Dispatch("VirtualBox.VirtualBox")
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync session = win32com.client.Dispatch("VirtualBox.Session")
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync mach = vbox.findMachine("uuid or name of machine to start")
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync progress = mach.launchVMProcess(session, "gui", "")
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync </screen> Also, see
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync <computeroutput>/bindings/glue/python/samples/vboxshell.py</computeroutput>
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync for more advanced usage scenarious. However, unless you have specific
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync requirements, we strongly recommend to use the generic glue layer
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync described in the next section to access MS COM objects.</para>
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync <para>As different wrappers ultimately provide access to the same
fabb3e1e51b589494ebe849b7c000e8bcc9ff473vboxsync underlying API, and to simplify porting and development of Python
fabb3e1e51b589494ebe849b7c000e8bcc9ff473vboxsync application using the VirtualBox Main API, we developed a common glue
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync layer that abstracts out most platform-specific details from the
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync application and allows the developer to focus on application logic.
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync The VirtualBox installer automatically sets up this glue layer for the
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync system default Python install. See below for details on how to set up
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync the glue layer if you want to use a different Python
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync installation.</para>
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync <para>In this layer, the class
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync <computeroutput>VirtualBoxManager</computeroutput> hides most
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync platform-specific details. It can be used to access both the local
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync (COM) and the webservice-based API. The following code can be used by
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync an application to use the glue layer.</para>
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync <screen># This code assumes vboxapi.py from VirtualBox distribution
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync# being in PYTHONPATH, or installed system-wide
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsyncfrom vboxapi import VirtualBoxManager
416817daa142e9bb7eaf14a1b10577978a5e691bvboxsync# This code initializes VirtualBox manager with default style
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync# and parameters
416817daa142e9bb7eaf14a1b10577978a5e691bvboxsyncvirtualBoxManager = VirtualBoxManager(None, None)
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync# Alternatively, one can be more verbose, and initialize
aa131431882ca8e44b0480d4af0b5d139f1bde21vboxsync# glue with webservice backend, and provide authentication
aa131431882ca8e44b0480d4af0b5d139f1bde21vboxsync# information
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsyncvirtualBoxManager = VirtualBoxManager("WEBSERVICE",
aa131431882ca8e44b0480d4af0b5d139f1bde21vboxsync 'user':'me',
aa131431882ca8e44b0480d4af0b5d139f1bde21vboxsync 'password':'secret'}) </screen>
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync <para>We supply the <computeroutput>VirtualBoxManager</computeroutput>
416817daa142e9bb7eaf14a1b10577978a5e691bvboxsync constructor with 2 arguments: style and parameters. Style defines
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync which bindings style to use (could be "MSCOM", "XPCOM" or
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync "WEBSERVICE"), and if set to <computeroutput>None</computeroutput>
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync defaults to usable platform bindings (MS COM on Windows, XPCOM on
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync other platforms). The second argument defines parameters, passed to
416817daa142e9bb7eaf14a1b10577978a5e691bvboxsync the platform-specific module, as we do in the second example, where we
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync pass username and password to be used to authenticate against the web
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync service.</para>
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync <para>After obtaining the
c9819fb7aaf7275898c2a4ad2f891245a4a13e67vboxsync <computeroutput>VirtualBoxManager</computeroutput> instance, one can
c9819fb7aaf7275898c2a4ad2f891245a4a13e67vboxsync perform operations on the IVirtualBox class. For example, the
416817daa142e9bb7eaf14a1b10577978a5e691bvboxsync following code will a start virtual machine by name or ID:</para>
c9819fb7aaf7275898c2a4ad2f891245a4a13e67vboxsyncprint "Version is",vbox.version
c9819fb7aaf7275898c2a4ad2f891245a4a13e67vboxsyncdef machById(id):
c9819fb7aaf7275898c2a4ad2f891245a4a13e67vboxsync mach = None
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync for m in virtualBoxManager.getArray(vbox, 'machines'):
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync return mach
730f8be51b729e8a3c1e32c756cd0f4ec088dd4dvboxsyncname = "Linux"
730f8be51b729e8a3c1e32c756cd0f4ec088dd4dvboxsyncmach = machById(name)
fabb3e1e51b589494ebe849b7c000e8bcc9ff473vboxsyncif mach is None:
c9819fb7aaf7275898c2a4ad2f891245a4a13e67vboxsync print "cannot find machine",name
c9819fb7aaf7275898c2a4ad2f891245a4a13e67vboxsync session = mgr.getSessionObject(vbox)
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync # one can also start headless session with "vrdp" instead of "gui"
fabb3e1e51b589494ebe849b7c000e8bcc9ff473vboxsync progress = vb.openRemoteSession(session, mach.id, "gui", "")
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync <para>This code also shows cross-platform access to array properties
fabb3e1e51b589494ebe849b7c000e8bcc9ff473vboxsync (certain limitations prevent one from using
fabb3e1e51b589494ebe849b7c000e8bcc9ff473vboxsync <computeroutput>vbox.machines</computeroutput> to access a list of
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync available virtual machines in case of XPCOM), and a mechanism of
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync uniform session creation
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync (<computeroutput>virtualBoxManager.mgr.getSessionObject()</computeroutput>).</para>
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync <para>In case you want to use the glue layer with a different Python
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync installation, use these steps in a shell to add the necessary
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync files:</para>
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync <para>C++ is the language that VirtualBox itself is written in, so C++
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync is the most direct way to use the Main API -- but it is not
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync necessarily the easiest, as using COM and XPCOM has its own set of
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync complications.</para>
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync <para>VirtualBox ships with sample programs that demonstrate how to
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync use the Main API to implement a number of tasks on your host platform.
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync These samples can be found in the
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync <computeroutput>/bindings/xpcom/samples</computeroutput> directory for
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync Linux, Mac OS X and Solaris and
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync <computeroutput>/bindings/mscom/samples</computeroutput> for Windows.
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync The two samples are actually different, because the one for Windows
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync uses native COM, whereas the other uses our XPCOM implementation, as
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync described above.</para>
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync <para>Since COM and XPCOM are conceptually very similar but vary in
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync the implementation details, we have created a "glue" layer that
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync shields COM client code from these differences. All VirtualBox uses is
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync this glue layer, so the same code written once works on both Windows
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync hosts (with native COM) as well as on other hosts (with our XPCOM
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync implementation). It is recommended to always use this glue code
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync instead of using the COM and XPCOM APIs directly, as it is very easy
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync to make your code completely independent from the platform it is
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync running on.<!-- A third sample,
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync <computeroutput>tstVBoxAPIGlue.cpp</computeroutput>, illustrates how to
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync use the glue layer.
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync <para>In order to encapsulate platform differences between Microsoft
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync COM and XPCOM, the following items should be kept in mind when using
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync the glue layer:</para>
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync setters.</emphasis> COM has the notion of "attributes" in
730f8be51b729e8a3c1e32c756cd0f4ec088dd4dvboxsync interfaces, which roughly compare to C++ member variables in
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync classes. The difference is that for each attribute declared in
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync an interface, COM automatically provides a "get" method to
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync return the attribute's value. Unless the attribute has been
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync marked as "readonly", a "set" attribute is also provided.</para>
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync <para>To illustrate, the IVirtualBox interface has a "version"
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync attribute, which is read-only and of the "wstring" type (the
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync standard string type in COM). As a result, you can call the
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync "get" method for this attribute to retrieve the version number
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync of VirtualBox.</para>
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync <para>Unfortunately, the implementation differs between COM and
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync XPCOM. Microsoft COM names the "get" method like this:
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync <computeroutput>get_Attribute()</computeroutput>, whereas XPCOM
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync uses this syntax:
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync <computeroutput>GetAttribute()</computeroutput> (and accordingly
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync for "set" methods). To hide these differences, the VirtualBox
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync glue code provides the
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync <computeroutput>COMGETTER(attrib)</computeroutput> and
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync <computeroutput>COMSETTER(attrib)</computeroutput> macros. So,
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync <computeroutput>COMGETTER(version)()</computeroutput> (note, two
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync pairs of brackets) expands to
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync <computeroutput>get_Version()</computeroutput> on Windows and
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync <computeroutput>GetVersion()</computeroutput> on other
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync platforms.</para>
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync </listitem>
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync <para><emphasis role="bold">Unicode conversions.</emphasis>
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync While the rest of the modern world has pretty much settled on
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync encoding strings in UTF-8, COM, unfortunately, uses UCS-16
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync encoding. This requires a lot of conversions, in particular
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync between the VirtualBox Main API and the Qt GUI, which, like the
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync rest of Qt, likes to use UTF-8.</para>
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync <para>To facilitate these conversions, VirtualBox provides the
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync <computeroutput>com::Utf8Str</computeroutput> classes, which
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync support all kinds of conversions back and forth.</para>
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync </listitem>
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync <para><emphasis role="bold">COM autopointers.</emphasis>
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync Possibly the greatest pain of using COM -- reference counting --
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync is alleviated by the
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync <computeroutput>ComPtr<></computeroutput> template
d862f0eeb9eacdb46b9f5cc420de30a3d7c2c3f6vboxsync provided by the <computeroutput>ptr.h</computeroutput> file in
d862f0eeb9eacdb46b9f5cc420de30a3d7c2c3f6vboxsync the glue layer.</para>
d862f0eeb9eacdb46b9f5cc420de30a3d7c2c3f6vboxsync </listitem>
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync <para>Both VirtualBox client programs and frontends should
d862f0eeb9eacdb46b9f5cc420de30a3d7c2c3f6vboxsync periodically perform processing of the main event queue, and do that
d862f0eeb9eacdb46b9f5cc420de30a3d7c2c3f6vboxsync on the application's main thread. In case of a typical GUI Windows/Mac
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync OS application this happens automatically in the GUI's dispatch loop.
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync However, for CLI only application, the appropriate actions have to be
416817daa142e9bb7eaf14a1b10577978a5e691bvboxsync taken. For C++ applications, the VirtualBox SDK provided glue method
416817daa142e9bb7eaf14a1b10577978a5e691bvboxsync int EventQueue::processEventQueue(uint32_t cMsTimeout)
416817daa142e9bb7eaf14a1b10577978a5e691bvboxsync </screen> can be used for both blocking and non-blocking operations.
9161d9a8318db73b2848c1feaef3880980474e64vboxsync For the Python bindings, a common layer provides the method <screen>
9161d9a8318db73b2848c1feaef3880980474e64vboxsync <para>Things get somewhat more complicated for situations where an
9161d9a8318db73b2848c1feaef3880980474e64vboxsync application using VirtualBox cannot directly control the main event
416817daa142e9bb7eaf14a1b10577978a5e691bvboxsync loop and the main event queue is separated from the event queue of the
416817daa142e9bb7eaf14a1b10577978a5e691bvboxsync programming librarly (for example in case of Qt on Unix platforms). In
416817daa142e9bb7eaf14a1b10577978a5e691bvboxsync such a case, the application developer is advised to use a
416817daa142e9bb7eaf14a1b10577978a5e691bvboxsync platform/toolkit specific event injection mechanism to force event
416817daa142e9bb7eaf14a1b10577978a5e691bvboxsync queue checks either based on periodical timer events delivered to the
416817daa142e9bb7eaf14a1b10577978a5e691bvboxsync main thread, or by using custom platform messages to notify the main
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync thread when events are available. See the VBoxSDL and Qt (VirtualBox)
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync frontends as examples.</para>
9161d9a8318db73b2848c1feaef3880980474e64vboxsync <title>Visual Basic and Visual Basic Script (VBS) on Windows
9161d9a8318db73b2848c1feaef3880980474e64vboxsync hosts</title>
9161d9a8318db73b2848c1feaef3880980474e64vboxsync <para>On Windows hosts, one can control some of the VirtualBox Main
9161d9a8318db73b2848c1feaef3880980474e64vboxsync API functionality from VBS scripts, and pretty much everything from
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync Visual Basic programs.<footnote>
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync <para>The difference results from the way VBS treats COM
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync safearrays, which are used to keep lists in the Main API. VBS
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync expects every array element to be a
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync <computeroutput>VARIANT</computeroutput>, which is too strict a
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync limitation for any high performance API. We may lift this
9161d9a8318db73b2848c1feaef3880980474e64vboxsync restriction for interface APIs in a future version, or
9161d9a8318db73b2848c1feaef3880980474e64vboxsync alternatively provide conversion APIs.</para>
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync <para>VBS is scripting language available in any recent Windows
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync environment. As an example, the following VBS code will print
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync VirtualBox version: <screen>
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync set vb = CreateObject("VirtualBox.VirtualBox")
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync Wscript.Echo "VirtualBox version " & vb.version
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync </screen> See
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync <computeroutput>bindings/mscom/vbs/sample/vboxinfo.vbs</computeroutput>
c4bfe32373c55416bf49dc29ebf45dfa560b4692vboxsync for the complete sample.</para>
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync <para>Visual Basic is a popular high level language capable of
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync accessing COM objects. The following VB code will iterate over all
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync available virtual machines:<screen>
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync vb = CreateObject("VirtualBox.VirtualBox")
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync machines = ""
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync </screen> See
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync <computeroutput>bindings/mscom/vb/sample/vboxinfo.vb</computeroutput>
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync for the complete sample.</para>
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync <para>This section currently applies to Linux hosts only.</para>
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync <para>Starting with version 2.2, VirtualBox offers a C binding for the
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync XPCOM API.</para>
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync <para>The C binding provides a layer enabling object creation, method
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync invocation and attribute access from C.</para>
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync <para>The following sections describe how to use the C binding in a
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync C program.</para>
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync <para>For Linux, a sample program is provided which demonstrates use
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync of the C binding to initialize XPCOM, get handles for VirtualBox and
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync Session objects, make calls to list and start virtual machines, and
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync uninitialize resources when done. The program uses the VBoxGlue
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync library to open the C binding layer during runtime.</para>
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync <para>The sample program
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync <computeroutput>tstXPCOMCGlue</computeroutput> is located in the bin
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync directory and can be run without arguments. It lists registered
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync machines on the host along with some additional information and ask
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync for a machine to start. The source for this program is available in
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync <computeroutput>sdk/bindings/xpcom/cbinding/samples/</computeroutput>
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync directory. The source for the VBoxGlue library is available in the
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync <computeroutput>sdk/bindings/xpcom/cbinding/</computeroutput>
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync directory.</para>
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync <para>Just like in C++, XPCOM needs to be initialized before it can
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync be used. The <computeroutput>VBoxCAPI_v2_5.h</computeroutput> header
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync provides the interface to the C binding. Here's how to initialize
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync XPCOM:</para>
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsyncPCVBOXXPCOM g_pVBoxFuncs = NULL;
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsyncIVirtualBox *vbox = NULL;
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsyncISession *session = NULL;
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync * VBoxGetXPCOMCFunctions() is the only function exported by
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync * VBoxXPCOMC.so and the only one needed to make virtualbox
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync * work with C. This functions gives you the pointer to the
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync * function table (g_pVBoxFuncs).
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync * Once you get the function table, then how and which functions
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync * to use is explained below.
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync * g_pVBoxFuncs->pfnComInitialize does all the necessary startup
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync * action and provides us with pointers to vbox and session handles.
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync * It should be matched by a call to g_pVBoxFuncs->pfnComUninitialize()
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync * when done.
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsyncg_pVBoxFuncs = VBoxGetXPCOMCFunctions(VBOX_XPCOMC_VERSION);
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsyncg_pVBoxFuncs->pfnComInitialize(&vbox, &session);</screen>
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync <para>If either <computeroutput>vbox</computeroutput> or
c4bfe32373c55416bf49dc29ebf45dfa560b4692vboxsync <computeroutput>NULL</computeroutput>, initialization failed and the
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync XPCOM API cannot be used.</para>
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync <para>Method invocation is straightforward. It looks pretty much
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync like the C++ way, augmented with an extra indirection due to
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync accessing the vtable and passing a pointer to the object as the
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync first argument to serve as the <computeroutput>this</computeroutput>
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync pointer.</para>
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync <para>Using the C binding, all method invocations return a numeric
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync result code.</para>
c4bfe32373c55416bf49dc29ebf45dfa560b4692vboxsync <para>If an interface is specified as returning an object, a pointer
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync to a pointer to the appropriate object must be passed as the last
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync argument. The method will then store an object pointer in that
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync location.</para>
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync <para>In other words, to call an object's method what you need
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync <screen>IObject *object;
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsyncnsresult rc;
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync * Calling void IObject::method(arg, ...)
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsyncrc = object->vtbl->Method(object, arg, ...);
2dd7b4388106de88d20f33a8aa6c85c8babf507bvboxsync * Calling IFoo IObject::method(arg, ...)
2dd7b4388106de88d20f33a8aa6c85c8babf507bvboxsyncrc = object->vtbl->Method(object, args, ..., &foo);</screen>
2dd7b4388106de88d20f33a8aa6c85c8babf507bvboxsync <para>As a real-world example of a method invocation, let's call
2dd7b4388106de88d20f33a8aa6c85c8babf507bvboxsync xreflabel="IVirtualBox::openRemoteSession" /> which returns an
2dd7b4388106de88d20f33a8aa6c85c8babf507bvboxsync IProgress object. Note again that the method name is
3faac25bf74aedb359249d6acd6d8e4988acd332vboxsync capitalized.</para>
3faac25bf74aedb359249d6acd6d8e4988acd332vboxsync <screen>IProgress *progress;
3faac25bf74aedb359249d6acd6d8e4988acd332vboxsyncrc = vbox->vtbl->OpenRemoteSession(
2dd7b4388106de88d20f33a8aa6c85c8babf507bvboxsync vbox, /* this */
2dd7b4388106de88d20f33a8aa6c85c8babf507bvboxsync session, /* arg 1 */
3faac25bf74aedb359249d6acd6d8e4988acd332vboxsync id, /* arg 2 */
2dd7b4388106de88d20f33a8aa6c85c8babf507bvboxsync sessionType, /* arg 3 */
3faac25bf74aedb359249d6acd6d8e4988acd332vboxsync env, /* arg 4 */
3faac25bf74aedb359249d6acd6d8e4988acd332vboxsync &progress /* Out */
2dd7b4388106de88d20f33a8aa6c85c8babf507bvboxsync <para>A construct similar to calling non-void methods is used to
c4bfe32373c55416bf49dc29ebf45dfa560b4692vboxsync access object attributes. For each attribute there exists a getter
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync method, the name of which is composed of
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync <computeroutput>Get</computeroutput> followed by the capitalized
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync attribute name. Unless the attribute is read-only, an analogous
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync <computeroutput>Set</computeroutput> method exists. Let's apply
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync these rules to read the <xref linkend="IVirtualBox__revision"
416817daa142e9bb7eaf14a1b10577978a5e691bvboxsync xreflabel="IVirtualBox::revision" /> attribute.</para>
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync <para>Using the <computeroutput>IVirtualBox</computeroutput> handle
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync <computeroutput>vbox</computeroutput> obtained above, calling its
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync <computeroutput>GetRevision</computeroutput> method looks like
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync this:</para>
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync <screen>PRUint32 rev;
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsyncrc = vbox->vtbl->GetRevision(vbox, &rev);
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsyncif (NS_SUCCEEDED(rc))
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync printf("Revision: %u\n", (unsigned)rev);
416817daa142e9bb7eaf14a1b10577978a5e691bvboxsync <para>All objects with their methods and attributes are documented
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync <para>When dealing with strings you have to be aware of a string's
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync encoding and ownership.</para>
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync <para>Internally, XPCOM uses UTF-16 encoded strings. A set of
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync conversion functions is provided to convert other encodings to and
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync from UTF-16. The type of a UTF-16 character is
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync <computeroutput>PRUnichar</computeroutput>. Strings of UTF-16
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync characters are arrays of that type. Most string handling functions
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync take pointers to that type. Prototypes for the following conversion
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync functions are declared in
c4bfe32373c55416bf49dc29ebf45dfa560b4692vboxsync <computeroutput>VBoxCAPI_v2_5.h</computeroutput>.</para>
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync <title>Conversion of UTF-16 to and from UTF-8</title>
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync <screen>int (*pfnUtf16ToUtf8)(const PRUnichar *pwszString, char **ppszString);
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsyncint (*pfnUtf8ToUtf16)(const char *pszString, PRUnichar **ppwszString);
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync <para>The ownership of a string determines who is responsible for
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync releasing resources associated with the string. Whenever XPCOM
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync creates a string, ownership is transferred to the caller. To avoid
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync resource leaks, the caller should release resources once the
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync string is no longer needed.</para>
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync <para>Uninitialization is performed by
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync <computeroutput>g_pVBoxFuncs->pfnComUninitialize().</computeroutput>
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync If your program can exit from more than one place, it is a good idea
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync to install this function as an exit handler with Standard C's
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync <computeroutput>atexit()</computeroutput> just after calling
c4bfe32373c55416bf49dc29ebf45dfa560b4692vboxsync <computeroutput>g_pVBoxFuncs->pfnComInitialize()</computeroutput>
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync#include <stdio.h>
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync * Make sure g_pVBoxFuncs->pfnComUninitialize() is called at exit, no
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync * matter if we return from the initial call to main or call exit()
c4bfe32373c55416bf49dc29ebf45dfa560b4692vboxsync * somewhere else. Note that atexit registered functions are not
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync * called upon abnormal termination, i.e. when calling abort() or
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync * signal(). Separate provisions must be taken for these cases.
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsyncif (atexit(g_pVBoxFuncs->pfnComUninitialize()) != 0) {
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync fprintf(stderr, "failed to register g_pVBoxFuncs->pfnComUninitialize()\n");
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync exit(EXIT_FAILURE);
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync <para>Another idea would be to write your own <computeroutput>void
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync myexit(int status)</computeroutput> function, calling
c4bfe32373c55416bf49dc29ebf45dfa560b4692vboxsync <computeroutput>g_pVBoxFuncs->pfnComUninitialize()</computeroutput>
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync followed by the real <computeroutput>exit()</computeroutput>, and
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync use it instead of <computeroutput>exit()</computeroutput> throughout
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync your program and at the end of
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync <para>If you expect the program to be terminated by a signal (e.g.
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync user types CTRL-C sending SIGINT) you might want to install a signal
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync handler setting a flag noting that a signal was sent and then
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync <computeroutput>g_pVBoxFuncs->pfnComUninitialize()</computeroutput>
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync later on (usually <emphasis>not</emphasis> from the handler itself
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync <para>That said, if a client program forgets to call
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync <computeroutput>g_pVBoxFuncs->pfnComUninitialize()</computeroutput>
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync before it terminates, there is a mechanism in place which will
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync eventually release references held by the client. You should not
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync rely on this, however.</para>
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync <para>A program using the C binding has to open the library during
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync runtime using the help of glue code provided and as shown in the
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync example <computeroutput>tstXPCOMCGlue.c</computeroutput>.
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync Compilation and linking can be achieved, e.g., with a makefile
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync fragment similar to</para>
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync <screen># Where is the XPCOM include directory?
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsyncINCS_XPCOM = /include
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync# Where is the glue code directory?
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsyncGLUE_DIR = ..
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsyncGLUE_INC = -I..
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync#Compile Glue Library
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync $(CC) $(CFLAGS) $(INCS_XPCOM) $(GLUE_INC) -o $@ -c $<
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync $(CC) $(CFLAGS) $(INCS_XPCOM) $(GLUE_INC) -o $@ -c $<
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync $(CC) -o $@ $^ -ldl</screen>
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync <title>Basic VirtualBox concepts; some examples</title>
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync <para>The following explains some basic VirtualBox concepts such as the
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync VirtualBox object, sessions and how virtual machines are manipulated and
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync launched using the Main API. The coding examples use a pseudo-code style
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync closely related to the object-oriented web service (OOWS) for JAX-WS.
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync Depending on which environment you are using, you will need to adjust the
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync examples.</para>
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync <title>Obtaining basic machine information. Reading attributes</title>
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync <para>Any program using the Main API will first need access to the
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync global VirtualBox object (see <xref linkend="IVirtualBox"
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync xreflabel="IVirtualBox" />), from which all other functionality of the
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync API is derived. With the OOWS for JAX-WS, this is returned from the
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync <xref linkend="???" xreflabel="IWebsessionManager::logon()" />
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync call.</para>
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync <para>To enumerate virtual machines, one would look at the "machines"
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync array attribute in the VirtualBox object (see <xref
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync linkend="IVirtualBox__machines" xreflabel="IVirtualBox::machines" />).
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync This array contains all virtual machines currently registered with the
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync host, each of them being an instance of <xref linkend="IMachine"
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync xreflabel="IMachine" />. From each such instance, one can query
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync additional information, such as the UUID, the name, memory, operating
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync system and more by looking at the attributes; see the attributes list in
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync <xref linkend="IMachine" xreflabel="IMachine documentation" />.</para>
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync <para>As mentioned in the preceding chapters, depending on your
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync programming environment, attributes are mapped to corresponding "get"
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync and (if the attribute is not read-only) "set" methods. So when the
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync documentation says that IMachine has a "<xref linkend="IMachine__name"
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync xreflabel="name" />" attribute, this means you need to code something
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync like the following to get the machine's name:<screen>IMachine machine = ...;
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsyncString name = machine.getName();</screen>Boolean attribute getters can
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync sometimes be called <computeroutput>isAttribute()</computeroutput> due
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync to JAX-WS naming conventions.</para>
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync <para>As said in the previous section, to read a machine's attribute,
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync one invokes the corresponding "get" method. One would think that to
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync change settings of a machine, it would suffice to call the corresponding
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync "set" method -- for example, to set a VM's memory to 1024 MB, one would
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync call <computeroutput>setMemorySize(1024)</computeroutput>. Try that, and
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync you will get an error: "The machine is not mutable."</para>
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync <para>So unfortunately, things are not that easy. VirtualBox is a
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync complicated environment in which multiple processes compete for possibly
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync the same resources, especially machine settings. As a result, machines
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync must be "locked" before they can either be modified or started. This is
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync to prevent multiple processes from making conflicting changes to a
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync machine: it should, for example, not be allowed to change the memory
730f8be51b729e8a3c1e32c756cd0f4ec088dd4dvboxsync size of a virtual machine while it is running. (You can't add more
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync memory to a real computer while it is running either, at least not to an
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync ordinary PC.) Also, two processes must not change settings at the same
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync time, or start a machine at the same time.</para>
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync <para>These requirements are implemented in the Main API by way of
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync "sessions", in particular, the <xref linkend="ISession"
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync xreflabel="ISession" /> interface. Each process which talks to
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync VirtualBox needs its own instance of ISession. In the web service, you
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync cannot create such an object, but
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync <computeroutput>vboxwebsrv</computeroutput> creates one for you when you
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync log on, which you can obtain by calling <xref
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync linkend="IWebsessionManager__getSessionObject"
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync xreflabel="IWebsessionManager::getSessionObject()" />.</para>
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync <para>This session object must then be used like a mutex semaphore in
610972deee47d5e5229ccdb6c86cbb332d2b4626vboxsync common programming environments. Before you can change machine settings,
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync you must write-lock the machine by calling <xref
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync linkend="IMachine__lockMachine" xreflabel="IMachine::lockMachine()" />
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync with your process's session object.</para>
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync linkend="ISession__machine" xreflabel="ISession::machine" /> attribute
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync contains a copy of the original IMachine object upon which the session
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync was opened, but this copy is "mutable": you can invoke "set" methods on
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync <para>When done making the changes to the machine, you must call <xref
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync linkend="IMachine__saveSettings"
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync xreflabel="IMachine::saveSettings()" />, which will copy the changes you
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync have made from your "mutable" machine back to the real machine and write
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync them out to the machine settings XML file. This will make your changes
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync permanent.</para>
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync <para>Finally, it is important to always unlock the machine again, by
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync xreflabel="ISession::unlockMachine()" />. Otherwise, when the calling
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync process end, the machine will receive the "aborted" state, which can
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync lead to loss of data.</para>
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync <para>So, as an example, the sequence to change a machine's memory to
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsync 1024 MB is something like this:<screen>IWebsessionManager mgr ...;
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsyncIVirtualBox vbox = mgr.logon(user, pass);
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsyncIMachine machine = ...; // read-only machine
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsyncISession session = mgr.getSessionObject();
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsyncmachine.lockMachine(session, LockType.Write); // machine is now locked for writing
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsyncIMachine mutable = session.getMachine(); // obtain the mutable machine copy
5a07658d13590eba51dd98ef335a73d2a11edaa7vboxsyncmutable.saveSettings(); // write settings to XML
IVirtualBox vbox = mgr.logon(user, pass);
ISession session = mgr.getSessionObject();
IProgress prog = machine.launchVMProcess(session,
prog.waitForCompletion(10000); // give the process 10 secs
if (prog.getResultCode() != 0) // check success
IEventListener listener = es.createListener();
VBoxEventType aTypes[] = (VBoxEventType.OnMachineStateChanged);
es.registerListener(listener, aTypes, false /* active */);
IEvent ev = es.getEvent(listener, 1000);
IMachineStateChangedEvent mcse = IMachineStateChangedEvent.queryInterface(ev);
es.eventProcessed(listener, ev);
if not hdd.id:
print "created HDD with id: %s" %(hdd.id)
data.result = VINF_SUCCESS;
data.Loc.type = VMMDevHGCMLoc_LocalHost_Existing;
strcpy (data.Loc.u.host.achName, "VBoxSharedFolders");
rc = data.result;
ulClientID = data.u32ClientID;
data.result = VINF_SUCCESS;
data.u32ClientID = ulClientID;
data.callInfo.result = VINF_SUCCESS; /* Will be returned by HGCM. */
data.callInfo.u32ClientID = ulClientID; /* Client identifier. */
data.callInfo.u32Function = SHFL_FN_READ; /* The function code. */
data.callInfo.cParms = SHFL_CPARMS_READ; /* Number of parameters. */
data.root.type = VMMDevHGCMParmType_32bit;
data.root.u.value32 = pMap->root;
data.handle.type = VMMDevHGCMParmType_64bit;
data.handle.u.value64 = hFile;
data.offset.type = VMMDevHGCMParmType_64bit;
data.offset.u.value64 = offset;
data.cb.type = VMMDevHGCMParmType_32bit;
data.cb.u.value32 = *pcbBuffer;
data.buffer.type = VMMDevHGCMParmType_LinAddr_Out;
data.buffer.u.Pointer.size = *pcbBuffer;
data.buffer.u.Pointer.u.linearAddr = (uintptr_t)pBuffer;
rc = VbglHGCMCall (handle, &data.callInfo, sizeof (data));
rc = data.callInfo.result;
*pcbBuffer = data.cb.u.value32; /* This is returned by the HGCM service. */
RDPWebClient.isRDPWebControlById(ElementId)
RDPWebClient.getFlashById(ElementId)
the VirtualBox API provides versioning in the Java package name, e.g.
url="http://sourceforge.net/projects/jacob-project/">http://sourceforge.net/projects/jacob-project/</ulink>
java -cp vboxjws.jar MyProgram
import org.virtualbox_3_3.*;
VirtualBoxManager mgr = VirtualBoxManager.createInstance(null);
String url = "http://myhost:18034";
mgr.connect(url, user, passwd);
IVirtualBox vbox = mgr.getVBox();
String m = vbox.getMachines().get(0).getName();
System.out.println("\nAttempting to start VM '" + m + "'");
mgr.startVm(m, null, 7000);
mgr.cleanup();
version components of VirtualBox change (that is, in the x.y.z scheme, a
code (e.g. changes in method parameter lists, renamed or removed
medium change notification) and removing associated enums (e.g.
available back-ends for hard disk images (e.g. VDI, VMDK, VHD or