VirtualBox

Changeset 56532 in vbox


Ignore:
Timestamp:
Jun 18, 2015 5:44:54 PM (9 years ago)
Author:
vboxsync
Message:

doc/manual: fix SDK reference to be valid docbook XML, needed adjustments in the generator (which produced creative stuff which was severely violating the DTD, e.g. custom attributes which could be easily done properly) and a LOT of manual editing. Content of the manual is essentially the same, the biggest issues were <para> sloppiness and the use of <xref> where <link> is the only solution. Also made the line lengths again as uniform as possible.

Location:
trunk/doc/manual
Files:
3 edited

Legend:

Unmodified
Added
Removed

  • trunk/doc/manual/docbook2latex.xsl

    r56483 r56532  
    621621  <xsl:template match="xref">
    622622    <xsl:choose>
    623       <xsl:when test="@xreflabel">
    624         <xsl:value-of select="concat('\hyperref[', @linkend, ']{\mbox{', @xreflabel, '}}')" />
    625       </xsl:when>
    626       <xsl:when test="@apiref='yes'">
     623      <xsl:when test="@endterm">
     624        <xsl:value-of select="concat('\hyperref[', @linkend, ']{\mbox{', @endterm, '}}')" />
     625      </xsl:when>
     626      <xsl:otherwise>
     627        <xsl:value-of select="concat($g_nlsChapter, ' \ref{', @linkend, '}, \textit{\nameref{', @linkend, '}}, ', $g_nlsPage, ' \pageref{', @linkend, '}')" />
     628      </xsl:otherwise>
     629    </xsl:choose>
     630  </xsl:template>
     631
     632  <xsl:template match="link">
     633    <xsl:choose>
     634      <xsl:when test="@endterm">
     635        <xsl:value-of select="concat('\hyperref[', @linkend, ']{\mbox{', @endterm, '}}')" />
     636      </xsl:when>
     637      <xsl:when test="./text()">
    627638        <xsl:value-of select="concat('\hyperref[', @linkend, ']{\mbox{')" />
    628         <xsl:apply-templates />
     639        <xsl:apply-templates select="./text()"/>
    629640        <xsl:value-of select="'}}'" />
    630641      </xsl:when>

  • trunk/doc/manual/en_US/SDKRef.xml

    r56250 r56532  
    3838        <imageobject>
    3939          <imagedata align="center" fileref="images/vbox-components.png"
    40                      width="12cm" />
     40                     width="12cm"/>
    4141        </imageobject>
    4242      </mediaobject>
    … …  
    6262      exposes the entire feature set of the virtualization engine below. It is
    6363      completely documented in this SDK Reference -- see <xref
    64       linkend="sdkref_classes" /> and <xref linkend="sdkref_enums" /> -- and
     64      linkend="sdkref_classes"/> and <xref linkend="sdkref_enums"/> -- and
    6565      available to anyone who wishes to control VirtualBox programmatically.
    6666      We chose the name "Main API" to differentiate it from other programming
    … …  
    114114
    115115                  <para>The OO bindings for Java are described in <xref
    116                   linkend="javaapi" />, those for Python in <xref lang=""
    117                   linkend="glue-python-ws" />.</para>
     116                  linkend="javaapi"/>, those for Python in <xref
     117                  linkend="glue-python-ws"/>.</para>
    118118                </listitem>
    119119
    … …  
    133133
    134134                  <para>We describe this further in <xref
    135                   linkend="raw-webservice" />, with samples for Java and
     135                  linkend="raw-webservice"/>, with samples for Java and
    136136                  Perl.</para>
    137137                </listitem>
    … …  
    155155            necessary files and documentation to build fully functional COM
    156156            applications. For an introduction, please see <xref
    157             linkend="api_com" /> below.</para>
     157            linkend="api_com"/> below.</para>
    158158
    159159            <para>The VirtualBox front-ends (the graphical user interfaces as
    … …  
    346346          <listitem>
    347347            <para><computeroutput>--ssl</computeroutput> (or
    348             <computeroutput>-s</computeroutput>): This enables SSL support.</para>
     348            <computeroutput>-s</computeroutput>): This enables SSL
     349            support.</para>
    349350          </listitem>
    350351
    … …  
    434435            <computeroutput>-k</computeroutput>): This specifies the maximum
    435436            number of requests which can be sent in one web service connection,
    436             and defaults to 100. This normally does not need to be changed.</para>
     437            and defaults to 100. This normally does not need to be
     438            changed.</para>
    437439          </listitem>
    438440
    … …  
    503505        <para>As opposed to the COM/XPCOM variant of the Main API, a client
    504506        that wants to use the web service must first log on by calling the
    505         <computeroutput>IWebsessionManager::logon()</computeroutput> API (see
    506         <xref linkend="IWebsessionManager__logon" />) that is specific to the
     507        <link linkend="IWebsessionManager__logon">IWebsessionManager::logon()</link>
     508        API that is specific to the
    507509        web service. Logon is necessary for the web service to be stateful;
    508510        internally, it maintains a session for each client that connects to
    … …  
    515517
    516518        <para>For testing purposes, it is recommended that you first disable
    517         authentication with this command:<screen>VBoxManage setproperty websrvauthlibrary null</screen></para>
     519        authentication with this command:
     520        <screen>VBoxManage setproperty websrvauthlibrary null</screen></para>
    518521
    519522        <para><warning>
    … …  
    533536        Manual; the web service uses the same kind of modules as the
    534537        VirtualBox VRDE server. For technical details on VirtualBox external
    535         authentication modules see <xref linkend="vbox-auth" /></para>
     538        authentication modules see <xref linkend="vbox-auth"/></para>
    536539
    537540        <para>By default, after installation, the web service uses the
    … …  
    557560    <title>Environment-specific notes</title>
    558561
    559     <para>The Main API described in <xref linkend="sdkref_classes" /> and
    560     <xref linkend="sdkref_enums" /> is mostly identical in all the supported
     562    <para>The Main API described in <xref linkend="sdkref_classes"/> and
     563    <xref linkend="sdkref_enums"/> is mostly identical in all the supported
    561564    programming environments which have been briefly mentioned in the
    562565    introduction of this book. As a result, the Main API's general concepts
    563     described in <xref linkend="concepts" /> are the same whether you use the
     566    described in <xref linkend="concepts"/> are the same whether you use the
    564567    object-oriented web service (OOWS) for JAX-WS or a raw web service
    565568    connection via, say, Perl, or whether you use C++ COM bindings.</para>
    … …  
    571574      <title>Using the object-oriented web service (OOWS)</title>
    572575
    573       <para>As explained in <xref linkend="webservice-or-com" />, VirtualBox
     576      <para>As explained in <xref linkend="webservice-or-com"/>, VirtualBox
    574577      ships with client-side libraries for Java, Python and PHP that allow you
    575578      to use the VirtualBox web service in an intuitive, object-oriented way.
    … …  
    577580      object references and other implementation details that come with the
    578581      VirtualBox web service. (If you are interested in these complications,
    579       have a look at <xref linkend="raw-webservice" />).</para>
     582      have a look at <xref linkend="raw-webservice"/>).</para>
    580583
    581584      <para>We recommend that you start your experiments with the VirtualBox
    … …  
    585588
    586589      <para>As "interfaces", "attributes" and "methods" are COM concepts,
    587       please read the documentation in <xref linkend="sdkref_classes" /> and
    588       <xref linkend="sdkref_enums" /> with the following notes in mind.</para>
     590      please read the documentation in <xref linkend="sdkref_classes"/> and
     591      <xref linkend="sdkref_enums"/> with the following notes in mind.</para>
    589592
    590593      <para>The OOWS bindings attempt to map the Main API as closely as
    … …  
    597600      capitalized first letter. So when the Main API Reference says that
    598601      <computeroutput>IMachine</computeroutput> has a "name" attribute (see
    599       <xref linkend="IMachine__name" xreflabel="IMachine::name" />), call
     602      <link linkend="IMachine__name">IMachine::name</link>), call
    600603      <computeroutput>getName()</computeroutput> on an IMachine object to
    601604      obtain a machine's name. Unless the attribute is marked as read-only in
    … …  
    650653                <para>To start the VirtualBox web service, open a second
    651654                terminal and change to the directory where the VirtualBox
    652                 executables are located. Then type:<screen>./vboxwebsrv -v</screen></para>
     655                executables are located. Then type:
     656                <screen>./vboxwebsrv -v</screen></para>
    653657
    654658                <para>The web service now waits for connections and will run
    655659                until you press Ctrl+C in this second terminal. The -v
    656660                argument causes it to log all connections to the terminal.
    657                 (See <xref linkend="runvboxwebsrv" os="" /> for details on how
     661                (See <xref linkend="runvboxwebsrv"/> for details on how
    658662                to run the web service.)</para>
    659663              </listitem>
    … …  
    661665              <listitem>
    662666                <para>Back in the first terminal and still in the samples
    663                 directory, to start a simple client example just type:<screen>make run16</screen></para>
     667                directory, to start a simple client example just type:
     668                <screen>make run16</screen></para>
    664669
    665670                <para>if you're on a Java 6 system; on a Java 5 system, run
    … …  
    715720          <computeroutput>clienttest</computeroutput> constructor:<orderedlist>
    716721              <listitem>
    717                 <para>An instance of <xref linkend="IWebsessionManager"
    718                 xreflabel="IWebsessionManager" />, which is an interface
    719                 provided by the web service to manage "web sessions" -- that
    720                 is, stateful connections to the web service with persistent
    721                 objects upon which methods can be invoked.</para>
     722                <para>An instance of
     723                <link linkend="IWebsessionManager">IWebsessionManager</link>,
     724                which is an interface provided by the web service to manage
     725                "web sessions" -- that is, stateful connections to the web
     726                service with persistent objects upon which methods can be
     727                invoked.</para>
    722728
    723729                <para>In the OOWS for JAX-WS, the IWebsessionManager class
    … …  
    731737                number given to the
    732738                <computeroutput>vboxwebsrv</computeroutput> command line; see
    733                 <xref linkend="vboxwebsrv-ref" />.</para>
    734               </listitem>
    735 
    736               <listitem>
    737                 <para>After that, the code calls <xref
    738                 linkend="IWebsessionManager__logon"
    739                 xreflabel="IWebsessionManager::logon()" />, which is the first
    740                 call that actually communicates with the server. This
    741                 authenticates the client with the web service and returns an
    742                 instance of <xref linkend="IVirtualBox"
    743                 xreflabel="IVirtualBox" />, the most fundamental interface of
    744                 the VirtualBox web service, from which all other functionality
    745                 can be derived.</para>
     739                <xref linkend="vboxwebsrv-ref"/>.</para>
     740              </listitem>
     741
     742              <listitem>
     743                <para>After that, the code calls
     744                <link linkend="IWebsessionManager__logon">IWebsessionManager::logon()</link>,
     745                which is the first call that actually communicates with the
     746                server. This authenticates the client with the web service and
     747                returns an instance of
     748                <link linkend="IVirtualBox">IVirtualBox</link>,
     749                the most fundamental interface of the VirtualBox web service,
     750                from which all other functionality can be derived.</para>
    746751
    747752                <para>If logon doesn't work, please take another look at <xref
    748                 linkend="websrv_authenticate" />.</para>
     753                linkend="websrv_authenticate"/>.</para>
    749754              </listitem>
    750755            </orderedlist></para>
    … …  
    756761          <para>The current OOWS for JAX-WS has certain memory management
    757762          related limitations. When you no longer need an object, call its
    758           <xref linkend="IManagedObjectRef__release"
    759           xreflabel="IManagedObjectRef::release()" /> method explicitly, which
     763          <link linkend="IManagedObjectRef__release">IManagedObjectRef::release()</link>
     764          method explicitly, which
    760765          frees appropriate managed reference, as is required by the raw
    761           web service; see <xref linkend="managed-object-references" /> for
     766          web service; see <xref linkend="managed-object-references"/> for
    762767          details. This limitation may be reconsidered in a future version of
    763768          the VirtualBox SDK.</para>
    … …  
    770775        <para>VirtualBox comes with two flavors of a Python API: one for web
    771776        service, discussed here, and one for the COM/XPCOM API discussed in
    772         <xref linkend="pycom" />. The client code is mostly similar, except
     777        <xref linkend="pycom"/>. The client code is mostly similar, except
    773778        for the initialization part, so it is up to the application developer
    774779        to choose the appropriate technology. Moreover, a common Python glue
    775780        layer exists, abstracting out concrete platform access details, see
    776         <xref linkend="glue-python" />.</para>
    777 
    778         <para>As indicated in <xref linkend="webservice-or-com" />, the
     781        <xref linkend="glue-python"/>.</para>
     782
     783        <para>As indicated in <xref linkend="webservice-or-com"/>, the
    779784        COM/XPCOM API gives better performance without the SOAP overhead, and
    780785        does not require a web server to be running. On the other hand, the
    … …  
    785790            are officially supported. This means Python 2.3 for 10.4, Python
    786791            2.5 for 10.5 and Python 2.5 and 2.6 for 10.6.</para>
    787           </footnote>). On Windows, you can use the Main API from Python if the Win32 extensions
    788           package for Python<footnote>
     792          </footnote>). On Windows, you can use the Main API from Python if the
     793          Win32 extensions package for Python<footnote>
    789794            <para>See <ulink
    790795            url="http://sourceforge.net/project/showfiles.php?group_id=78018">http://sourceforge.net/project/showfiles.php?group_id=78018</ulink>.</para>
    791           </footnote> is installed. Version of Python Win32 extensions earlier than 2.16 are known to have bugs,
    792           leading to issues with VirtualBox Python bindings, and also some early builds of Python 2.5 for Windows have issues with
    793           reporting platform name on some Windows versions, so please make sure to use latest available Python
    794           and Win32 extensions.</para>
     796          </footnote> is installed. Version of Python Win32 extensions earlier
     797          than 2.16 are known to have bugs, leading to issues with VirtualBox
     798          Python bindings, and also some early builds of Python 2.5 for Windows
     799          have issues with reporting platform name on some Windows versions, so
     800          please make sure to use latest available Python and Win32
     801          extensions.</para>
    795802
    796803        <para>The VirtualBox OOWS for Python relies on the Python ZSI SOAP
    … …  
    813820        and web services).</para>
    814821
    815         <para>To start the shell, perform the following commands: <screen>/opt/VirtualBox/vboxwebsrv -t 0
     822        <para>To start the shell, perform the following commands:
     823        <screen>/opt/VirtualBox/vboxwebsrv -t 0
    816824            # start web service with object autocollection disabled
    817825export VBOX_PROGRAM_PATH=/opt/VirtualBox
    … …  
    819827export VBOX_SDK_PATH=/home/youruser/vbox-sdk
    820828            # where you've extracted the SDK
    821 ./vboxshell.py -w        </screen>See <xref linkend="vboxshell" /> for more
     829./vboxshell.py -w        </screen>
     830        See <xref linkend="vboxshell"/> for more
    822831        details on the shell's functionality. For you, as a VirtualBox
    823832        application developer, the vboxshell sample could be interesting as an
    … …  
    851860
    852861      <para>Generally, when reading the documentation in <xref
    853       linkend="sdkref_classes" /> and <xref linkend="sdkref_enums" />, due to
     862      linkend="sdkref_classes"/> and <xref linkend="sdkref_enums"/>, due to
    854863      the limitations of SOAP and WSDL lined out in <xref
    855       linkend="rawws-conventions" />, please have the following notes in
     864      linkend="rawws-conventions"/>, please have the following notes in
    856865      mind:</para>
    857866
    … …  
    864873            the <computeroutput>IVirtualBox</computeroutput> interface
    865874            supports the <computeroutput>createMachine()</computeroutput>
    866             method (see <xref linkend="IVirtualBox__createMachine"
    867             xreflabel="IVirtualBox::createMachine()" />), the web service
    868             operation is
     875            method (see
     876            <link linkend="IVirtualBox__createMachine">IVirtualBox::createMachine()</link>),
     877            the web service operation is
    869878            <computeroutput>IVirtualBox_createMachine(...)</computeroutput>,
    870879            and a managed object reference to an
    … …  
    924933            <listitem>
    925934              <para>Open a terminal in your working directory. Execute the
    926               following command:<screen> java org.apache.axis.wsdl.WSDL2Java /path/to/vboxwebService.wsdl</screen></para>
     935              following command:
     936              <screen>java org.apache.axis.wsdl.WSDL2Java /path/to/vboxwebService.wsdl</screen></para>
    927937
    928938              <para>The <computeroutput>vboxwebService.wsdl</computeroutput>
    … …  
    933943              <para>If this fails, your Apache Axis may not be located on your
    934944              system classpath, and you may have to adjust the CLASSPATH
    935               environment variable. Something like this:<screen>export CLASSPATH="/path-to-axis-1_4/lib/*":$CLASSPATH</screen></para>
     945              environment variable. Something like this:
     946              <screen>export CLASSPATH="/path-to-axis-1_4/lib/*":$CLASSPATH</screen></para>
    936947
    937948              <para>Use the directory where the Axis JAR files are located.
    … …  
    956967            <listitem>
    957968              <para>Next, compile the
    958               <computeroutput>clienttest.java</computeroutput> source:<screen>javac clienttest.java </screen></para>
     969              <computeroutput>clienttest.java</computeroutput>
     970              source:<screen>javac clienttest.java </screen></para>
    959971
    960972              <para>This should yield a "clienttest.class" file.</para>
    … …  
    964976              <para>To start the VirtualBox web service, open a second
    965977              terminal and change to the directory where the VirtualBox
    966               executables are located. Then type:<screen>./vboxwebsrv -v</screen></para>
     978              executables are located. Then type:
     979              <screen>./vboxwebsrv -v</screen></para>
    967980
    968981              <para>The web service now waits for connections and will run
    969982              until you press Ctrl+C in this second terminal. The -v argument
    970983              causes it to log all connections to the terminal. (See <xref
    971               linkend="runvboxwebsrv" os="" /> for details on how to run the
     984              linkend="runvboxwebsrv"/> for details on how to run the
    972985              web service.)</para>
    973986            </listitem>
    … …  
    10211034              <para>To start the VirtualBox web service, open a second
    10221035              terminal and change to the directory where the VirtualBox
    1023               executables are located. Then type:<screen>./vboxwebsrv -v</screen></para>
     1036              executables are located. Then type:
     1037              <screen>./vboxwebsrv -v</screen></para>
    10241038
    10251039              <para>The web service now waits for connections and will run
    10261040              until you press Ctrl+C in this second terminal. The -v argument
    10271041              causes it to log all connections to the terminal. (See <xref
    1028               linkend="runvboxwebsrv" os="" /> for details on how to run the
     1042              linkend="runvboxwebsrv"/> for details on how to run the
    10291043              web service.)</para>
    10301044            </listitem>
    … …  
    10321046            <listitem>
    10331047              <para>In the first terminal with the Perl sample, run the
    1034               clienttest.pl script:<screen>perl -I ../lib clienttest.pl</screen></para>
     1048              clienttest.pl script:
     1049              <screen>perl -I ../lib clienttest.pl</screen></para>
    10351050            </listitem>
    10361051          </orderedlist></para>
    … …  
    10431058        things in mind, or you will sooner or later run into issues that are
    10441059        not immediately obvious. By contrast, the object-oriented client-side
    1045         libraries described in <xref linkend="glue" /> take care of these
     1060        libraries described in <xref linkend="glue"/> take care of these
    10461061        things automatically and thus greatly simplify using the web
    10471062        service.</para>
    … …  
    10891104                method is invoked. (Managed object references are explained in
    10901105                detail below; see <xref
    1091                 linkend="managed-object-references" />.)</para>
     1106                linkend="managed-object-references"/>.)</para>
    10921107
    10931108                <para>So, when one would normally code, in the pseudo-code of
    … …  
    11041119                <para>To make the web service stateful, and objects persistent
    11051120                between method calls, the VirtualBox web service introduces a
    1106                 <emphasis role="bold">session manager</emphasis> (by way of
    1107                 the <xref linkend="IWebsessionManager"
    1108                 xreflabel="IWebsessionManager" /> interface), which manages
    1109                 object references. Any client wishing to interact with the web
    1110                 service must first log on to the session manager and in turn
    1111                 receives a managed object reference to an object that supports
    1112                 the <xref linkend="IVirtualBox" xreflabel="IVirtualBox" />
     1121                <emphasis role="bold">session manager</emphasis> (by way of the
     1122                 <link linkend="IWebsessionManager">IWebsessionManager</link>
     1123                interface), which manages object references. Any client wishing
     1124                to interact with the web service must first log on to the
     1125                session manager and in turn receives a managed object reference
     1126                to an object that supports the
     1127                <link linkend="IVirtualBox">IVirtualBox</link>
    11131128                interface (the basic interface in the Main API).</para>
    11141129              </listitem>
    … …  
    11271142          Main API version number) looks like this:<orderedlist>
    11281143              <listitem>
    1129                 <para>A client logs on to the web service by calling <xref
    1130                 linkend="IWebsessionManager__logon"
    1131                 xreflabel="IWebsessionManager::logon()" /> with a valid user
    1132                 name and password. See <xref linkend="websrv_authenticate" />
     1144                <para>A client logs on to the web service by calling
     1145                <link linkend="IWebsessionManager__logon">IWebsessionManager::logon()</link>
     1146                with a valid user name and password. See
     1147                <xref linkend="websrv_authenticate"/>
    11331148                for details about how authentication works.</para>
    11341149              </listitem>
    … …  
    11371152                <para>On the server side,
    11381153                <computeroutput>vboxwebsrv</computeroutput> creates a session,
    1139                 which persists until the client calls <xref
    1140                 linkend="IWebsessionManager__logoff"
    1141                 xreflabel="IWebsessionManager::logoff()" /> or the session
    1142                 times out after a configurable period of inactivity (see <xref
    1143                 linkend="vboxwebsrv-ref" />).</para>
     1154                which persists until the client calls
     1155                <link linkend="IWebsessionManager__logoff">IWebsessionManager::logoff()</link>
     1156                or the session times out after a configurable period of
     1157                inactivity (see <xref linkend="vboxwebsrv-ref"/>).</para>
    11441158
    11451159                <para>For the new session, the web service creates an instance
    1146                 of <xref linkend="IVirtualBox" xreflabel="IVirtualBox" />.
     1160                of <link linkend="IVirtualBox">IVirtualBox</link>.
    11471161                This interface is the most central one in the Main API and
    11481162                allows access to all other interfaces, either through
    … …  
    11631177                string consisting of digits and dashes. However, it is a
    11641178                string with a meaning and will be checked by the web service.
    1165                 For details, see below. As hinted above, <xref
    1166                 linkend="IWebsessionManager__logon"
    1167                 xreflabel="IWebsessionManager::logon()" /> is the
    1168                 <emphasis>only</emphasis> operation provided by the web
     1179                For details, see below. As hinted above,
     1180                <link linkend="IWebsessionManager__logon">IWebsessionManager::logon()</link>
     1181                is the <emphasis>only</emphasis> operation provided by the web
    11691182                service which does not take a managed object reference as the
    11701183                first argument!)</para>
    … …  
    11741187                <para>The VirtualBox Main API documentation says that the
    11751188                <computeroutput>IVirtualBox</computeroutput> interface has a
    1176                 <xref linkend="IVirtualBox__version" xreflabel="version" />
     1189                <link linkend="IVirtualBox__version">version</link>
    11771190                attribute, which is a string. For each attribute, there is a
    11781191                "get" and a "set" method in COM, which maps to according
    11791192                operations in the web service. So, to retrieve the "version"
    11801193                attribute of this <computeroutput>IVirtualBox</computeroutput>
    1181                 object, the web service client does this:<screen>string version;
     1194                object, the web service client does this:
     1195                <screen>string version;
    11821196version = webservice.IVirtualBox_getVersion(oVirtualBox);
    11831197
    … …  
    11891203
    11901204              <listitem>
    1191                 <para>The web service client calls <xref
    1192                 linkend="IWebsessionManager__logoff"
    1193                 xreflabel="IWebsessionManager::logoff()" /> with the
    1194                 VirtualBox managed object reference. This will clean up all
    1195                 allocated resources.</para>
     1205                <para>The web service client calls
     1206                <link linkend="IWebsessionManager__logoff">IWebsessionManager::logoff()</link>
     1207                with the VirtualBox managed object reference. This will clean
     1208                up all allocated resources.</para>
    11961209              </listitem>
    11971210            </orderedlist></para>
    … …  
    12121225          situations:<orderedlist>
    12131226              <listitem>
    1214                 <para>When a client logs on, by calling <xref
    1215                 linkend="IWebsessionManager__logon"
    1216                 xreflabel="IWebsessionManager::logon()" />.</para>
     1227                <para>When a client logs on, by calling
     1228                <link linkend="IWebsessionManager__logon">IWebsessionManager::logon()</link>.</para>
    12171229
    12181230                <para>Upon logon, the websession manager creates one instance
    1219                 of <xref linkend="IVirtualBox" xreflabel="IVirtualBox" />,
     1231                of <link linkend="IVirtualBox">IVirtualBox</link>,
    12201232                which can be used for directly performing calls to its
    12211233                methods, or used as a parameter for calling some methods of
    1222                 <xref linkend="IWebsessionManager" xreflabel="IWebsessionManager" />.
    1223                 Creating Main API session objects is performed using <xref
    1224                 linkend="IWebsessionManager__getSessionObject"
    1225                 xreflabel="IWebsessionManager::getSessionObject()" />.</para>
    1226 
    1227                 <para>(Technically, there is always only one <xref
    1228                 linkend="IVirtualBox" xreflabel="IVirtualBox" /> object, which
     1234                <link linkend="IWebsessionManager">IWebsessionManager</link>.
     1235                Creating Main API session objects is performed using
     1236                <link linkend="IWebsessionManager__getSessionObject">IWebsessionManager::getSessionObject()</link>.</para>
     1237
     1238                <para>(Technically, there is always only one
     1239                <link linkend="IVirtualBox">IVirtualBox</link> object, which
    12291240                is shared between all websessions and clients, as it is a COM
    12301241                singleton. However, each session receives its own managed
    … …  
    12361247                whose COM implementation creates COM objects.</para>
    12371248
    1238                 <para>For example, <xref linkend="IVirtualBox__createMachine"
    1239                 xreflabel="IVirtualBox::createMachine()" /> creates a new
    1240                 instance of <xref linkend="IMachine" xreflabel="IMachine" />;
     1249                <para>For example,
     1250                <link linkend="IVirtualBox__createMachine">IVirtualBox::createMachine()</link>
     1251                creates a new instance of
     1252                <link linkend="IMachine">IMachine</link>;
    12411253                the COM object returned by the COM method call is then wrapped
    12421254                into a managed object reference by the web server, and this
    … …  
    12551267
    12561268          <para>Managed object references are not destroyed automatically and
    1257           must be released by explicitly calling <xref
    1258           linkend="IManagedObjectRef__release"
    1259           xreflabel="IManagedObjectRef::release()" />. This is important, as
     1269          must be released by explicitly calling
     1270          <link linkend="IManagedObjectRef__release">IManagedObjectRef::release()</link>.
     1271          This is important, as
    12601272          otherwise hundreds or thousands of managed object references (and
    12611273          corresponding COM objects, which can consume much more memory!) can
    … …  
    12691281          them.</para>
    12701282
    1271           <para>When a web service client calls <xref
    1272           linkend="IWebsessionManager__logoff"
    1273           xreflabel="IWebsessionManager::logoff()" />, all managed object
    1274           references created during the session are automatically freed. For
    1275           short-lived sessions that do not create a lot of objects, logging
    1276           off may therefore be sufficient, although it is certainly not "best
    1277           practice".</para>
     1283          <para>When a web service client calls
     1284          <link linkend="IWebsessionManager__logoff">IWebsessionManager::logoff()</link>,
     1285          all managed object references created during the session are
     1286          automatically freed. For short-lived sessions that do not create a
     1287          lot of objects, logging off may therefore be sufficient, although it
     1288          is certainly not "best practice".</para>
    12781289        </sect3>
    12791290
    … …  
    13211332
    13221333            <para><screen>webServiceClass service("localhost", 18083); // server and port
    1323 string result = service.SayHello("Peter");  // invoke remote procedure</screen>and
    1324             would, for these two pseudo-lines, automatically perform these
     1334string result = service.SayHello("Peter");  // invoke remote procedure</screen>
     1335            and would, for these two pseudo-lines, automatically perform these
    13251336            steps:</para>
    13261337
    … …  
    13841395            procedure calls into the native language syntax -- for example,
    13851396            like in the Java sample shown in <xref
    1386             linkend="webservice-java-sample" />.</para>
     1397            linkend="webservice-java-sample"/>.</para>
    13871398
    13881399            <para>For details about how programming languages support web
    … …  
    14011412                <para>For <emphasis role="bold">Java, </emphasis> there are
    14021413                several implementations already described in this document
    1403                 (see <xref linkend="glue-jax-ws" /> and <xref
    1404                 linkend="webservice-java-sample" />).</para>
     1414                (see <xref linkend="glue-jax-ws"/> and <xref
     1415                linkend="webservice-java-sample"/>).</para>
    14051416              </listitem>
    14061417
    … …  
    14121423                (You can also import any WSDL file "live" by having it parsed
    14131424                every time the script runs, but that can take a while.) You
    1414                 can then code (again, assuming the above example):<screen>my $result = servicename-&gt;sayHello("Peter");</screen></para>
     1425                can then code (again, assuming the above example):
     1426                <screen>my $result = servicename-&gt;sayHello("Peter");</screen>
     1427                </para>
    14151428
    14161429                <para>A sample that uses SOAP::Lite was described in <xref
    1417                 linkend="raw-webservice-perl" />.</para>
     1430                linkend="raw-webservice-perl"/>.</para>
    14181431              </listitem>
    14191432            </orderedlist>
    … …  
    15331546        </screen>
    15341547        <para>
    1535           Following code will print all registered machines and their log folders
     1548          Following code will print all registered machines and their log
     1549          folders
    15361550        </para>
    15371551        <screen>from vboxapi import VirtualBoxManager
    … …  
    17601774
    17611775          <para>The sample program <computeroutput>tstCAPIGlue</computeroutput>
    1762           can be built using the provided <computeroutput>Makefile</computeroutput>
    1763           and can be run without arguments.</para>
     1776          can be built using the provided
     1777          <computeroutput>Makefile</computeroutput> and can be run without
     1778          arguments.</para>
    17641779
    17651780          <para>It uses the VBoxCAPIGlue library (source code is in directory
    … …  
    17881803          <computeroutput>VBoxCAPI_v4_3.h</computeroutput> header provides the
    17891804          interface to the C binding, but you can alternatively and more
    1790           conveniently also include <computeroutput>VBoxCAPIGlue.h</computeroutput>,
     1805          conveniently also include
     1806          <computeroutput>VBoxCAPIGlue.h</computeroutput>,
    17911807          as this avoids the VirtualBox version dependent header file name and
    17921808          makes sure the global variable <code>g_pVBoxFuncs</code> contains a
    … …  
    18771893          these rules to get the <computeroutput>IVirtualBox</computeroutput>
    18781894          reference, an <computeroutput>ISession</computeroutput> instance
    1879           reference and read the <xref linkend="IVirtualBox__revision"
    1880           xreflabel="IVirtualBox::revision" /> attribute:<screen>rc = IVirtualBoxClient_get_VirtualBox(vboxclient, &amp;vbox);
     1895          reference and read the
     1896          <link linkend="IVirtualBox__revision">IVirtualBox::revision</link>
     1897          attribute:
     1898          <screen>rc = IVirtualBoxClient_get_VirtualBox(vboxclient, &amp;vbox);
    18811899if (FAILED(rc) || !vbox)
    18821900{
    … …  
    19021920
    19031921          <para>So far only attribute getters were illustrated, but generic
    1904           method calls are straightforward, too:<screen>IMachine *machine = NULL;
     1922          method calls are straightforward, too:
     1923          <screen>IMachine *machine = NULL;
    19051924BSTR vmname = ...;
    19061925...
    … …  
    19111930
    19121931          <para>As a more complicated example of a method invocation, let's
    1913           call <xref linkend="IMachine__launchVMProcess"
    1914           xreflabel="IMachine::launchVMProcess" /> which returns an
    1915           IProgress object. Note again that the method name is
    1916           capitalized:<screen>IProgress *progress;
     1932          call
     1933          <link linkend="IMachine__launchVMProcess">IMachine::launchVMProcess</link>
     1934          which returns an IProgress object. Note again that the method name is
     1935          capitalized:
     1936          <screen>IProgress *progress;
    19171937...
    19181938rc = IMachine_LaunchVMProcess(
    … …  
    19251945
    19261946          <para>All objects with their methods and attributes are documented
    1927           in <xref linkend="sdkref_classes" />.</para>
     1947          in <xref linkend="sdkref_classes"/>.</para>
    19281948        </sect3>
    19291949
    … …  
    19411961          represented by a pointer to the start of the zero-terminated string.
    19421962          There are functions for converting between UTF-8 and UTF-16 strings
    1943           available through <code>g_pVBoxFuncs</code>:<screen>int (*pfnUtf16ToUtf8)(CBSTR pwszString, char **ppszString);
     1963          available through <code>g_pVBoxFuncs</code>:
     1964          <screen>int (*pfnUtf16ToUtf8)(CBSTR pwszString, char **ppszString);
    19441965int (*pfnUtf8ToUtf16)(const char *pszString, BSTR *ppwszString);</screen></para>
    19451966
    … …  
    19631984          <para>Passing arrays as input parameters to API methods is usually
    19641985          done by the following sequence, calling a hypothetical
    1965           <code>IArrayDemo_PassArray</code> API method:<screen>static const ULONG aElements[] = { 1, 2, 3, 4 };
     1986          <code>IArrayDemo_PassArray</code> API method:
     1987          <screen>static const ULONG aElements[] = { 1, 2, 3, 4 };
    19661988ULONG cElements = sizeof(aElements) / sizeof(aElements[0]);
    19671989SAFEARRAY *psa = NULL;
    … …  
    19731995          <para>Likewise, getting arrays results from output parameters is done
    19741996          using helper functions which manage memory allocations as part of
    1975           their other functionality:<screen>SAFEARRAY *psa = g_pVBoxFuncs->pfnSafeArrayOutParamAlloc();
     1997          their other functionality:
     1998          <screen>SAFEARRAY *psa = g_pVBoxFuncs->pfnSafeArrayOutParamAlloc();
    19761999ULONG *pData;
    19772000ULONG cElements;
    … …  
    19852008          gets the list of VMs, and passes the first IMachine reference to
    19862009          another API function (assuming that there is at least one element
    1987           in the array, to simplify the example):<screen>SAFEARRAY psa = g_pVBoxFuncs->pfnSafeArrayOutParamAlloc();
     2010          in the array, to simplify the example):
     2011          <screen>SAFEARRAY psa = g_pVBoxFuncs->pfnSafeArrayOutParamAlloc();
    19882012IMachine **machines = NULL;
    19892013ULONG machineCnt = 0;
    … …  
    20402064          <para>The actual event handler implementation is quite tedious, as
    20412065          it has to implement a complete API interface. Especially on Windows
    2042           it is a lot of work to implement the complicated <code>IDispatch</code>
    2043           interface, requiring to load COM type information and using it
    2044           in the <code>IDispatch</code> method implementation. Overall this is
    2045           quite tedious compared to passive event handling.</para>
     2066          it is a lot of work to implement the complicated
     2067          <code>IDispatch</code> interface, requiring to load COM type
     2068          information and using it in the <code>IDispatch</code> method
     2069          implementation. Overall this is quite tedious compared to passive
     2070          event handling.</para>
    20462071
    20472072          <para>Passive event handling uses a similar event loop structure,
    … …  
    20602085
    20612086          <para>The general event handling concepts are described in the API
    2062           specification (see <xref linkend="events" />), including how to
     2087          specification (see <xref linkend="events"/>), including how to
    20632088          aggregate multiple event sources for processing in one event loop.
    20642089          As mentioned, the sample illustrates the practical aspects of how to
    20652090          use both types of event handling, active and passive, from a C
    20662091          application. Additional hints are in the comments documenting
    2067           the helper methods in <computeroutput>VBoxCAPI_v4_3.h</computeroutput>.
    2068           The code complexity of active event handling (and its inherenly
    2069           platform/compiler specific aspects) should be motivation to use
    2070           passive event handling whereever possible.</para>
     2092          the helper methods in
     2093          <computeroutput>VBoxCAPI_v4_3.h</computeroutput>. The code complexity
     2094          of active event handling (and its inherenly platform/compiler
     2095          specific aspects) should be motivation to use passive event handling
     2096          whereever possible.</para>
    20712097        </sect3>
    20722098
    … …  
    21752201          if the code refers to them frequently.</para>
    21762202
    2177           <para>The C API client code should include <computeroutput>VBoxCAPIGlue.h</computeroutput>
    2178           instead of <computeroutput>VBoxXPCOMCGlue.h</computeroutput> or
     2203          <para>The C API client code should include
     2204          <computeroutput>VBoxCAPIGlue.h</computeroutput> instead of
     2205          <computeroutput>VBoxXPCOMCGlue.h</computeroutput> or
    21792206          <computeroutput>VBoxCAPI_v4_3.h</computeroutput>, as this makes sure
    21802207          the correct macros and internal translations are selected.</para>
    … …  
    21952222          <code>IErrorInfo</code> for the first two respectively. Event queue
    21962223          handling should be replaced by using the platform independent way
    2197           described in <xref linkend="c-eventhandling" />.</para>
     2224          described in <xref linkend="c-eventhandling"/>.</para>
    21982225
    21992226          <para>Finally adjust the string and array handling to use the new
    … …  
    22392266
    22402267      <para>Any program using the Main API will first need access to the
    2241       global VirtualBox object (see <xref linkend="IVirtualBox"
    2242       xreflabel="IVirtualBox" />), from which all other functionality of the
    2243       API is derived. With the OOWS for JAX-WS, this is returned from the
    2244       <xref linkend="IWebsessionManager__logon"
    2245       xreflabel="IWebsessionManager::logon()" /> call.</para>
     2268      global VirtualBox object (see
     2269      <link linkend="IVirtualBox">IVirtualBox</link>), from which all other
     2270      functionality of the API is derived. With the OOWS for JAX-WS, this is
     2271      returned from the
     2272      <link linkend="IWebsessionManager__logon">IWebsessionManager::logon()</link>
     2273      call.</para>
    22462274
    22472275      <para>To enumerate virtual machines, one would look at the "machines"
    2248       array attribute in the VirtualBox object (see <xref
    2249       linkend="IVirtualBox__machines" xreflabel="IVirtualBox::machines" />).
     2276      array attribute in the VirtualBox object (see
     2277      <link linkend="IVirtualBox__machines">IVirtualBox::machines</link>).
    22502278      This array contains all virtual machines currently registered with the
    2251       host, each of them being an instance of <xref linkend="IMachine"
    2252       xreflabel="IMachine" />. From each such instance, one can query
    2253       additional information, such as the UUID, the name, memory, operating
    2254       system and more by looking at the attributes; see the attributes list in
    2255       <xref linkend="IMachine" xreflabel="IMachine documentation" />.</para>
     2279      host, each of them being an instance of
     2280      <link linkend="IMachine">IMachine</link>.
     2281      From each such instance, one can query additional information, such as
     2282      the UUID, the name, memory, operating system and more by looking at the
     2283      attributes; see the attributes list in
     2284      <link linkend="IMachine">IMachine</link> documentation.</para>
    22562285
    22572286      <para>As mentioned in the preceding chapters, depending on your
    22582287      programming environment, attributes are mapped to corresponding "get"
    22592288      and (if the attribute is not read-only) "set" methods. So when the
    2260       documentation says that IMachine has a "<xref linkend="IMachine__name"
    2261       xreflabel="name" />" attribute, this means you need to code something
    2262       like the following to get the machine's name:<screen>IMachine machine = ...;
    2263 String name = machine.getName();</screen>Boolean attribute getters can
    2264       sometimes be called <computeroutput>isAttribute()</computeroutput> due
    2265       to JAX-WS naming conventions.</para>
     2289      documentation says that IMachine has a
     2290      "<link linkend="IMachine__name">name</link>" attribute, this means you
     2291      need to code something
     2292      like the following to get the machine's name:
     2293      <screen>IMachine machine = ...;
     2294String name = machine.getName();</screen>
     2295      Boolean attribute getters can sometimes be called
     2296      <computeroutput>isAttribute()</computeroutput> due to JAX-WS naming
     2297      conventions.</para>
    22662298    </sect1>
    22672299
    … …  
    22882320
    22892321      <para>These requirements are implemented in the Main API by way of
    2290       "sessions", in particular, the <xref linkend="ISession"
    2291       xreflabel="ISession" /> interface. Each process which talks to
     2322      "sessions", in particular, the <link linkend="ISession">ISession</link>
     2323      interface. Each process which talks to
    22922324      VirtualBox needs its own instance of ISession. In the web service, you
    2293       can request the creation of such an object by calling <xref
    2294       linkend="IWebsessionManager__getSessionObject"
    2295       xreflabel="IWebsessionManager::getSessionObject()" />. More complex
    2296       management tasks might need multiple instances of ISession, and each call
    2297       returns a new one.</para>
     2325      can request the creation of such an object by calling
     2326      <link linkend="IWebsessionManager__getSessionObject">IWebsessionManager::getSessionObject()</link>.
     2327      More complex management tasks might need multiple instances of ISession,
     2328      and each call returns a new one.</para>
    22982329
    22992330      <para>This session object must then be used like a mutex semaphore in
    23002331      common programming environments. Before you can change machine settings,
    2301       you must write-lock the machine by calling <xref
    2302       linkend="IMachine__lockMachine" xreflabel="IMachine::lockMachine()" />
     2332      you must write-lock the machine by calling
     2333      <link linkend="IMachine__lockMachine">IMachine::lockMachine()</link>
    23032334      with your process's session object.</para>
    23042335
    2305       <para>After the machine has been locked, the <xref
    2306       linkend="ISession__machine" xreflabel="ISession::machine" /> attribute
     2336      <para>After the machine has been locked, the
     2337      <link linkend="ISession__machine">ISession::machine</link> attribute
    23072338      contains a copy of the original IMachine object upon which the session
    23082339      was opened, but this copy is "mutable": you can invoke "set" methods on
    23092340      it.</para>
    23102341
    2311       <para>When done making the changes to the machine, you must call <xref
    2312       linkend="IMachine__saveSettings"
    2313       xreflabel="IMachine::saveSettings()" />, which will copy the changes you
    2314       have made from your "mutable" machine back to the real machine and write
    2315       them out to the machine settings XML file. This will make your changes
    2316       permanent.</para>
     2342      <para>When done making the changes to the machine, you must call
     2343      <link linkend="IMachine__saveSettings">IMachine::saveSettings()</link>,
     2344      which will copy the changes you have made from your "mutable" machine
     2345      back to the real machine and write them out to the machine settings XML
     2346      file. This will make your changes permanent.</para>
    23172347
    23182348      <para>Finally, it is important to always unlock the machine again, by
    2319       calling <xref linkend="ISession__unlockMachine"
    2320       xreflabel="ISession::unlockMachine()" />. Otherwise, when the calling
    2321       process end, the machine will receive the "aborted" state, which can
    2322       lead to loss of data.</para>
     2349      calling
     2350      <link linkend="ISession__unlockMachine">ISession::unlockMachine()</link>.
     2351      Otherwise, when the calling process end, the machine will receive the
     2352      "aborted" state, which can lead to loss of data.</para>
    23232353
    23242354      <para>So, as an example, the sequence to change a machine's memory to
    … …  
    23382368      <title>Launching virtual machines</title>
    23392369
    2340       <para>To launch a virtual machine, you call <xref
    2341       linkend="IMachine__launchVMProcess"
    2342       xreflabel="IMachine::launchVMProcess()" />. In doing so, the caller
    2343       instructs the VirtualBox engine to start a new process with the virtual
    2344       machine in it, since to the host, each virtual machine looks like a
    2345       single process, even if it has hundreds of its own processes inside.
    2346       (This new VM process in turn obtains a write lock on the machine, as
    2347       described above, to prevent conflicting changes from other processes;
    2348       this is why opening another session will fail while the VM is
    2349       running.)</para>
    2350 
    2351       <para>Starting a machine looks something like this:<screen>IWebsessionManager mgr ...;
     2370      <para>To launch a virtual machine, you call
     2371      <link linkend="IMachine__launchVMProcess">IMachine::launchVMProcess()</link>.
     2372      In doing so, the caller instructs the VirtualBox engine to start a new
     2373      process with the virtual machine in it, since to the host, each virtual
     2374      machine looks like single process, even if it has hundreds of its own
     2375      processes inside. (This new VM process in turn obtains a write lock on
     2376      the machine, as described above, to prevent conflicting changes from
     2377      other processes; this is why opening another session will fail while the
     2378      VM is running.)</para>
     2379
     2380      <para>Starting a machine looks something like this:
     2381      <screen>IWebsessionManager mgr ...;
    23522382IVirtualBox vbox = mgr.logon(user, pass);
    23532383...
    … …  
    23632393      <para>The caller's session object can then be used as a sort of remote
    23642394      control to the VM process that was launched. It contains a "console"
    2365       object (see <xref linkend="ISession__console"
    2366       xreflabel="ISession::console" />) with which the VM can be paused,
     2395      object (see <link linkend="ISession__console">ISession::console</link>)
     2396      with which the VM can be paused,
    23672397      stopped, snapshotted or other things.</para>
    23682398    </sect1>
    … …  
    23732403      <para>In VirtualBox, "events" provide a uniform mechanism to register
    23742404      for and consume specific events. A VirtualBox client can register an
    2375       "event listener" (represented by the <xref linkend="IEventListener"
    2376       xreflabel="IEventListener" /> interface), which will then get notified
    2377       by the server when an event (represented by the <xref linkend="IEvent"
    2378       xreflabel="IEvent" /> interface) happens.</para>
     2405      "event listener" (represented by the
     2406      <link linkend="IEventListener">IEventListener</link> interface), which
     2407      will then get notified by the server when an event (represented by the
     2408      <link linkend="IEvent">IEvent</link> interface) happens.</para>
    23792409
    23802410      <para>The IEvent interface is an abstract parent interface for all
    23812411      events that can occur in VirtualBox. The actual events that the server
    2382       sends out are then of one of the specific subclasses, for example <xref
    2383       linkend="IMachineStateChangedEvent"
    2384       xreflabel="IMachineStateChangedEvent" /> or <xref
    2385       linkend="IMediumChangedEvent" xreflabel="IMediumChangedEvent" />.</para>
     2412      sends out are then of one of the specific subclasses, for example
     2413      <link linkend="IMachineStateChangedEvent">IMachineStateChangedEvent</link>
     2414      or
     2415      <link linkend="IMediumChangedEvent">IMediumChangedEvent</link>.</para>
    23862416
    23872417      <para>As an example, the VirtualBox GUI waits for machine events and can
    … …  
    24512481
    24522482    <para>You can easily extend this shell with your own commands. Create a
    2453     subdirectory named <computeroutput>.config/VirtualBox/shexts</computeroutput>
    2454     below your home directory (respectively <computeroutput>.VirtualBox/shexts</computeroutput> on a Windows system and <computeroutput>Library/VirtualBox/shexts</computeroutput> on OS X) and put a Python file implementing your shell
    2455     extension commands in this directory. This file must contain an array
    2456     named <computeroutput>commands</computeroutput> containing your command
     2483    subdirectory named
     2484    <computeroutput>.config/VirtualBox/shexts</computeroutput> below your home
     2485    directory (respectively <computeroutput>.VirtualBox/shexts</computeroutput>
     2486    on a Windows system and
     2487    <computeroutput>Library/VirtualBox/shexts</computeroutput> on OS X) and put
     2488    a Python file implementing your shell extension commands in this directory.
     2489    This file must contain an array named
     2490    <computeroutput>commands</computeroutput> containing your command
    24572491    definitions: <screen>
    24582492        commands = {
    … …  
    34963530    <para>Since VirtualBox 4.2 it's possible to transfer files from host to the
    34973531    Linux guests by dragging files, directories or text from the host into the
    3498     guest's screen. This is called <emphasis>drag'n drop (DnD)</emphasis>.</para>
     3532    guest's screen. This is called <emphasis>drag'n drop
     3533    (DnD)</emphasis>.</para>
    34993534
    35003535    <para>In version 5.0 support for Windows guests has been added, as well as
    … …  
    35173552      <emphasis>source</emphasis> and a <emphasis>target</emphasis>:</para>
    35183553
    3519       <para>The <emphasis>source</emphasis> is the side which provides the data,
    3520       e.g. is the origin of data. This data can be stored within the source directly
    3521       or can be retrieved on-demand by the source itself. Other interfaces don't
    3522       care where the data from this source actually came from.</para>
     3554      <para>The <emphasis>source</emphasis> is the side which provides the
     3555      data, e.g. is the origin of data. This data can be stored within the
     3556      source directly or can be retrieved on-demand by the source itself. Other
     3557      interfaces don't care where the data from this source actually came
     3558      from.</para>
    35233559
    35243560      <para>The <emphasis>target</emphasis> on the other hand is the side which
    35253561      provides the source a visual representation where the user can drop the
    3526       data the source offers. This representation can be a window (or just a certain
    3527       part of it), for example.</para>
     3562      data the source offers. This representation can be a window (or just a
     3563      certain part of it), for example.</para>
    35283564
    35293565      <para>The source and the target have abstract interfaces called
    3530       <xref linkend="IDnDSource" xreflabel="IDnDSource" /> and
    3531       <xref linkend="IDnDTarget" xreflabel="IDnDTarget" />. VirtualBox also
     3566      <link linkend="IDnDSource">IDnDSource</link> and
     3567      <link linkend="IDnDTarget">IDnDTarget</link>. VirtualBox also
    35323568      provides implementations of both interfaces, called
    3533       <xref linkend="IGuestDnDSource" xreflabel="IGuestDnDSource" /> and
    3534       <xref linkend="IGuestDnDTarget" xreflabel="IGuestDnDTarget" />. Both
     3569      <link linkend="IGuestDnDSource">IGuestDnDSource</link> and
     3570      <link linkend="IGuestDnDTarget">IGuestDnDTarget</link>. Both
    35353571      implementations are also used in the VirtualBox Manager frontend.</para>
    35363572    </sect1>
    … …  
    35393575      <title>Supported formats</title>
    35403576
    3541       <para>As the target needs to perform specific actions depending on the data
    3542       the source provided, the target first needs to know what type of data it
    3543       actually is going to retrieve. It might be that the source offers data the
    3544       target cannot (or intentionally does not want to) support.</para>
     3577      <para>As the target needs to perform specific actions depending on the
     3578      data the source provided, the target first needs to know what type of
     3579      data it actually is going to retrieve. It might be that the source offers
     3580      data the target cannot (or intentionally does not want to)
     3581      support.</para>
    35453582
    35463583      <para>VirtualBox handles those data types by providing so-called
    3547       <emphasis>MIME types</emphasis> -- these MIME types were originally defined
    3548       in <ulink url="https://tools.ietf.org/html/rfc2046">RFC 2046</ulink> and
     3584      <emphasis>MIME types</emphasis> -- these MIME types were originally
     3585      defined in
     3586      <ulink url="https://tools.ietf.org/html/rfc2046">RFC 2046</ulink> and
    35493587      are also called <emphasis>Content-types</emphasis>.
    3550       <xref linkend="IGuestDnDSource" xreflabel="IGuestDnDSource" /> and
    3551       <xref linkend="IGuestDnDTarget" xreflabel="IGuestDnDTarget" /> support
     3588      <link linkend="IGuestDnDSource">IGuestDnDSource</link> and
     3589      <link linkend="IGuestDnDTarget">IGuestDnDTarget</link> support
    35523590      the following MIME types by default:<itemizedlist>
    35533591          <listitem>
    3554             <para><emphasis role="bold">text/uri-list</emphasis> - A list of URIs
    3555             (Uniform Resource Identifier, see
     3592            <para><emphasis role="bold">text/uri-list</emphasis> - A list of
     3593            URIs (Uniform Resource Identifier, see
    35563594            <ulink url="https://tools.ietf.org/html/rfc3986">RFC 3986</ulink>)
    3557             pointing to the file and/or directory paths already transferred from
    3558             the source to the target.</para>
     3595            pointing to the file and/or directory paths already transferred
     3596            from the source to the target.</para>
    35593597          </listitem>
    35603598          <listitem>
    35613599            <para><emphasis role="bold">text/plain;charset=utf-8</emphasis> and
    3562             <emphasis role="bold">UTF8_STRING</emphasis> - text in UTF8 format.</para>
     3600            <emphasis role="bold">UTF8_STRING</emphasis> - text in UTF-8
     3601            format.</para>
    35633602          </listitem>
    35643603          <listitem>
    35653604            <para><emphasis role="bold">text/plain, TEXT</emphasis>
    3566             and <emphasis role="bold">STRING</emphasis> - plain ASCII text, depending
    3567             on the source's active ANSI page (if any).</para>
     3605            and <emphasis role="bold">STRING</emphasis> - plain ASCII text,
     3606            depending on the source's active ANSI page (if any).</para>
    35683607          </listitem>
    35693608        </itemizedlist>
    35703609      </para>
    35713610
    3572       <para>If, for whatever reason, a certain default format should not be supported
    3573       or a new format should be registered,
    3574       <xref linkend="IDnDSource" xreflabel="IDnDSource" /> and
    3575       <xref linkend="IDnDTarget" xreflabel="IDnDTarget" /> have methods derived from
    3576       <xref linkend="IDnDBase" xreflabel="IDnDBase" /> which provide adding,
     3611      <para>If, for whatever reason, a certain default format should not be
     3612      supported or a new format should be registered,
     3613      <link linkend="IDnDSource">IDnDSource</link> and
     3614      <link linkend="IDnDTarget">IDnDTarget</link> have methods derived from
     3615      <link linkend="IDnDBase">IDnDBase</link> which provide adding,
    35773616      removing and enumerating specific formats.
    35783617      <note><para>Registering new or removing default formats on the guest side
    … …  
    37383777            class path.</para>
    37393778
    3740             <para>Start your application like this: <programlisting>
    3741  java -cp vboxjmscom.jar;c:\jacob\jacob.jar -Djava.library.path=c:\jacob MyProgram
    3742               </programlisting></para>
     3779            <para>Start your application like this:
     3780            <programlisting>java -cp vboxjmscom.jar;c:\jacob\jacob.jar -Djava.library.path=c:\jacob MyProgram</programlisting></para>
    37433781          </listitem>
    37443782
    … …  
    38663904          those operations in the case where no VM is running.
    38673905          <itemizedlist>
    3868             <listitem><xref linkend="IMachine__saveState"
    3869                 xreflabel="IMachine::saveState()" /> replaces
    3870               <computeroutput>IConsole::saveState()</computeroutput>
    3871             </listitem>
    3872             <listitem>
    3873               <xref linkend="IMachine__adoptSavedState"
    3874                 xreflabel="IMachine::adoptSavedState()" /> replaces
    3875               <computeroutput>IConsole::adoptSavedState()</computeroutput>
    3876             </listitem>
    3877             <listitem>
    3878               <xref linkend="IMachine__discardSavedState"
    3879                 xreflabel="IMachine::discardSavedState()" /> replaces
    3880               <computeroutput>IConsole::discardSavedState()</computeroutput>
    3881             </listitem>
    3882             <listitem>
    3883               <xref linkend="IMachine__takeSnapshot"
    3884                 xreflabel="IMachine::takeSnapshot()" /> replaces
    3885               <computeroutput>IConsole::takeSnapshot()</computeroutput>
    3886             </listitem>
    3887             <listitem>
    3888               <xref linkend="IMachine__deleteSnapshot"
    3889                 xreflabel="IMachine::deleteSnapshot()" /> replaces
    3890               <computeroutput>IConsole::deleteSnapshot()</computeroutput>
    3891             </listitem>
    3892             <listitem>
    3893               <xref linkend="IMachine__deleteSnapshotAndAllChildren"
    3894                 xreflabel="IMachine::deleteSnapshotAndAllChildren()" /> replaces
    3895               <computeroutput>IConsole::deleteSnapshotAndAllChildren()</computeroutput>
    3896             </listitem>
    3897             <listitem>
    3898                <xref linkend="IMachine__deleteSnapshotRange"
    3899                 xreflabel="IMachine::deleteSnapshotRange()" /> replaces
    3900                <computeroutput>IConsole::deleteSnapshotRange()</computeroutput>
     3906            <listitem><para><link linkend="IMachine__saveState">IMachine::saveState()</link>
     3907              replaces
     3908              <computeroutput>IConsole::saveState()</computeroutput></para>
     3909            </listitem>
     3910            <listitem>
     3911              <para><link linkend="IMachine__adoptSavedState">IMachine::adoptSavedState()</link>
     3912              replaces
     3913              <computeroutput>IConsole::adoptSavedState()</computeroutput></para>
     3914            </listitem>
     3915            <listitem>
     3916              <para><link linkend="IMachine__discardSavedState">IMachine::discardSavedState()</link>
     3917              replaces
     3918              <computeroutput>IConsole::discardSavedState()</computeroutput></para>
     3919            </listitem>
     3920            <listitem>
     3921              <para><link linkend="IMachine__takeSnapshot">IMachine::takeSnapshot()</link>
     3922              replaces
     3923              <computeroutput>IConsole::takeSnapshot()</computeroutput></para>
     3924            </listitem>
     3925            <listitem>
     3926              <para><link linkend="IMachine__deleteSnapshot">IMachine::deleteSnapshot()</link>
     3927              replaces
     3928              <computeroutput>IConsole::deleteSnapshot()</computeroutput></para>
     3929            </listitem>
     3930            <listitem>
     3931              <para><link linkend="IMachine__deleteSnapshotAndAllChildren">IMachine::deleteSnapshotAndAllChildren()</link>
     3932              replaces
     3933              <computeroutput>IConsole::deleteSnapshotAndAllChildren()</computeroutput></para>
     3934            </listitem>
     3935            <listitem>
     3936               <para><link linkend="IMachine__deleteSnapshotRange">IMachine::deleteSnapshotRange()</link>
     3937               replaces
     3938               <computeroutput>IConsole::deleteSnapshotRange()</computeroutput></para>
    39013939             </listitem>
    39023940             <listitem>
    3903                <xref linkend="IMachine__restoreSnapshot"
    3904                 xreflabel="IMachine::restoreSnapshot()" /> replaces
    3905                <computeroutput>IConsole::restoreSnapshot()</computeroutput>
     3941               <para><link linkend="IMachine__restoreSnapshot">IMachine::restoreSnapshot()</link>
     3942               replaces
     3943               <computeroutput>IConsole::restoreSnapshot()</computeroutput></para>
    39063944             </listitem>
    39073945           </itemizedlist>
    … …  
    39163954          <para>Two new machine states have been introduced to allow proper
    39173955          distinction between saving state and taking a snapshot.
    3918           <xref linkend="MachineState__Saving" xreflabel="MachineState::Saving" />
     3956          <link linkend="MachineState__Saving">MachineState::Saving</link>
    39193957          now is used exclusively while the VM's state is being saved, without
    39203958          any overlaps with snapshot functionality. The new state
    3921           <xref linkend="MachineState__Snapshotting" xreflabel="MachineState::Snapshotting" />
     3959          <link linkend="MachineState__Snapshotting">MachineState::Snapshotting</link>
    39223960          is used when an offline snapshot is taken and likewise the new state
    3923           <xref linkend="MachineState__OnlineSnapshotting" xreflabel="MachineState::OnlineSnapshotting" />
     3961          <link linkend="MachineState__OnlineSnapshotting">MachineState::OnlineSnapshotting</link>
    39243962          is used when an online snapshot is taken.</para>
    39253963        </listitem>
    39263964
    39273965        <listitem>
    3928           <para>A new event has been introduced, which signals when a snapshot has been
    3929           restored:
    3930           <xref linkend="ISnapshotRestoredEvent" xreflabel="ISnapshotRestoredEvent"/>.
     3966          <para>A new event has been introduced, which signals when a snapshot
     3967          has been restored:
     3968          <link linkend="ISnapshotRestoredEvent">ISnapshotRestoredEvent</link>.
    39313969          Previously the event
    3932           <xref linkend="ISnapshotDeletedEvent" xreflabel="ISnapshotDeletedEvent"/> was
    3933           signalled, which isn't logical (but could be distinguished from actual deletion
    3934           by the fact that the snapshot was still there).</para>
    3935         </listitem>
    3936 
    3937         <listitem>
    3938           <para>The method <xref linkend="IVirtualBox__createMedium"
    3939           xreflabel="IVirtualBox::createMedium()" /> replaces
     3970          <link linkend="ISnapshotDeletedEvent">ISnapshotDeletedEvent</link>
     3971          was signalled, which isn't logical (but could be distinguished from
     3972          actual deletion by the fact that the snapshot was still
     3973          there).</para>
     3974        </listitem>
     3975
     3976        <listitem>
     3977          <para>The method
     3978          <link linkend="IVirtualBox__createMedium">IVirtualBox::createMedium()</link>
     3979          replaces
    39403980          <computeroutput>VirtualBox::createHardDisk()</computeroutput>.
    39413981          Adjusting existing code needs adding two parameters with
    … …  
    39483988
    39493989        <listitem>
    3950           <para>The method <xref linkend="IMachine__getStorageControllerByInstance"
    3951           xreflabel="IMachine::getStorageControllerByInstance()" /> now has an
    3952           additional parameter (first parameter), for specifying the storage
    3953           bus which the storage controller must be using. The method was not
    3954           useful before, as the instance numbers are only unique for a specfic
    3955           storage bus.</para>
    3956         </listitem>
    3957 
    3958         <listitem>
    3959           <para>The attribute <computeroutput>IMachine::sessionType</computeroutput>
    3960           has been renamed to <xref linkend="IMachine__sessionName"
    3961           xreflabel="IMachine::sessionName()" />. This cleans up the confusing
    3962           terminology (as the session type is something different).</para>
    3963         </listitem>
    3964 
    3965         <listitem>
    3966           <para>The attribute <computeroutput>IMachine::guestPropertyNotificationPatterns</computeroutput>
     3990          <para>The method
     3991          <link linkend="IMachine__getStorageControllerByInstance">IMachine::getStorageControllerByInstance()</link>
     3992          now has an additional parameter (first parameter), for specifying the
     3993          storage bus which the storage controller must be using. The method
     3994          was not useful before, as the instance numbers are only unique for a
     3995          specfic storage bus.</para>
     3996        </listitem>
     3997
     3998        <listitem>
     3999          <para>The attribute
     4000          <computeroutput>IMachine::sessionType</computeroutput> has been
     4001          renamed to
     4002          <link linkend="IMachine__sessionName">IMachine::sessionName()</link>.
     4003          This cleans up the confusing terminology (as the session type is
     4004          something different).</para>
     4005        </listitem>
     4006
     4007        <listitem>
     4008          <para>The attribute
     4009          <computeroutput>IMachine::guestPropertyNotificationPatterns</computeroutput>
    39674010          has been removed. In practice it was not usable because it is too
    39684011          global and didn't distinguish between API clients.</para>
    … …  
    39724015
    39734016          <listitem>
    3974             <para>Methods for providing host to guest drag'n drop functionality,
    3975               such as <computeroutput>IGuest::dragHGEnter</computeroutput>,
     4017            <para>Methods for providing host to guest drag'n drop
     4018              functionality, such as
     4019              <computeroutput>IGuest::dragHGEnter</computeroutput>,
    39764020              <computeroutput>IGuest::dragHGMove()</computeroutput>,
    39774021              <computeroutput>IGuest::dragHGLeave()</computeroutput>,
    … …  
    39794023              <computeroutput>IGuest::dragHGPutData()</computeroutput>,
    39804024              have been moved to an abstract base class called
    3981               <xref linkend="IDnDTarget" xreflabel="IDnDTarget" />. VirtualBox implements
    3982               this base class in the <xref linkend="IGuestDnDTarget" xreflabel="IGuestDnDTarget" />
     4025              <link linkend="IDnDTarget">IDnDTarget</link>.
     4026              VirtualBox implements this base class in the
     4027              <link linkend="IGuestDnDTarget">IGuestDnDTarget</link>
    39834028              interface. The implementation can be used by using the
    3984               <xref linkend="IGuest__dnDTarget" xreflabel="IGuest::dnDTarget()" /> method.</para>
    3985             <para>Methods for providing guest to host drag'n drop functionality,
    3986               such as <computeroutput>IGuest::dragGHPending()</computeroutput>,
     4029              <link linkend="IGuest__dnDTarget">IGuest::dnDTarget()</link>
     4030              method.</para>
     4031            <para>Methods for providing guest to host drag'n drop
     4032              functionality, such as
     4033              <computeroutput>IGuest::dragGHPending()</computeroutput>,
    39874034              <computeroutput>IGuest::dragGHDropped()</computeroutput> and
    39884035              <computeroutput>IGuest::dragGHGetData()</computeroutput>,
    39894036              have been moved to an abstract base class called
    3990               <xref linkend="IDnDSource" xreflabel="IDnDSource" />. VirtualBox implements
    3991               this base class in the <xref linkend="IGuestDnDSource" xreflabel="IGuestDnDSource" />
     4037              <link linkend="IDnDSource">IDnDSource</link>.
     4038              VirtualBox implements this base class in the
     4039              <link linkend="IGuestDnDSource">IGuestDnDSource</link>
    39924040              interface. The implementation can be used by using the
    3993               <xref linkend="IGuest__dnDSource" xreflabel="IGuest::dnDSource()" /> method.</para>
     4041              <link linkend="IGuest__dnDSource">IGuest::dnDSource()</link>
     4042              method.</para>
    39944043          </listitem>
    39954044
    39964045          <listitem>
    3997             <para>The <computeroutput>DragAndDropAction</computeroutput> enumeration has been
    3998               renamed to <xref linkend="DnDAction" xreflabel="DnDAction" />.</para>
     4046            <para>The <computeroutput>DragAndDropAction</computeroutput>
     4047            enumeration has been renamed to
     4048            <link linkend="DnDAction">DnDAction</link>.</para>
    39994049          </listitem>
    40004050
    40014051          <listitem>
    4002             <para>The <computeroutput>DragAndDropMode</computeroutput> enumeration has been
    4003               renamed to <xref linkend="DnDMode" xreflabel="DnDMode" />.</para>
     4052            <para>The <computeroutput>DragAndDropMode</computeroutput>
     4053            enumeration has been renamed to
     4054            <link linkend="DnDMode">DnDMode</link>.</para>
    40044055          </listitem>
    40054056
    40064057          <listitem>
    4007             <para>The attribute <computeroutput>IMachine::dragAndDropMode</computeroutput>
    4008               has been renamed to <xref linkend="IMachine__dnDMode" xreflabel="IMachine::dnDMode()" />.</para>
     4058            <para>The attribute
     4059            <computeroutput>IMachine::dragAndDropMode</computeroutput>
     4060            has been renamed to
     4061            <link linkend="IMachine__dnDMode">IMachine::dnDMode()</link>.</para>
    40094062          </listitem>
    40104063
    40114064          <listitem>
    4012             <para>The event <computeroutput>IDragAndDropModeChangedEvent</computeroutput>
    4013               has been renamed to <xref linkend="IDnDModeChangedEvent" xreflabel="IDnDModeChangedEvent" />.</para>
     4065            <para>The event
     4066            <computeroutput>IDragAndDropModeChangedEvent</computeroutput>
     4067            has been renamed to
     4068            <link linkend="IDnDModeChangedEvent">IDnDModeChangedEvent</link>.</para>
    40144069          </listitem>
    40154070
    4016           <listitem>
    4017             <para>The callback method <computeroutput>IInternalSessionControl::onDragAndDropModeChange</computeroutput>
    4018               has been renamed to <xref linkend="IInternalSessionControl__onDnDModeChange" xreflabel="IInternalSessionControl::onDnDModeChange()" />.</para>
    4019           </listitem>
    4020 
    40214071          </itemizedlist></para>
    40224072        </listitem>
    40234073
    4024         <listitem><para>IDisplay and IFramebuffer interfaces were changed to allow IFramebuffer
    4025           object to reside in a separate frontend process:<itemizedlist>
     4074        <listitem><para>IDisplay and IFramebuffer interfaces were changed to
     4075          allow IFramebuffer object to reside in a separate frontend
     4076          process:<itemizedlist>
    40264077
    40274078          <listitem><para>
    4028             IDisplay::ResizeCompleted() has been removed, because the IFramebuffer object
    4029             does not provide the screen memory anymore.
     4079            IDisplay::ResizeCompleted() has been removed, because the
     4080            IFramebuffer object does not provide the screen memory anymore.
    40304081          </para></listitem>
    40314082
    40324083          <listitem><para>
    4033             IDisplay::SetFramebuffer() has been replaced with IDisplay::AttachFramebuffer()
    4034             and IDisplay::DetachFramebuffer().
     4084            IDisplay::SetFramebuffer() has been replaced with
     4085            IDisplay::AttachFramebuffer() and IDisplay::DetachFramebuffer().
    40354086          </para></listitem>
    40364087
    40374088          <listitem><para>
    4038             IDisplay::GetFramebuffer() has been replaced with IDisplay::QueryFramebuffer().
     4089            IDisplay::GetFramebuffer() has been replaced with
     4090            IDisplay::QueryFramebuffer().
    40394091          </para></listitem>
    40404092
    … …  
    40464098
    40474099          <listitem><para>
    4048             IDisplay::TakeScreenShot() and IDisplay::TakeScreenShotToArray() have a new parameter
    4049             <computeroutput>bitmapFormat</computeroutput>. As a consequence of this,
    4050             IDisplay::TakeScreenShotPNGToArray() has been removed.
     4100            IDisplay::TakeScreenShot() and IDisplay::TakeScreenShotToArray()
     4101            have a new parameter
     4102            <computeroutput>bitmapFormat</computeroutput>. As a consequence of
     4103            this, IDisplay::TakeScreenShotPNGToArray() has been removed.
    40514104          </para></listitem>
    40524105
    40534106          <listitem><para>
    4054             IFramebuffer::RequestResize() has been replaced with IFramebuffer::NotifyChange().
     4107            IFramebuffer::RequestResize() has been replaced with
     4108            IFramebuffer::NotifyChange().
    40554109          </para></listitem>
    40564110
    40574111          <listitem><para>
    4058             IFramebuffer::NotifyUpdateImage() added to support IFramebuffer objects in a different process.
     4112            IFramebuffer::NotifyUpdateImage() added to support IFramebuffer
     4113            objects in a different process.
    40594114          </para></listitem>
    40604115
    40614116          <listitem><para>
    4062             IFramebuffer::Lock(), IFramebuffer::Unlock(), IFramebuffer::Address(), IFramebuffer::UsesGuestVRAM()
    4063             have been removed because  the IFramebuffer object does not provide the screen memory anymore.
     4117            IFramebuffer::Lock(), IFramebuffer::Unlock(),
     4118            IFramebuffer::Address(), IFramebuffer::UsesGuestVRAM() have been
     4119            removed because the IFramebuffer object does not provide the screen
     4120            memory anymore.
    40644121          </para></listitem>
    40654122
    … …  
    40674124        </listitem>
    40684125
    4069         <listitem><para>IGuestSession, IGuestFile and IGuestProcess interfaces were changed as follows:
     4126        <listitem><para>IGuestSession, IGuestFile and IGuestProcess interfaces
     4127        were changed as follows:
    40704128          <itemizedlist>
    40714129            <listitem>
    4072               <para>Replaced IGuestSession::directoryQueryInfo and IGuestSession::fileQueryInfo with a new
    4073                  <xref linkend="IGuestSession__fsObjQueryInfo" xreflabel="IGuestSession::fsObjQueryInfo"/> method
    4074                  that works on any type of file system object.</para>
    4075             </listitem>
    4076             <listitem>
    4077               <para>Replaced IGuestSession::fileRemove, IGuestSession::symlinkRemoveDirectory and
     4130              <para>Replaced IGuestSession::directoryQueryInfo and
     4131                 IGuestSession::fileQueryInfo with a new
     4132                 <link linkend="IGuestSession__fsObjQueryInfo">IGuestSession::fsObjQueryInfo</link>
     4133                 method that works on any type of file system object.</para>
     4134            </listitem>
     4135            <listitem>
     4136              <para>Replaced IGuestSession::fileRemove,
     4137                 IGuestSession::symlinkRemoveDirectory and
    40784138                 IGuestSession::symlinkRemoveFile with a new
    4079                  <xref linkend="IGuestSession__fsObjRemove" xreflabel="IGuestSession::fsObjRemove"/> method that works
    4080                  on any type of file system object except directories. (fileRemove also worked on any type of object too,
     4139                 <link linkend="IGuestSession__fsObjRemove">IGuestSession::fsObjRemove</link>
     4140                 method that works on any type of file system object except
     4141                 directories. (fileRemove also worked on any type of object
     4142                 too, though that was not the intent of the method.)</para>
     4143            </listitem>
     4144            <listitem>
     4145              <para>Replaced IGuestSession::directoryRename and
     4146                 IGuestSession::directoryRename with a new
     4147                 <link linkend="IGuestSession__fsObjRename">IGuestSession::fsObjRename</link>
     4148                 method that works on any type of file system object.
     4149                 (directoryRename and fileRename may already have worked for
     4150                 any kind of object, but that was never the intent of the
     4151                 methods.)</para>
     4152            </listitem>
     4153            <listitem>
     4154              <para>Replaced the unimplemented IGuestSession::directorySetACL
     4155                 and IGuestSession::fileSetACL with a new
     4156                 <link linkend="IGuestSession__fsObjSetACL">IGuestSession::fsObjSetACL</link>
     4157                 method that works on all type of file system object. Also
     4158                 added a UNIX-style mode parameter as an alternative to the
     4159                 ACL.</para>
     4160            </listitem>
     4161            <listitem>
     4162              <para>Replaced IGuestSession::fileRemove,
     4163                 IGuestSession::symlinkRemoveDirectory and
     4164                 IGuestSession::symlinkRemoveFile with a new
     4165                 <link linkend="IGuestSession__fsObjRemove">IGuestSession::fsObjRemove</link>
     4166                 method that works on any type of file system object except
     4167                 directories (fileRemove also worked on any type of object,
    40814168                 though that was not the intent of the method.)</para>
    40824169            </listitem>
    40834170            <listitem>
    4084               <para>Replaced IGuestSession::directoryRename and IGuestSession::directoryRename with a new
    4085                  <xref linkend="IGuestSession__fsObjRename" xreflabel="IGuestSession::fsObjRename"/> method that works
    4086                  on any type of file system object. (directoryRename and fileRename may already have worked for any kind
    4087                  of object, but that was never the intent of the methods.)</para>
    4088             </listitem>
    4089             <listitem>
    4090               <para>Replaced the unimplemented IGuestSession::directorySetACL and IGuestSession::fileSetACL with a new
    4091                  <xref linkend="IGuestSession__fsObjSetACL" xreflabel="IGuestSession::fsObjSetACL"/> method that works
    4092                  on all type of file system object. Also added a UNIX-style mode parameter as an alternative to the ACL.</para>
    4093             </listitem>
    4094             <listitem>
    4095               <para>Replaced IGuestSession::fileRemove, IGuestSession::symlinkRemoveDirectory and
    4096                  IGuestSession::symlinkRemoveFile with a new
    4097                  <xref linkend="IGuestSession__fsObjRemove" xreflabel="IGuestSession::fsObjRemove"/> method that works
    4098                  on any type of file system object except directories (fileRemove also worked on any type of object,
    4099                  though that was not the intent of the method.)</para>
    4100             </listitem>
    4101             <listitem>
    4102               <para>Renamed IGuestSession::copyTo to <xref linkend="IGuestSession__fileCopyToGuest"
    4103                  xreflabel="IGuestSession::fileCopyToGuest"/>.</para>
    4104             </listitem>
    4105             <listitem>
    4106               <para>Renamed IGuestSession::copyFrom to <xref linkend="IGuestSession__fileCopyFromGuest"
    4107                  xreflabel="IGuestSession::fileCopyFromGuest"/>.</para>
    4108             </listitem>
    4109             <listitem>
    4110               <para>Renamed the CopyFileFlag enum to <xref linkend="FileCopyFlag" xreflabel="FileCopyFlag"/>.</para>
    4111             </listitem>
    4112             <listitem>
    4113               <para>Renamed the IGuestSession::environment attribute to <xref linkend="IGuestSession__environmentChanges"
    4114                 xreflabel="IGuestSession::environmentChanges"/> to better reflect what it does.</para>
    4115             </listitem>
    4116             <listitem>
    4117               <para>Changed the <xref linkend="IProcess__environment" xreflabel="IGuestProcess::environment"/> to
    4118                a stub returning E_NOTIMPL since it wasn't doing what was advertised (returned changes, not the
    4119                actual environment).</para>
    4120             </listitem>
    4121             <listitem>
    4122               <para>Renamed IGuestSession::environmentSet to <xref linkend="IGuestSession__environmentScheduleSet"
    4123                 xreflabel="IGuestSession::environmentScheduleSet"/> to better reflect what it does.</para>
    4124             </listitem>
    4125             <listitem>
    4126               <para>Renamed IGuestSession::environmentUnset to <xref linkend="IGuestSession__environmentScheduleUnset"
    4127                 xreflabel="IGuestSession::environmentScheduleUnset"/> to better reflect what it does.</para>
    4128             </listitem>
    4129             <listitem>
    4130               <para>Removed IGuestSession::environmentGet it was only getting changes while giving the impression it was
    4131                 actual environment variables, and it did not represent scheduled unset operations.</para>
    4132             </listitem>
    4133             <listitem>
    4134               <para>Removed IGuestSession::environmentClear as it duplicates assigning an empty array to the
    4135                 <xref linkend="IGuestSession__environmentChanges" xreflabel="IGuestSession::environmentChanges"/> (formerly
    4136                 known as IGuestSession::environment).</para>
    4137             </listitem>
    4138             <listitem>
    4139               <para>Changed the <xref linkend="IGuestSession__processCreate" xreflabel="IGuestSession::processCreate"/> and
    4140               <xref linkend="IGuestSession__processCreateEx" xreflabel="IGuestSession::processCreateEx"/> methods to accept
    4141               arguments starting with argument zero (argv[0]) instead of argument one (argv[1]). (Not yet implemented on the
    4142               guest additions side, so argv[0] will probably be ignored for a short while.)</para>
    4143             </listitem>
    4144 
    4145             <listitem>
    4146               <para>Added a followSymlink parameter to the following methods:<itemizedlist>
    4147                 <listitem><para><xref linkend="IGuestSession__directoryExists"
    4148                   xreflabel="IGuestSession::directoryExists"/></para></listitem>
    4149                 <listitem><para><xref linkend="IGuestSession__fileExists"
    4150                   xreflabel="IGuestSession::fileExists"/></para></listitem>
    4151                 <listitem><para><xref linkend="IGuestSession__fileQuerySize"
    4152                   xreflabel="IGuestSession::fileQuerySize"/></para></listitem>
     4171              <para>Renamed IGuestSession::copyTo to
     4172              <link linkend="IGuestSession__fileCopyToGuest">IGuestSession::fileCopyToGuest</link>.</para>
     4173            </listitem>
     4174            <listitem>
     4175              <para>Renamed IGuestSession::copyFrom to
     4176              <link linkend="IGuestSession__fileCopyFromGuest">IGuestSession::fileCopyFromGuest</link>.</para>
     4177            </listitem>
     4178            <listitem>
     4179              <para>Renamed the CopyFileFlag enum to
     4180              <link linkend="FileCopyFlag">FileCopyFlag</link>.</para>
     4181            </listitem>
     4182            <listitem>
     4183              <para>Renamed the IGuestSession::environment attribute to
     4184              <link linkend="IGuestSession__environmentChanges">IGuestSession::environmentChanges</link>
     4185              to better reflect what it does.</para>
     4186            </listitem>
     4187            <listitem>
     4188              <para>Changed the
     4189              <link linkend="IProcess__environment">IGuestProcess::environment</link>
     4190              to a stub returning E_NOTIMPL since it wasn't doing what was
     4191              advertised (returned changes, not the actual environment).</para>
     4192            </listitem>
     4193            <listitem>
     4194              <para>Renamed IGuestSession::environmentSet to
     4195              <link linkend="IGuestSession__environmentScheduleSet">IGuestSession::environmentScheduleSet</link>
     4196              to better reflect what it does.</para>
     4197            </listitem>
     4198            <listitem>
     4199              <para>Renamed IGuestSession::environmentUnset to
     4200              <link linkend="IGuestSession__environmentScheduleUnset">IGuestSession::environmentScheduleUnset</link>
     4201              to better reflect what it does.</para>
     4202            </listitem>
     4203            <listitem>
     4204              <para>Removed IGuestSession::environmentGet it was only getting
     4205              changes while giving the impression it was actual environment
     4206              variables, and it did not represent scheduled unset
     4207              operations.</para>
     4208            </listitem>
     4209            <listitem>
     4210              <para>Removed IGuestSession::environmentClear as it duplicates
     4211              assigning an empty array to the
     4212              <link linkend="IGuestSession__environmentChanges">IGuestSession::environmentChanges</link>
     4213              (formerly known as IGuestSession::environment).</para>
     4214            </listitem>
     4215            <listitem>
     4216              <para>Changed the
     4217              <link linkend="IGuestSession__processCreate">IGuestSession::processCreate</link>
     4218              and
     4219              <link linkend="IGuestSession__processCreateEx">IGuestSession::processCreateEx</link>
     4220              methods to accept arguments starting with argument zero (argv[0])
     4221              instead of argument one (argv[1]). (Not yet implemented on the
     4222              guest additions side, so argv[0] will probably be ignored for a
     4223              short while.)</para>
     4224            </listitem>
     4225
     4226            <listitem>
     4227              <para>Added a followSymlink parameter to the following methods:
     4228              <itemizedlist>
     4229                <listitem><para><link linkend="IGuestSession__directoryExists">IGuestSession::directoryExists</link></para></listitem>
     4230                <listitem><para><link linkend="IGuestSession__fileExists">IGuestSession::fileExists</link></para></listitem>
     4231                <listitem><para><link linkend="IGuestSession__fileQuerySize">IGuestSession::fileQuerySize</link></para></listitem>
    41534232              </itemizedlist></para>
    41544233            </listitem>
    41554234            <listitem>
    4156               <para>The parameters to the <xref linkend="IGuestSession__fileOpen" xreflabel="IGuestSession::fileOpen"/>
    4157                 and <xref linkend="IGuestSession__fileOpenEx" xreflabel="IGuestSession::fileOpenEx"/> methods were
    4158                 altered:<itemizedlist>
    4159                 <listitem><para>The openMode string parameter was replaced by the enum
    4160                   <xref linkend="FileAccessMode" xreflabel="FileAccessMode"/> and renamed to accessMode.</para></listitem>
    4161                 <listitem><para>The disposition string parameter was replaced by the enum
    4162                   <xref linkend="FileOpenAction" xreflabel="FileOpenAction"/> and renamed to openAction.</para></listitem>
    4163                 <listitem><para>The unimplemented sharingMode string parameter was replaced by the enum
    4164                   <xref linkend="FileSharingMode" xreflabel="FileSharingMode"/> (fileOpenEx only).</para></listitem>
    4165                 <listitem><para>Added a flags parameter taking a list of <xref linkend="FileOpenExFlags"
    4166                   xreflabel="FileOpenExFlags"/> values (fileOpenEx only).</para></listitem>
    4167                 <listitem><para>Removed the offset parameter (fileOpenEx only).</para></listitem>
     4235              <para>The parameters to the
     4236                <link linkend="IGuestSession__fileOpen">IGuestSession::fileOpen</link>
     4237                and
     4238                <link linkend="IGuestSession__fileOpenEx">IGuestSession::fileOpenEx</link>
     4239                methods were altered:<itemizedlist>
     4240                <listitem><para>The openMode string parameter was replaced by
     4241                  the enum
     4242                  <link linkend="FileAccessMode">FileAccessMode</link>
     4243                  and renamed to accessMode.</para></listitem>
     4244                <listitem><para>The disposition string parameter was replaced
     4245                  by the enum
     4246                  <link linkend="FileOpenAction">FileOpenAction</link>
     4247                  and renamed to openAction.</para></listitem>
     4248                <listitem><para>The unimplemented sharingMode string parameter
     4249                  was replaced by the enum
     4250                  <link linkend="FileSharingMode">FileSharingMode</link>
     4251                  (fileOpenEx only).</para></listitem>
     4252                <listitem><para>Added a flags parameter taking a list of
     4253                <link linkend="FileOpenExFlags">FileOpenExFlags</link> values
     4254                (fileOpenEx only).</para></listitem>
     4255                <listitem><para>Removed the offset parameter (fileOpenEx
     4256                only).</para></listitem>
    41684257              </itemizedlist></para>
    41694258            </listitem>
    41704259
    41714260            <listitem>
    4172               <para><xref linkend="IFile__seek" xreflabel="IGuestFile::seek"/> now returns the new offset.</para>
    4173             </listitem>
    4174             <listitem>
    4175               <para>Renamed the FileSeekType enum used by <xref linkend="IFile__seek" xreflabel="IGuestFile::seek"/>
    4176                 to <xref linkend="FileSeekOrigin" xreflabel="FileSeekOrigin"/> and added the missing End value
    4177                 and renaming the Set to Begin.</para>
    4178             </listitem>
    4179             <listitem>
    4180               <para>Extended the unimplemented <xref linkend="IFile__setACL" xreflabel="IGuestFile::setACL"/>
    4181                 method with a UNIX-style mode parameter as an alternative to the ACL.</para>
    4182             </listitem>
    4183             <listitem>
    4184               <para>Renamed the IFile::openMode attribute to <xref linkend="IFile__accessMode" xreflabel="IFile::accessMode"/>
    4185                 and change the type from string to <xref linkend="FileAccessMode" xreflabel="FileAccessMode"/> to reflect
     4261              <para><link linkend="IFile__seek">IGuestFile::seek</link> now
     4262              returns the new offset.</para>
     4263            </listitem>
     4264            <listitem>
     4265              <para>Renamed the FileSeekType enum used by
     4266              <link linkend="IFile__seek">IGuestFile::seek</link>
     4267                to <link linkend="FileSeekOrigin">FileSeekOrigin</link> and
     4268                added the missing End value and renaming the Set to
     4269                Begin.</para>
     4270            </listitem>
     4271            <listitem>
     4272              <para>Extended the unimplemented
     4273                <link linkend="IFile__setACL">IGuestFile::setACL</link>
     4274                method with a UNIX-style mode parameter as an alternative to
     4275                the ACL.</para>
     4276            </listitem>
     4277            <listitem>
     4278              <para>Renamed the IFile::openMode attribute to
     4279                <link linkend="IFile__accessMode">IFile::accessMode</link>
     4280                and change the type from string to
     4281                <link linkend="FileAccessMode">FileAccessMode</link> to reflect
    41864282                the changes to the fileOpen methods.</para>
    41874283            </listitem>
    41884284            <listitem>
    4189               <para>Renamed the IGuestFile::disposition attribute to <xref linkend="IFile__openAction"
    4190                 xreflabel="IFile::openAction"/> and change the type from string to <xref linkend="FileOpenAction"
    4191                 xreflabel="FileOpenAction"/> to reflect the changes to the fileOpen methods.</para>
     4285              <para>Renamed the IGuestFile::disposition attribute to
     4286              <link linkend="IFile__openAction">IFile::openAction</link> and
     4287              change the type from string to
     4288              <link linkend="FileOpenAction">FileOpenAction</link> to reflect
     4289              the changes to the fileOpen methods.</para>
    41924290            </listitem>
    41934291
    41944292            <!-- Non-incompatible things worth mentioning (stubbed methods/attrs aren't worth it). -->
    41954293            <listitem>
    4196               <para>Added <xref linkend="IGuestSession__pathStyle" xreflabel="IGuestSession::pathStyle"/> attribute.</para>
    4197             </listitem>
    4198             <listitem>
    4199               <para>Added <xref linkend="IGuestSession__fsObjExists" xreflabel="IGuestSession::fsObjExists"/> attribute.</para>
     4294              <para>Added
     4295              <link linkend="IGuestSession__pathStyle">IGuestSession::pathStyle</link>
     4296              attribute.</para>
     4297            </listitem>
     4298            <listitem>
     4299              <para>Added
     4300              <link linkend="IGuestSession__fsObjExists">IGuestSession::fsObjExists</link>
     4301              attribute.</para>
    42004302            </listitem>
    42014303
    … …  
    42054307
    42064308        <listitem><para>
    4207           IConsole::GetDeviceActivity() returns information about multiple devices.
     4309          IConsole::GetDeviceActivity() returns information about multiple
     4310          devices.
    42084311        </para></listitem>
    42094312
    42104313        <listitem><para>
    42114314          IMachine::ReadSavedThumbnailToArray() has a new parameter
    4212           <computeroutput>bitmapFormat</computeroutput>. As a consequence of this,
    4213           IMachine::ReadSavedThumbnailPNGToArray() has been removed.
     4315          <computeroutput>bitmapFormat</computeroutput>. As a consequence of
     4316          this, IMachine::ReadSavedThumbnailPNGToArray() has been removed.
    42144317        </para></listitem>
    42154318
    … …  
    42314334
    42324335        <listitem>
    4233           <para>The method <xref linkend="IWebsessionManager__getSessionObject"
    4234           xreflabel="IWebsessionManager::getSessionObject()" /> now returns
    4235           a new <xref linkend="ISession" xreflabel="ISession" /> instance for
    4236           every invocation. This puts the behavior in line with other binding
    4237           styles, which never forced the equivalent of establishing another
    4238           connection and logging in again to get another instance.</para>
     4336          <para>The method
     4337          <link linkend="IWebsessionManager__getSessionObject">IWebsessionManager::getSessionObject()</link>
     4338          now returns a new <link linkend="ISession">ISession</link> instance
     4339          for every invocation. This puts the behavior in line with other
     4340          binding styles, which never forced the equivalent of establishing
     4341          another connection and logging in again to get another
     4342          instance.</para>
    42394343        </listitem>
    42404344      </itemizedlist>
    … …  
    42474351        <listitem>
    42484352          <para>The explicit medium locking methods
    4249             <xref linkend="IMedium__lockRead" xreflabel="IMedium::lockRead()" />
    4250             and <xref linkend="IMedium__lockWrite" xreflabel="IMedium::lockWrite()" />
     4353            <link linkend="IMedium__lockRead">IMedium::lockRead()</link>
     4354            and <link linkend="IMedium__lockWrite">IMedium::lockWrite()</link>
    42514355            have been redesigned. They return a lock token object reference
    4252             now, and calling the <xref linkend="IToken__abandon"
    4253               xreflabel="IToken::abandon()" /> method (or letting the reference
    4254             count to this object drop to 0) will unlock it. This eliminates
    4255             the rather common problem that an API client crash left behind
    4256             locks, and also improves the safety (API clients can't release
    4257             locks they didn't obtain).</para>
    4258         </listitem>
    4259 
    4260         <listitem>
    4261           <para>The parameter list of <xref linkend="IAppliance__write"
    4262           xreflabel="IAppliance::write()" /> has been changed slightly, to
    4263           allow multiple flags to be passed.</para>
     4356            now, and calling the
     4357            <link linkend="IToken__abandon">IToken::abandon()</link> method (or
     4358            letting the reference count to this object drop to 0) will unlock
     4359            it. This eliminates the rather common problem that an API client
     4360            crash left behind locks, and also improves the safety (API clients
     4361            can't release locks they didn't obtain).</para>
     4362        </listitem>
     4363
     4364        <listitem>
     4365          <para>The parameter list of
     4366          <link linkend="IAppliance__write">IAppliance::write()</link>
     4367          has been changed slightly, to allow multiple flags to be
     4368          passed.</para>
    42644369        </listitem>
    42654370
    42664371        <listitem>
    42674372          <para><computeroutput>IMachine::delete</computeroutput>
    4268           has been renamed to <xref linkend="IMachine__deleteConfig"
    4269           xreflabel="IMachine::deleteConfig()" />, to improve API client
    4270           binding compatibility.</para>
     4373          has been renamed to
     4374          <link linkend="IMachine__deleteConfig">IMachine::deleteConfig()</link>,
     4375          to improve API client binding compatibility.</para>
    42714376        </listitem>
    42724377
    42734378        <listitem>
    42744379          <para><computeroutput>IMachine::export</computeroutput>
    4275           has been renamed to <xref linkend="IMachine__exportTo"
    4276           xreflabel="IMachine::exportTo()" />, to improve API client binding
    4277           compatibility.</para>
    4278         </listitem>
    4279 
    4280         <listitem>
    4281           <para>For <xref linkend="IMachine__launchVMProcess"
    4282           xreflabel="IMachine::launchVMProcess()"/> the meaning of the
    4283           <computeroutput>type</computeroutput> parameter has changed slightly.
    4284           Empty string now means that the per-VM or global default frontend
    4285           is launched. Most callers of this method should use the empty string
    4286           now, unless they really want to override the default and launch a
    4287           particular frontend.</para>
     4380          has been renamed to
     4381          <link linkend="IMachine__exportTo">IMachine::exportTo()</link>,
     4382          to improve API client binding compatibility.</para>
     4383        </listitem>
     4384
     4385        <listitem>
     4386          <para>For
     4387          <link linkend="IMachine__launchVMProcess">IMachine::launchVMProcess()</link>
     4388          the meaning of the <computeroutput>type</computeroutput> parameter
     4389          has changed slightly. Empty string now means that the per-VM or
     4390          global default frontend is launched. Most callers of this method
     4391          should use the empty string now, unless they really want to override
     4392          the default and launch a particular frontend.</para>
    42884393        </listitem>
    42894394
    … …  
    42934398            <listitem>
    42944399              <para>The type of attribute
    4295               <xref linkend="IMedium__variant" xreflabel="IMedium::variant()"/>
     4400              <link linkend="IMedium__variant">IMedium::variant()</link>
    42964401              changed from <computeroutput>unsigned long</computeroutput>
    42974402              to <computeroutput>safe-array MediumVariant</computeroutput>.
    4298               It is an array of flags instead of a set of flags which were stored inside one variable.
     4403              It is an array of flags instead of a set of flags which were
     4404              stored inside one variable.
    42994405              </para>
    43004406            </listitem>
    43014407
    43024408            <listitem>
    4303               <para>The parameter list for <xref
    4304               linkend="IMedium__cloneTo"
    4305               xreflabel="IMedium::cloneTo()" /> was modified.</para>
    4306               The type of parameter variant was changed from unsigned long to safe-array MediumVariant.
    4307             </listitem>
    4308 
    4309             <listitem>
    4310               <para>The parameter list for <xref
    4311               linkend="IMedium__createBaseStorage"
    4312               xreflabel="IMedium::createBaseStorage()" /> was modified.</para>
    4313               The type of parameter variant was changed from unsigned long to safe-array MediumVariant.
    4314             </listitem>
    4315 
    4316             <listitem>
    4317               <para>The parameter list for <xref
    4318               linkend="IMedium__createDiffStorage"
    4319               xreflabel="IMedium::createDiffStorage()" /> was modified.</para>
    4320               The type of parameter variant was changed from unsigned long to safe-array MediumVariant.
    4321             </listitem>
    4322 
    4323             <listitem>
    4324               <para>The parameter list for <xref
    4325               linkend="IMedium__cloneToBase"
    4326               xreflabel="IMedium::cloneToBase()" /> was modified.</para>
    4327               The type of parameter variant was changed from unsigned long to safe-array MediumVariant.
     4409              <para>The parameter list for
     4410              <link linkend="IMedium__cloneTo">IMedium::cloneTo()</link>
     4411              was modified. The type of parameter variant was changed from
     4412              unsigned long to safe-array MediumVariant.
     4413              </para>
     4414            </listitem>
     4415
     4416            <listitem>
     4417              <para>The parameter list for
     4418              <link linkend="IMedium__createBaseStorage">IMedium::createBaseStorage()</link>
     4419              was modified. The type of parameter variant was changed from
     4420              unsigned long to safe-array MediumVariant.
     4421              </para>
     4422            </listitem>
     4423
     4424            <listitem>
     4425              <para>The parameter list for
     4426              <link linkend="IMedium__createDiffStorage">IMedium::createDiffStorage()</link>
     4427              was modified. The type of parameter variant was changed from
     4428              unsigned long to safe-array MediumVariant.
     4429              </para>
     4430            </listitem>
     4431
     4432            <listitem>
     4433              <para>The parameter list for
     4434              <link linkend="IMedium__cloneToBase">IMedium::cloneToBase()</link>
     4435              was modified. The type of parameter variant was changed from
     4436              unsigned long to safe-array MediumVariant.
     4437              </para>
    43284438            </listitem>
    43294439          </itemizedlist></para>
    … …  
    43324442        <listitem>
    43334443          <para>The type of attribute
    4334           <xref linkend="IMediumFormat__capabilities"
    4335           xreflabel="IMediumFormat::capabilities()"/>
    4336           changed from <computeroutput>unsigned long</computeroutput>
    4337           to <computeroutput>safe-array MediumFormatCapabilities</computeroutput>.
    4338           It is an array of flags instead of a set of flags which were stored inside one variable.
     4444          <link linkend="IMediumFormat__capabilities">IMediumFormat::capabilities()</link>
     4445          changed from <computeroutput>unsigned long</computeroutput> to
     4446          <computeroutput>safe-array MediumFormatCapabilities</computeroutput>.
     4447          It is an array of flags instead of a set of flags which were stored
     4448          inside one variable.
    43394449          </para>
    43404450        </listitem>
    43414451
    43424452        <listitem>
    4343           <para>The attribute <xref linkend="IMedium__logicalSize"
    4344           xreflabel="IMedium::logicalSize()" /> now returns the logical
    4345           size of exactly this medium object (whether it is a base or diff
    4346           image). The old behavior was no longer acceptable, as each image
    4347           can have a different capacity.</para>
    4348         </listitem>
    4349 
    4350         <listitem>
    4351           <para>Guest control APIs - such as <xref linkend="IGuest"
    4352             xreflabel="IGuest" />, <xref linkend="IGuestSession"
    4353             xreflabel="IGuestSession" />, <xref linkend="IGuestProcess"
    4354             xreflabel="IGuestProcess" /> and so on - now emit own events to provide
    4355             clients much finer control and the ability to write own frontends for
    4356             guest operations. The event <xref linkend="IGuestSessionEvent"
    4357             xreflabel="IGuestSessionEvent" /> acts as an abstract base class
    4358             for all guest control events. Certain guest events contain a
    4359             <xref linkend="IVirtualBoxErrorInfo" xreflabel="IVirtualBoxErrorInfo" /> member
    4360             to provide more information in case of an error happened on the
    4361             guest side.</para>
    4362         </listitem>
    4363 
    4364         <listitem>
    4365           <para>Guest control sessions on the guest started by <xref
    4366             linkend="IGuest__createSession" xreflabel="IGuest::createSession()" />
    4367             now are dedicated guest processes to provide more safety and performance
    4368             for certain operations. Also, the <xref linkend="IGuest__createSession"
    4369             xreflabel="IGuest::createSession()" /> call does not wait for the
    4370             guest session being created anymore due to the dedicated guest session
    4371             processes just mentioned. This also will enable webservice clients to
    4372             handle guest session creation more gracefully. To wait for a guest
    4373             session being started, use the newly added attribute <xref
    4374             linkend="IGuestSession__status" xreflabel="IGuestSession::status()" />
     4453          <para>The attribute
     4454          <link linkend="IMedium__logicalSize">IMedium::logicalSize()</link>
     4455          now returns the logical size of exactly this medium object (whether
     4456          it is a base or diff image). The old behavior was no longer
     4457          acceptable, as each image can have a different capacity.</para>
     4458        </listitem>
     4459
     4460        <listitem>
     4461          <para>Guest control APIs - such as
     4462          <link linkend="IGuest">IGuest</link>,
     4463          <link linkend="IGuestSession">IGuestSession</link>,
     4464          <link linkend="IGuestProcess">IGuestProcess</link> and so on - now
     4465          emit own events to provide clients much finer control and the ability
     4466          to write own frontends for guest operations. The event
     4467          <link linkend="IGuestSessionEvent">IGuestSessionEvent</link> acts as
     4468          an abstract base class for all guest control events. Certain guest
     4469          events contain a
     4470          <link linkend="IVirtualBoxErrorInfo">IVirtualBoxErrorInfo</link>
     4471          member to provide more information in case of an error happened on
     4472          the guest side.</para>
     4473        </listitem>
     4474
     4475        <listitem>
     4476          <para>Guest control sessions on the guest started by
     4477            <link linkend="IGuest__createSession">IGuest::createSession()</link>
     4478            now are dedicated guest processes to provide more safety and
     4479            performance for certain operations. Also, the
     4480            <link linkend="IGuest__createSession">IGuest::createSession()</link>
     4481            call does not wait for the guest session being created anymore due
     4482            to the dedicated guest session processes just mentioned. This also
     4483            will enable webservice clients to handle guest session creation
     4484            more gracefully. To wait for a guest session being started, use the
     4485            newly added attribute
     4486            <link linkend="IGuestSession__status">IGuestSession::status()</link>
    43754487            to query the current guest session status.</para>
    43764488        </listitem>
    43774489
    43784490        <listitem>
    4379           <para>The <xref linkend="IGuestFile" xreflabel="IGuestFile" />
     4491          <para>The <link linkend="IGuestFile">IGuestFile</link>
    43804492            APIs are now implemented to provide native guest file access from
    43814493            the host.</para>
    … …  
    43834495
    43844496        <listitem>
    4385           <para>The parameter list for <xref
    4386           linkend="IGuest__updateGuestAdditions"
    4387           xreflabel="IMedium::updateGuestAdditions()" /> was modified.</para>
    4388           It now supports specifying optional command line arguments for the
    4389           Guest Additions installer performing the actual update on the guest.
    4390         </listitem>
    4391 
    4392         <listitem>
    4393           <para>A new event <xref linkend="IGuestUserStateChangedEvent"
    4394           xreflabel="IGuestUserStateChangedEvent" /> was introduced to provide
    4395           guest user status updates to the host via event listeners. To use this
    4396           event there needs to be at least the 4.3 Guest Additions installed on
    4397           the guest. At the moment only the states "Idle" and "InUse" of the
    4398           <xref linkend="GuestUserState"
    4399           xreflabel="GuestUserState" /> enumeration are supported on
    4400           Windows guests, starting at Windows 2000 SP2.</para>
     4497          <para>The parameter list for
     4498          <link linkend="IGuest__updateGuestAdditions">IMedium::updateGuestAdditions()</link>
     4499          was modified. It now supports specifying optional command line
     4500          arguments for the Guest Additions installer performing the actual
     4501          update on the guest.
     4502          </para>
     4503        </listitem>
     4504
     4505        <listitem>
     4506          <para>A new event
     4507          <link linkend="IGuestUserStateChangedEvent">IGuestUserStateChangedEvent</link>
     4508          was introduced to provide guest user status updates to the host via
     4509          event listeners. To use this event there needs to be at least the 4.3
     4510          Guest Additions installed on the guest. At the moment only the states
     4511          "Idle" and "InUse" of the
     4512          <link linkend="GuestUserState">GuestUserState</link> enumeration arei
     4513          supported on Windows guests, starting at Windows 2000 SP2.</para>
    44014514        </listitem>
    44024515
    44034516        <listitem>
    44044517          <para>
    4405             The attribute <xref linkend="IGuestSession__protocolVersion"
    4406             xreflabel="IGuestSession::protocolVersion"/> was added to provide a
    4407             convenient way to lookup the guest session's protocol version it
    4408             uses to communicate with the installed Guest Additions on the guest.
    4409             Older Guest Additions will set the protocol version to 1, whereas
    4410             Guest Additions 4.3 will set the protocol version to 2. This might
    4411             change in the future as new features arise.</para>
     4518            The attribute
     4519            <link linkend="IGuestSession__protocolVersion">IGuestSession::protocolVersion</link>
     4520            was added to provide a convenient way to lookup the guest session's
     4521            protocol version it uses to communicate with the installed Guest
     4522            Additions on the guest. Older Guest Additions will set the protocol
     4523            version to 1, whereas Guest Additions 4.3 will set the protocol
     4524            version to 2. This might change in the future as new features
     4525            arise.</para>
    44124526        </listitem>
    44134527
    … …  
    44194533        <listitem>
    44204534          <para>
    4421             The <xref linkend="IUSBController" xreflabel="IUSBController"/>
    4422             class is not a singleton of <xref linkend="IMachine" xreflabel="IMachine"/>
    4423             anymore but <xref linkend="IMachine" xreflabel="IMachine"/> contains
    4424             a list of USB controllers present in the VM. The USB device filter
    4425             handling was moved to <xref linkend="IUSBDeviceFilters" xreflabel="IUSBDeviceFilters"/>.
     4535            The <link linkend="IUSBController">IUSBController</link>
     4536            class is not a singleton of
     4537            <link linkend="IMachine">IMachine</link> anymore but
     4538            <link linkend="IMachine">IMachine</link> contains a list of USB
     4539            controllers present in the VM. The USB device filter handling was
     4540            moved to
     4541            <link linkend="IUSBDeviceFilters">IUSBDeviceFilters</link>.
    44264542          </para>
    44274543        </listitem>
    … …  
    44364552          <para>Guest control APIs for executing guest processes, working with
    44374553          guest files or directories have been moved to the newly introduced
    4438           <xref linkend="IGuestSession" xreflabel="IGuestSession" /> interface which
    4439           can be created by calling <xref linkend="IGuest__createSession"
    4440           xreflabel="IGuest::createSession()" />.</para>
     4554          <link linkend="IGuestSession">IGuestSession</link> interface which
     4555          can be created by calling
     4556          <link linkend="IGuest__createSession">IGuest::createSession()</link>.</para>
    44414557
    44424558          <para>A guest session will act as a
    … …  
    44484564          <para>Instead of working with process or directory handles before
    44494565          version 4.2, there now are the dedicated interfaces
    4450           <xref linkend="IGuestProcess" xreflabel="IGuestProcess" />,
    4451           <xref linkend="IGuestDirectory" xreflabel="IGuestDirectory" /> and
    4452           <xref linkend="IGuestFile" xreflabel="IGuestFile" />. To retrieve more
     4566          <link linkend="IGuestProcess">IGuestProcess</link>,
     4567          <link linkend="IGuestDirectory">IGuestDirectory</link> and
     4568          <link linkend="IGuestFile">IGuestFile</link>. To retrieve more
    44534569          information of a file system object the new interface
    4454           <xref linkend="IGuestFsObjInfo" xreflabel="IGuestFsObjInfo" /> has been
     4570          <link linkend="IGuestFsObjInfo">IGuestFsObjInfo</link> has been
    44554571          introduced.</para>
    44564572
    … …  
    44584574          compatible so that it can be used with older installed Guest
    44594575          Additions. However, to use upcoming features like process termination
    4460           or waiting for input / output new Guest Additions must be installed when
    4461           these features got implemented.</para>
     4576          or waiting for input / output new Guest Additions must be installed
     4577          when these features got implemented.</para>
    44624578
    44634579          <para>The following limitations apply:
    44644580            <itemizedlist>
    4465               <listitem><para>The <xref linkend="IGuestFile" xreflabel="IGuestFile" />
     4581              <listitem><para>The <link linkend="IGuestFile">IGuestFile</link>
    44664582                interface is not fully implemented yet.</para>
    44674583              </listitem>
    44684584              <listitem><para>The symbolic link APIs
    4469                 <xref linkend="IGuestSession__symlinkCreate"
    4470                 xreflabel="IGuestSession::symlinkCreate()" />,
    4471                 <xref linkend="IGuestSession__symlinkExists"
    4472                 xreflabel="IGuestSession::symlinkExists()" />,
    4473                 <xref linkend="IGuestSession__symlinkRead"
    4474                 xreflabel="IGuestSession::symlinkRead()" />,
     4585                <link linkend="IGuestSession__symlinkCreate">IGuestSession::symlinkCreate()</link>,
     4586                <link linkend="IGuestSession__symlinkExists">IGuestSession::symlinkExists()</link>,
     4587                <link linkend="IGuestSession__symlinkRead">IGuestSession::symlinkRead()</link>,
    44754588                IGuestSession::symlinkRemoveDirectory() and
    44764589                IGuestSession::symlinkRemoveFile() are not
    … …  
    44784591              </listitem>
    44794592              <listitem><para>The directory APIs
    4480                 <xref linkend="IGuestSession__directoryRemove"
    4481                 xreflabel="IGuestSession::directoryRemove()" />,
    4482                 <xref linkend="IGuestSession__directoryRemoveRecursive"
    4483                 xreflabel="IGuestSession::directoryRemoveRecursive()" />,
     4593                <link linkend="IGuestSession__directoryRemove">IGuestSession::directoryRemove()</link>,
     4594                <link linkend="IGuestSession__directoryRemoveRecursive">IGuestSession::directoryRemoveRecursive()</link>,
    44844595                IGuestSession::directoryRename() and
    44854596                IGuestSession::directorySetACL() are not
    … …  
    44874598              </listitem>
    44884599              <listitem><para>The temporary file creation API
    4489                 <xref linkend="IGuestSession__fileCreateTemp"
    4490                 xreflabel="IGuestSession::fileCreateTemp()" /> is not
     4600                <link linkend="IGuestSession__fileCreateTemp">IGuestSession::fileCreateTemp()</link>
     4601                is not implemented yet.</para>
     4602              </listitem>
     4603              <listitem><para>Guest process termination via
     4604                <link linkend="IProcess__terminate">IProcess::terminate()</link>
     4605                is not implemented yet.</para>
     4606              </listitem>
     4607              <listitem><para>Waiting for guest process output via
     4608                <link linkend="ProcessWaitForFlag__StdOut">ProcessWaitForFlag::StdOut</link>
     4609                and
     4610                <link linkend="ProcessWaitForFlag__StdErr">ProcessWaitForFlag::StdErr</link>
     4611                is not implemented yet.</para>
     4612                <para>To wait for process output,
     4613                <link linkend="IProcess__read">IProcess::read()</link> with
     4614                appropriate flags still can be used to periodically check for
     4615                new output data to arrive. Note that
     4616                <link linkend="ProcessCreateFlag__WaitForStdOut">ProcessCreateFlag::WaitForStdOut</link>
     4617                and / or
     4618                <link linkend="ProcessCreateFlag__WaitForStdErr">ProcessCreateFlag::WaitForStdErr</link>
     4619                need to be specified when creating a guest process via
     4620                <link linkend="IGuestSession__processCreate">IGuestSession::processCreate()</link>
     4621                or
     4622                <link linkend="IGuestSession__processCreateEx">IGuestSession::processCreateEx()</link>.</para>
     4623              </listitem>
     4624              <listitem>
     4625                <para>ACL (Access Control List) handling in general is not
    44914626                implemented yet.</para>
    4492               </listitem>
    4493               <listitem><para>Guest process termination via
    4494                 <xref linkend="IProcess__terminate"
    4495                 xreflabel="IProcess::terminate()" /> is not
    4496                 implemented yet.</para>
    4497               </listitem>
    4498               <listitem><para>Waiting for guest process output via
    4499                 <xref linkend="ProcessWaitForFlag__StdOut" xreflabel="ProcessWaitForFlag::StdOut" />
    4500                 and <xref linkend="ProcessWaitForFlag__StdErr" xreflabel="ProcessWaitForFlag::StdErr" />
    4501                 is not implemented yet.</para><para>To wait for process output, <xref linkend="IProcess__read"
    4502                 xreflabel="IProcess::read()" /> with appropriate flags still can be used to periodically
    4503                 check for new output data to arrive. Note that <xref linkend="ProcessCreateFlag__WaitForStdOut"
    4504                 xreflabel="ProcessCreateFlag::WaitForStdOut" /> and / or
    4505                 <xref linkend="ProcessCreateFlag__WaitForStdErr" xreflabel="ProcessCreateFlag::WaitForStdErr" />
    4506                 need to be specified when creating a guest process via <xref linkend="IGuestSession__processCreate"
    4507                 xreflabel="IGuestSession::processCreate()" /> or <xref linkend="IGuestSession__processCreateEx"
    4508                 xreflabel="IGuestSession::processCreateEx()" />.</para>
    4509               </listitem>
    4510               <listitem>
    4511                 <para>ACL (Access Control List) handling in general is not implemented yet.</para>
    45124627              </listitem>
    45134628            </itemizedlist>
    … …  
    45164631
    45174632        <listitem>
    4518           <para>The <xref linkend="LockType" xreflabel="LockType" />
    4519           enumeration now has an additional value <computeroutput>VM</computeroutput>
    4520           which tells <xref linkend="IMachine__lockMachine"
    4521           xreflabel="IMachine::lockMachine()" /> to create a full-blown
    4522           object structure for running a VM. This was the previous behavior
    4523           with <computeroutput>Write</computeroutput>, which now only creates
    4524           the minimal object structure to save time and resources (at the
    4525           moment the Console object is still created, but all sub-objects
    4526           such as Display, Keyboard, Mouse, Guest are not.</para>
     4633          <para>The <link linkend="LockType">LockType</link>
     4634          enumeration now has an additional value
     4635          <computeroutput>VM</computeroutput> which tells
     4636          <link linkend="IMachine__lockMachine">IMachine::lockMachine()</link>
     4637          to create a full-blown object structure for running a VM. This was
     4638          the previous behavior with <computeroutput>Write</computeroutput>,
     4639          which now only creates the minimal object structure to save time and
     4640          resources (at the moment the Console object is still created, but all
     4641          sub-objects such as Display, Keyboard, Mouse, Guest are not.</para>
    45274642        </listitem>
    45284643
    … …  
    45304645          <para>Machines can be put in groups (actually an array of groups).
    45314646          The primary group affects the default placement of files belonging
    4532           to a VM. <xref linkend="IVirtualBox__createMachine"
    4533           xreflabel="IVirtualBox::createMachine()"/> and
    4534           <xref linkend="IVirtualBox__composeMachineFilename"
    4535           xreflabel="IVirtualBox::composeMachineFilename()"/> have been
    4536           adjusted accordingly, the former taking an array of groups as an
    4537           additional parameter and the latter taking a group as an additional
    4538           parameter. The create option handling has been changed for those two
    4539           methods, too.</para>
     4647          to a VM.
     4648          <link linkend="IVirtualBox__createMachine">IVirtualBox::createMachine()</link>
     4649          and
     4650          <link linkend="IVirtualBox__composeMachineFilename">IVirtualBox::composeMachineFilename()</link>
     4651          have been adjusted accordingly, the former taking an array of groups
     4652          as an additional parameter and the latter taking a group as an
     4653          additional parameter. The create option handling has been changed for
     4654          those two methods, too.</para>
    45404655        </listitem>
    45414656
    45424657        <listitem>
    45434658          <para>The method IVirtualBox::findMedium() has been removed, since
    4544           it provides a subset of the functionality of <xref linkend="IVirtualBox__openMedium"
    4545           xreflabel="IVirtualBox::openMedium()" />.</para>
     4659          it provides a subset of the functionality of
     4660          <link linkend="IVirtualBox__openMedium">IVirtualBox::openMedium()</link>.</para>
    45464661        </listitem>
    45474662
    … …  
    45624677              <row>
    45634678                <entry>PointingHidType</entry>
    4564                 <entry><xref linkend="PointingHIDType" xreflabel="PointingHIDType"/></entry>
     4679                <entry><link linkend="PointingHIDType">PointingHIDType</link></entry>
    45654680              </row>
    45664681              <row>
    45674682                <entry>KeyboardHidType</entry>
    4568                 <entry><xref linkend="KeyboardHIDType" xreflabel="KeyboardHIDType"/></entry>
     4683                <entry><link linkend="KeyboardHIDType">KeyboardHIDType</link></entry>
    45694684              </row>
    45704685              <row>
    45714686                <entry>IPciAddress</entry>
    4572                 <entry><xref linkend="IPCIAddress" xreflabel="IPCIAddress"/></entry>
     4687                <entry><link linkend="IPCIAddress">IPCIAddress</link></entry>
    45734688              </row>
    45744689              <row>
    45754690                <entry>IPciDeviceAttachment</entry>
    4576                 <entry><xref linkend="IPCIDeviceAttachment" xreflabel="IPCIDeviceAttachment"/></entry>
     4691                <entry><link linkend="IPCIDeviceAttachment">IPCIDeviceAttachment</link></entry>
    45774692              </row>
    45784693              <row>
    45794694                <entry>IMachine::pointingHidType</entry>
    4580                 <entry><xref linkend="IMachine__pointingHIDType" xreflabel="IMachine::pointingHIDType"/></entry>
     4695                <entry><link linkend="IMachine__pointingHIDType">IMachine::pointingHIDType</link></entry>
    45814696              </row>
    45824697              <row>
    45834698                <entry>IMachine::keyboardHidType</entry>
    4584                 <entry><xref linkend="IMachine__keyboardHIDType" xreflabel="IMachine::keyboardHIDType"/></entry>
     4699                <entry><link linkend="IMachine__keyboardHIDType">IMachine::keyboardHIDType</link></entry>
    45854700              </row>
    45864701              <row>
    45874702                <entry>IMachine::hpetEnabled</entry>
    4588                 <entry><xref linkend="IMachine__HPETEnabled" xreflabel="IMachine::HPETEnabled"/></entry>
     4703                <entry><link linkend="IMachine__HPETEnabled">IMachine::HPETEnabled</link></entry>
    45894704              </row>
    45904705              <row>
    45914706                <entry>IMachine::sessionPid</entry>
    4592                 <entry><xref linkend="IMachine__sessionPID" xreflabel="IMachine::sessionPID"/></entry>
     4707                <entry><link linkend="IMachine__sessionPID">IMachine::sessionPID</link></entry>
    45934708              </row>
    45944709              <row>
    45954710                <entry>IMachine::ioCacheEnabled</entry>
    4596                 <entry><xref linkend="IMachine__IOCacheEnabled" xreflabel="IMachine::IOCacheEnabled"/></entry>
     4711                <entry><link linkend="IMachine__IOCacheEnabled">IMachine::IOCacheEnabled</link></entry>
    45974712              </row>
    45984713              <row>
    45994714                <entry>IMachine::ioCacheSize</entry>
    4600                 <entry><xref linkend="IMachine__IOCacheSize" xreflabel="IMachine::IOCacheSize"/></entry>
     4715                <entry><link linkend="IMachine__IOCacheSize">IMachine::IOCacheSize</link></entry>
    46014716              </row>
    46024717              <row>
    46034718                <entry>IMachine::pciDeviceAssignments</entry>
    4604                 <entry><xref linkend="IMachine__PCIDeviceAssignments" xreflabel="IMachine::PCIDeviceAssignments"/></entry>
     4719                <entry><link linkend="IMachine__PCIDeviceAssignments">IMachine::PCIDeviceAssignments</link></entry>
    46054720              </row>
    46064721              <row>
    46074722                <entry>IMachine::attachHostPciDevice()</entry>
    4608                 <entry><xref linkend="IMachine__attachHostPCIDevice" xreflabel="IMachine::attachHostPCIDevice"/></entry>
     4723                <entry><link linkend="IMachine__attachHostPCIDevice">IMachine::attachHostPCIDevice</link></entry>
    46094724              </row>
    46104725              <row>
    46114726                <entry>IMachine::detachHostPciDevice()</entry>
    4612                 <entry><xref linkend="IMachine__detachHostPCIDevice" xreflabel="IMachine::detachHostPCIDevice()"/></entry>
     4727                <entry><link linkend="IMachine__detachHostPCIDevice">IMachine::detachHostPCIDevice()</link></entry>
    46134728              </row>
    46144729              <row>
    46154730                <entry>IConsole::attachedPciDevices</entry>
    4616                 <entry><xref linkend="IConsole__attachedPCIDevices" xreflabel="IConsole::attachedPCIDevices"/></entry>
     4731                <entry><link linkend="IConsole__attachedPCIDevices">IConsole::attachedPCIDevices</link></entry>
    46174732              </row>
    46184733              <row>
    46194734                <entry>IHostNetworkInterface::dhcpEnabled</entry>
    4620                 <entry><xref linkend="IHostNetworkInterface__DHCPEnabled" xreflabel="IHostNetworkInterface::DHCPEnabled"/></entry>
     4735                <entry><link linkend="IHostNetworkInterface__DHCPEnabled">IHostNetworkInterface::DHCPEnabled</link></entry>
    46214736              </row>
    46224737              <row>
    46234738                <entry>IHostNetworkInterface::enableStaticIpConfig()</entry>
    4624                 <entry><xref linkend="IHostNetworkInterface__enableStaticIPConfig" xreflabel="IHostNetworkInterface::enableStaticIPConfig()"/></entry>
     4739                <entry><link linkend="IHostNetworkInterface__enableStaticIPConfig">IHostNetworkInterface::enableStaticIPConfig()</link></entry>
    46254740              </row>
    46264741              <row>
    46274742                <entry>IHostNetworkInterface::enableStaticIpConfigV6()</entry>
    4628                 <entry><xref linkend="IHostNetworkInterface__enableStaticIPConfigV6" xreflabel="IHostNetworkInterface::enableStaticIPConfigV6()"/></entry>
     4743                <entry><link linkend="IHostNetworkInterface__enableStaticIPConfigV6">IHostNetworkInterface::enableStaticIPConfigV6()</link></entry>
    46294744              </row>
    46304745              <row>
    46314746                <entry>IHostNetworkInterface::enableDynamicIpConfig()</entry>
    4632                 <entry><xref linkend="IHostNetworkInterface__enableDynamicIPConfig" xreflabel="IHostNetworkInterface::enableDynamicIPConfig()"/></entry>
     4747                <entry><link linkend="IHostNetworkInterface__enableDynamicIPConfig">IHostNetworkInterface::enableDynamicIPConfig()</link></entry>
    46334748              </row>
    46344749              <row>
    46354750                <entry>IHostNetworkInterface::dhcpRediscover()</entry>
    4636                 <entry><xref linkend="IHostNetworkInterface__DHCPRediscover" xreflabel="IHostNetworkInterface::DHCPRediscover()"/></entry>
     4751                <entry><link linkend="IHostNetworkInterface__DHCPRediscover">IHostNetworkInterface::DHCPRediscover()</link></entry>
    46374752              </row>
    46384753              <row>
    46394754                <entry>IHost::Acceleration3DAvailable</entry>
    4640                 <entry><xref linkend="IHost__acceleration3DAvailable" xreflabel="IHost::acceleration3DAvailable"/></entry>
     4755                <entry><link linkend="IHost__acceleration3DAvailable">IHost::acceleration3DAvailable</link></entry>
    46414756              </row>
    46424757              <row>
    46434758                <entry>IGuestOSType::recommendedPae</entry>
    4644                 <entry><xref linkend="IGuestOSType__recommendedPAE" xreflabel="IGuestOSType::recommendedPAE"/></entry>
     4759                <entry><link linkend="IGuestOSType__recommendedPAE">IGuestOSType::recommendedPAE</link></entry>
    46454760              </row>
    46464761              <row>
    46474762                <entry>IGuestOSType::recommendedDvdStorageController</entry>
    4648                 <entry><xref linkend="IGuestOSType__recommendedDVDStorageController" xreflabel="IGuestOSType::recommendedDVDStorageController"/></entry>
     4763                <entry><link linkend="IGuestOSType__recommendedDVDStorageController">IGuestOSType::recommendedDVDStorageController</link></entry>
    46494764              </row>
    46504765              <row>
    46514766                <entry>IGuestOSType::recommendedDvdStorageBus</entry>
    4652                 <entry><xref linkend="IGuestOSType__recommendedDVDStorageBus" xreflabel="IGuestOSType::recommendedDVDStorageBus"/></entry>
     4767                <entry><link linkend="IGuestOSType__recommendedDVDStorageBus">IGuestOSType::recommendedDVDStorageBus</link></entry>
    46534768              </row>
    46544769              <row>
    46554770                <entry>IGuestOSType::recommendedHdStorageController</entry>
    4656                 <entry><xref linkend="IGuestOSType__recommendedHDStorageController" xreflabel="IGuestOSType::recommendedHDStorageController"/></entry>
     4771                <entry><link linkend="IGuestOSType__recommendedHDStorageController">IGuestOSType::recommendedHDStorageController</link></entry>
    46574772              </row>
    46584773              <row>
    46594774                <entry>IGuestOSType::recommendedHdStorageBus</entry>
    4660                 <entry><xref linkend="IGuestOSType__recommendedHDStorageBus" xreflabel="IGuestOSType::recommendedHDStorageBus"/></entry>
     4775                <entry><link linkend="IGuestOSType__recommendedHDStorageBus">IGuestOSType::recommendedHDStorageBus</link></entry>
    46614776              </row>
    46624777              <row>
    46634778                <entry>IGuestOSType::recommendedUsbHid</entry>
    4664                 <entry><xref linkend="IGuestOSType__recommendedUSBHID" xreflabel="IGuestOSType::recommendedUSBHID"/></entry>
     4779                <entry><link linkend="IGuestOSType__recommendedUSBHID">IGuestOSType::recommendedUSBHID</link></entry>
    46654780              </row>
    46664781              <row>
    46674782                <entry>IGuestOSType::recommendedHpet</entry>
    4668                 <entry><xref linkend="IGuestOSType__recommendedHPET" xreflabel="IGuestOSType::recommendedHPET"/></entry>
     4783                <entry><link linkend="IGuestOSType__recommendedHPET">IGuestOSType::recommendedHPET</link></entry>
    46694784              </row>
    46704785              <row>
    46714786                <entry>IGuestOSType::recommendedUsbTablet</entry>
    4672                 <entry><xref linkend="IGuestOSType__recommendedUSBTablet" xreflabel="IGuestOSType::recommendedUSBTablet"/></entry>
     4787                <entry><link linkend="IGuestOSType__recommendedUSBTablet">IGuestOSType::recommendedUSBTablet</link></entry>
    46734788              </row>
    46744789              <row>
    46754790                <entry>IGuestOSType::recommendedRtcUseUtc</entry>
    4676                 <entry><xref linkend="IGuestOSType__recommendedRTCUseUTC" xreflabel="IGuestOSType::recommendedRTCUseUTC"/></entry>
     4791                <entry><link linkend="IGuestOSType__recommendedRTCUseUTC">IGuestOSType::recommendedRTCUseUTC</link></entry>
    46774792              </row>
    46784793              <row>
    46794794                <entry>IGuestOSType::recommendedUsb</entry>
    4680                 <entry><xref linkend="IGuestOSType__recommendedUSB" xreflabel="IGuestOSType::recommendedUSB"/></entry>
     4795                <entry><link linkend="IGuestOSType__recommendedUSB">IGuestOSType::recommendedUSB</link></entry>
    46814796              </row>
    46824797              <row>
    46834798                <entry>INetworkAdapter::natDriver</entry>
    4684                 <entry><xref linkend="INetworkAdapter__NATEngine" xreflabel="INetworkAdapter::NATEngine"/></entry>
     4799                <entry><link linkend="INetworkAdapter__NATEngine">INetworkAdapter::NATEngine</link></entry>
    46854800              </row>
    46864801              <row>
    … …  
    46904805              <row>
    46914806                <entry>INATEngine::tftpPrefix</entry>
    4692                 <entry><xref linkend="INATEngine__TFTPPrefix" xreflabel="INATEngine::TFTPPrefix"/></entry>
     4807                <entry><link linkend="INATEngine__TFTPPrefix">INATEngine::TFTPPrefix</link></entry>
    46934808              </row>
    46944809              <row>
    46954810                <entry>INATEngine::tftpBootFile</entry>
    4696                 <entry><xref linkend="INATEngine__TFTPBootFile" xreflabel="INATEngine::TFTPBootFile"/></entry>
     4811                <entry><link linkend="INATEngine__TFTPBootFile">INATEngine::TFTPBootFile</link></entry>
    46974812              </row>
    46984813              <row>
    46994814                <entry>INATEngine::tftpNextServer</entry>
    4700                 <entry><xref linkend="INATEngine__TFTPNextServer" xreflabel="INATEngine::TFTPNextServer"/></entry>
     4815                <entry><link linkend="INATEngine__TFTPNextServer">INATEngine::TFTPNextServer</link></entry>
    47014816              </row>
    47024817              <row>
    47034818                <entry>INATEngine::dnsPassDomain</entry>
    4704                 <entry><xref linkend="INATEngine__DNSPassDomain" xreflabel="INATEngine::DNSPassDomain"/></entry>
     4819                <entry><link linkend="INATEngine__DNSPassDomain">INATEngine::DNSPassDomain</link></entry>
    47054820              </row>
    47064821              <row>
    47074822                <entry>INATEngine::dnsProxy</entry>
    4708                 <entry><xref linkend="INATEngine__DNSProxy" xreflabel="INATEngine::DNSProxy"/></entry>
     4823                <entry><link linkend="INATEngine__DNSProxy">INATEngine::DNSProxy</link></entry>
    47094824              </row>
    47104825              <row>
    47114826                <entry>INATEngine::dnsUseHostResolver</entry>
    4712                 <entry><xref linkend="INATEngine__DNSUseHostResolver" xreflabel="INATEngine::DNSUseHostResolver"/></entry>
     4827                <entry><link linkend="INATEngine__DNSUseHostResolver">INATEngine::DNSUseHostResolver</link></entry>
    47134828              </row>
    47144829              <row>
    47154830                <entry>VBoxEventType::OnHostPciDevicePlug</entry>
    4716                 <entry><xref linkend="VBoxEventType__OnHostPCIDevicePlug" xreflabel="VBoxEventType::OnHostPCIDevicePlug"/></entry>
     4831                <entry><link linkend="VBoxEventType__OnHostPCIDevicePlug">VBoxEventType::OnHostPCIDevicePlug</link></entry>
    47174832              </row>
    47184833              <row>
    47194834                <entry>ICPUChangedEvent::cpu</entry>
    4720                 <entry><xref linkend="ICPUChangedEvent__CPU" xreflabel="ICPUChangedEvent::CPU"/></entry>
     4835                <entry><link linkend="ICPUChangedEvent__CPU">ICPUChangedEvent::CPU</link></entry>
    47214836              </row>
    47224837              <row>
    47234838                <entry>INATRedirectEvent::hostIp</entry>
    4724                 <entry><xref linkend="INATRedirectEvent__hostIP" xreflabel="INATRedirectEvent::hostIP"/></entry>
     4839                <entry><link linkend="INATRedirectEvent__hostIP">INATRedirectEvent::hostIP</link></entry>
    47254840              </row>
    47264841              <row>
    47274842                <entry>INATRedirectEvent::guestIp</entry>
    4728                 <entry><xref linkend="INATRedirectEvent__guestIP" xreflabel="INATRedirectEvent::guestIP"/></entry>
     4843                <entry><link linkend="INATRedirectEvent__guestIP">INATRedirectEvent::guestIP</link></entry>
    47294844              </row>
    47304845              <row>
    47314846                <entry>IHostPciDevicePlugEvent</entry>
    4732                 <entry><xref linkend="IHostPCIDevicePlugEvent" xreflabel="IHostPCIDevicePlugEvent"/></entry>
     4847                <entry><link linkend="IHostPCIDevicePlugEvent">IHostPCIDevicePlugEvent</link></entry>
    47334848              </row>
    47344849            </tbody>
    … …  
    47434858      <itemizedlist>
    47444859        <listitem>
    4745           <para>The method <xref linkend="IAppliance__importMachines"
    4746           xreflabel="IAppliance::importMachines()" /> has one more parameter
    4747           now, which allows to configure the import process in more detail.
     4860          <para>The method
     4861          <link linkend="IAppliance__importMachines">IAppliance::importMachines()</link>
     4862          has one more parameter now, which allows to configure the import
     4863          process in more detail.
    47484864          </para>
    47494865        </listitem>
    47504866
    47514867        <listitem>
    4752           <para>The method <xref linkend="IVirtualBox__openMedium"
    4753           xreflabel="IVirtualBox::openMedium()" /> has one more parameter
    4754           now, which allows resolving duplicate medium UUIDs without the need
    4755           for external tools.</para>
    4756         </listitem>
    4757 
    4758         <listitem>
    4759           <para>The <xref linkend="INetworkAdapter" xreflabel="INetworkAdapter"/>
     4868          <para>The method
     4869          <link linkend="IVirtualBox__openMedium">IVirtualBox::openMedium()</link>
     4870          has one more parameter now, which allows resolving duplicate medium
     4871          UUIDs without the need for external tools.</para>
     4872        </listitem>
     4873
     4874        <listitem>
     4875          <para>The <link linkend="INetworkAdapter">INetworkAdapter</link>
    47604876          interface has been cleaned up. The various methods to activate an
    47614877          attachment type have been replaced by the
    4762           <xref linkend="INetworkAdapter__attachmentType" xreflabel="INetworkAdapter::attachmentType"/> setter.</para>
     4878          <link linkend="INetworkAdapter__attachmentType">INetworkAdapter::attachmentType</link>
     4879          setter.</para>
    47634880          <para>Additionally each attachment mode now has its own attribute,
    47644881          which means that host only networks no longer share the settings with
    … …  
    47724889        <listitem>
    47734890          <para>This version introduces the guest facilities concept. A guest
    4774           facility either represents a module or feature the guest is running or
    4775           offering, which is defined by <xref linkend="AdditionsFacilityType"
    4776           xreflabel="AdditionsFacilityType"/>. Each facility is member of a
    4777           <xref linkend="AdditionsFacilityClass" xreflabel="AdditionsFacilityClass"/>
    4778           and has a current status indicated by <xref linkend="AdditionsFacilityStatus"
    4779           xreflabel="AdditionsFacilityStatus"/>, together with a timestamp (in ms) of
    4780           the last status update.</para>
     4891          facility either represents a module or feature the guest is running
     4892          or offering, which is defined by
     4893          <link linkend="AdditionsFacilityType">AdditionsFacilityType</link>.
     4894          Each facility is member of a
     4895          <link linkend="AdditionsFacilityClass">AdditionsFacilityClass</link>
     4896          and has a current status indicated by
     4897          <link linkend="AdditionsFacilityStatus">AdditionsFacilityStatus</link>,
     4898          together with a timestamp (in ms) of the last status update.</para>
    47814899          <para>To address the above concept, the following changes were made:
    47824900            <itemizedlist>
    47834901              <listitem>
    47844902                <para>
    4785                   In the <xref linkend="IGuest" xreflabel="IGuest"/> interface, the following were removed:
     4903                  In the <link linkend="IGuest">IGuest</link> interface, the
     4904                  following were removed:
    47864905                  <itemizedlist>
    47874906                    <listitem>
    4788                       <para>the <computeroutput>supportsSeamless</computeroutput> attribute;</para>
     4907                      <para>the
     4908                      <computeroutput>supportsSeamless</computeroutput>
     4909                      attribute;</para>
    47894910                    </listitem>
    47904911                    <listitem>
    4791                       <para>the <computeroutput>supportsGraphics</computeroutput> attribute;</para>
     4912                      <para>the
     4913                      <computeroutput>supportsGraphics</computeroutput>
     4914                      attribute;</para>
    47924915                    </listitem>
    47934916                  </itemizedlist>
    … …  
    47964919              <listitem>
    47974920                <para>
    4798                   The function <xref linkend="IGuest__getFacilityStatus" xreflabel="IGuest::getFacilityStatus()"/>
    4799                   was added. It quickly provides a facility's status without the need to get the facility
    4800                   collection with <xref linkend="IGuest__facilities" xreflabel="IGuest::facilities"/>.
     4921                  The function
     4922                  <link linkend="IGuest__getFacilityStatus">IGuest::getFacilityStatus()</link>
     4923                  was added. It quickly provides a facility's status without
     4924                  the need to get the facility collection with
     4925                  <link linkend="IGuest__facilities">IGuest::facilities</link>.
    48014926                </para>
    48024927              </listitem>
    48034928              <listitem>
    48044929                <para>
    4805                   The attribute <xref linkend="IGuest__facilities" xreflabel="IGuest::facilities"/>
    4806                   was added to provide an easy to access collection of all currently known guest
    4807                   facilities, that is, it contains all facilies where at least one status update was
    4808                   made since the guest was started.
     4930                  The attribute
     4931                  <link linkend="IGuest__facilities">IGuest::facilities</link>
     4932                  was added to provide an easy to access collection of all
     4933                  currently known guest facilities, that is, it contains all
     4934                  facilies where at least one status update was made since the
     4935                  guest was started.
    48094936                </para>
    48104937              </listitem>
    48114938              <listitem>
    48124939                <para>
    4813                   The interface <xref linkend="IAdditionsFacility" xreflabel="IAdditionsFacility"/>
     4940                  The interface
     4941                  <link linkend="IAdditionsFacility">IAdditionsFacility</link>
    48144942                  was added to represent a single facility returned by
    4815                   <xref linkend="IGuest__facilities" xreflabel="IGuest::facilities"/>.
     4943                  <link linkend="IGuest__facilities">IGuest::facilities</link>.
    48164944                </para>
    48174945              </listitem>
    48184946              <listitem>
    48194947                <para>
    4820                   <xref linkend="AdditionsFacilityStatus" xreflabel="AdditionsFacilityStatus"/>
     4948                  <link linkend="AdditionsFacilityStatus">AdditionsFacilityStatus</link>
    48214949                  was added to represent a facility's overall status.
    48224950                </para>
    … …  
    48244952              <listitem>
    48254953                <para>
    4826                   <xref linkend="AdditionsFacilityType" xreflabel="AdditionsFacilityType"/> and
    4827                   <xref linkend="AdditionsFacilityClass" xreflabel="AdditionsFacilityClass"/> were
     4954                  <link linkend="AdditionsFacilityType">AdditionsFacilityType</link> and
     4955                  <link linkend="AdditionsFacilityClass">AdditionsFacilityClass</link> were
    48284956                  added to represent the facility's type and class.
    48294957                </para>
    … …  
    48454973          instead of <computeroutput>IWebsessionManager</computeroutput>, the
    48464974          new class <computeroutput>VirtualBoxManager</computeroutput> must be
    4847           used. See <xref linkend="javaapi" xreflabel="Java API chapter" />
    4848           for details.</para>
     4975          used. See <xref linkend="javaapi"/> for details.</para>
    48494976        </listitem>
    48504977
    … …  
    48564983                <para>Replace any
    48574984                <computeroutput>IVirtualBox::openSession(uuidMachine,
    4858                 ...)</computeroutput> API call with the machine's <xref
    4859                 linkend="IMachine__lockMachine"
    4860                 xreflabel="IMachine::lockMachine()" /> call and a
     4985                ...)</computeroutput> API call with the machine's
     4986                <link linkend="IMachine__lockMachine">IMachine::lockMachine()</link>
     4987                call and a
    48614988                <computeroutput>LockType.Write</computeroutput> argument. The
    48624989                functionality is unchanged, but instead of "opening a direct
    … …  
    48694996                <para>Similarly, replace any
    48704997                <computeroutput>IVirtualBox::openExistingSession(uuidMachine,
    4871                 ...)</computeroutput> call with the machine's <xref
    4872                 linkend="IMachine__lockMachine"
    4873                 xreflabel="IMachine::lockMachine()" /> call and a
    4874                 <computeroutput>LockType.Shared</computeroutput> argument.
    4875                 Whereas it was previously impossible to connect a client
    4876                 session to a running VM process in a race-free manner, the new
    4877                 API will atomically either write-lock the machine for the
    4878                 current session or establish a remote link to an existing
     4998                ...)</computeroutput> call with the machine's
     4999                <link linkend="IMachine__lockMachine">IMachine::lockMachine()</link>
     5000                call and a <computeroutput>LockType.Shared</computeroutput>
     5001                argument. Whereas it was previously impossible to connect a
     5002                client session to a running VM process in a race-free manner,
     5003                the new API will atomically either write-lock the machine for
     5004                the current session or establish a remote link to an existing
    48795005                session. Existing client code which tried calling both
    48805006                <computeroutput>openSession()</computeroutput> and
    … …  
    48865012                <para>Third, replace any
    48875013                <computeroutput>IVirtualBox::openRemoteSession(uuidMachine,
    4888                 ...)</computeroutput> call with the machine's <xref
    4889                 linkend="IMachine__launchVMProcess"
    4890                 xreflabel="IMachine::launchVMProcess()" /> call. The
    4891                 functionality is unchanged.</para>
    4892               </listitem>
    4893 
    4894               <listitem>
    4895                 <para>The <xref linkend="SessionState"
    4896                 xreflabel="SessionState" /> enum was adjusted accordingly:
    4897                 "Open" is now "Locked", "Closed" is now "Unlocked", "Closing"
    4898                 is now "Unlocking".</para>
     5014                ...)</computeroutput> call with the machine's
     5015                <link linkend="IMachine__launchVMProcess">IMachine::launchVMProcess()</link>
     5016                call. The functionality is unchanged.</para>
     5017              </listitem>
     5018
     5019              <listitem>
     5020                <para>The <link linkend="SessionState">SessionState</link> enum
     5021                was adjusted accordingly: "Open" is now "Locked", "Closed" is
     5022                now "Unlocked", "Closing" is now "Unlocking".</para>
    48995023              </listitem>
    49005024            </itemizedlist></para>
    … …  
    49115035                <para>Neither
    49125036                <computeroutput>IVirtualBox::createHardDisk()</computeroutput>
    4913                 nor <xref linkend="IVirtualBox__openMedium"
    4914                 xreflabel="IVirtualBox::openMedium()" /> register media
    4915                 automatically any more.</para>
    4916               </listitem>
    4917 
    4918               <listitem>
    4919                 <para><xref linkend="IMachine__attachDevice"
    4920                 xreflabel="IMachine::attachDevice()" /> and <xref
    4921                 linkend="IMachine__mountMedium"
    4922                 xreflabel="IMachine::mountMedium()" /> now take an IMedium
    4923                 object instead of a UUID as an argument. It is these two calls
    4924                 which add media to a registry now (either a machine registry
    4925                 for machines created with VirtualBox 4.0 or later or the
    4926                 global registry otherwise). As a consequence, if a medium is
    4927                 opened but never attached to a machine, it is no longer added
    4928                 to any registry any more.</para>
     5037                nor
     5038                <link linkend="IVirtualBox__openMedium">IVirtualBox::openMedium()</link>
     5039                register media automatically any more.</para>
     5040              </listitem>
     5041
     5042              <listitem>
     5043                <para><link linkend="IMachine__attachDevice">IMachine::attachDevice()</link>
     5044                and
     5045                <link linkend="IMachine__mountMedium">IMachine::mountMedium()</link>
     5046                now take an IMedium object instead of a UUID as an argument. It
     5047                is these two calls which add media to a registry now (either a
     5048                machine registry for machines created with VirtualBox 4.0 or
     5049                later or the global registry otherwise). As a consequence, if a
     5050                medium is opened but never attached to a machine, it is no
     5051                longer added to any registry any more.</para>
    49295052              </listitem>
    49305053
    … …  
    49355058                been merged into IVirtualBox::findMedium(), and
    49365059                IVirtualBox::openHardDisk(), openDVDImage() and
    4937                 openFloppyImage() have all been merged into <xref
    4938                 linkend="IVirtualBox__openMedium"
    4939                 xreflabel="IVirtualBox::openMedium()" />.</para>
     5060                openFloppyImage() have all been merged into
     5061                <link linkend="IVirtualBox__openMedium">IVirtualBox::openMedium()</link>.</para>
    49405062              </listitem>
    49415063
    … …  
    49545076
    49555077              <listitem>
    4956                 <para>The <xref linkend="ISystemProperties__infoVDSize"
    4957                 xreflabel="ISystemProperties::infoVDSize" /> attribute
    4958                 replaces the <computeroutput>getMaxVDISize()</computeroutput>
     5078                <para>The
     5079                <link linkend="ISystemProperties__infoVDSize">ISystemProperties::infoVDSize</link>
     5080                attribute replaces the
     5081                <computeroutput>getMaxVDISize()</computeroutput>
    49595082                API call; this now uses bytes instead of megabytes.</para>
    49605083              </listitem>
    … …  
    49655088          <para>Machine management APIs were enhanced as follows:<itemizedlist>
    49665089              <listitem>
    4967                 <para><xref linkend="IVirtualBox__createMachine"
    4968                 xreflabel="IVirtualBox::createMachine()" /> is no longer
    4969                 restricted to creating machines in the default "Machines"
    4970                 folder, but can now create machines at arbitrary locations.
    4971                 For this to work, the parameter list had to be changed.</para>
     5090                <para><link linkend="IVirtualBox__createMachine">IVirtualBox::createMachine()</link>
     5091                is no longer restricted to creating machines in the default
     5092                "Machines" folder, but can now create machines at arbitrary
     5093                locations. For this to work, the parameter list had to be
     5094                changed.</para>
    49725095              </listitem>
    49735096
    … …  
    49825105                aforementioned media APIs,
    49835106                <computeroutput>IVirtualBox::getMachine()</computeroutput> has
    4984                 been merged with <xref linkend="IVirtualBox__findMachine"
    4985                 xreflabel="IVirtualBox::findMachine()" />, and
     5107                been merged with
     5108                <link linkend="IVirtualBox__findMachine">IVirtualBox::findMachine()</link>,
     5109                and
    49865110                <computeroutput>IMachine::getSnapshot()</computeroutput> has
    4987                 been merged with <xref linkend="IMachine__findSnapshot"
    4988                 xreflabel="IMachine::findSnapshot()" />.</para>
     5111                been merged with
     5112                <link linkend="IMachine__findSnapshot">IMachine::findSnapshot()</link>.</para>
    49895113              </listitem>
    49905114
    49915115              <listitem>
    49925116                <para><computeroutput>IVirtualBox::unregisterMachine()</computeroutput>
    4993                 was replaced with <xref linkend="IMachine__unregister"
    4994                 xreflabel="IMachine::unregister()" /> with additional
    4995                 functionality for cleaning up machine files.</para>
     5117                was replaced with
     5118                <link linkend="IMachine__unregister">IMachine::unregister()</link>
     5119                with additional functionality for cleaning up machine
     5120                files.</para>
    49965121              </listitem>
    49975122
    … …  
    50085133              <listitem>
    50095134                <para><computeroutput>IConsole::forgetSavedState</computeroutput>
    5010                 has been renamed to <computeroutput>IConsole::discardSavedState()</computeroutput>.</para>
     5135                has been renamed to
     5136                <computeroutput>IConsole::discardSavedState()</computeroutput>.</para>
    50115137              </listitem>
    50125138            </itemizedlist></para>
    … …  
    50175143          event mechanism that can be used both locally (COM, XPCOM) and
    50185144          remotely (web services). Also, the new mechanism is usable from
    5019           scripting languages and a local Java. See <xref linkend="IEvent"
    5020           xreflabel="events" /> for details. The new concept will require
    5021           changes to all clients that used event callbacks.</para>
    5022         </listitem>
    5023 
    5024         <listitem>
    5025           <para><computeroutput>additionsActive()</computeroutput> was
    5026           replaced with <xref linkend="IGuest__additionsRunLevel"
    5027           xreflabel="additionsRunLevel()" /> and <xref
    5028           linkend="IGuest__getAdditionsStatus"
    5029           xreflabel="getAdditionsStatus()" /> in order to support a more
    5030           detailed status of the current Guest Additions loading/readiness
    5031           state. <xref linkend="IGuest__additionsVersion"
    5032           xreflabel="IGuest::additionsVersion()" /> no longer returns the
    5033           Guest Additions interface version but the installed Guest Additions
    5034           version and revision in form of
     5145          scripting languages and a local Java. See
     5146          <link linkend="IEvent">events</link> for details. The new concept
     5147          will require changes to all clients that used event callbacks.</para>
     5148        </listitem>
     5149
     5150        <listitem>
     5151          <para><computeroutput>additionsActive()</computeroutput> was replaced
     5152          with
     5153          <link linkend="IGuest__additionsRunLevel">additionsRunLevel()</link>
     5154          and
     5155          <link linkend="IGuest__getAdditionsStatus">getAdditionsStatus()</link>
     5156          in order to support a more detailed status of the current Guest
     5157          Additions loading/readiness state.
     5158          <link linkend="IGuest__additionsVersion">IGuest::additionsVersion()</link>
     5159          no longer returns the Guest Additions interface version but the
     5160          installed Guest Additions version and revision in form of
    50355161          <computeroutput>3.3.0r12345</computeroutput>.</para>
    50365162        </listitem>
    … …  
    50415167          <computeroutput>automount</computeroutput> parameter: <itemizedlist>
    50425168              <listitem>
    5043                 <para><xref linkend="IVirtualBox__createSharedFolder"
    5044                 xreflabel="IVirtualBox::createSharedFolder()" /></para>
    5045               </listitem>
    5046 
    5047               <listitem>
    5048                 <para><xref linkend="IMachine__createSharedFolder"
    5049                 xreflabel="IMachine::createSharedFolder()" /></para>
    5050               </listitem>
    5051 
    5052               <listitem>
    5053                 <para><xref linkend="IConsole__createSharedFolder"
    5054                 xreflabel="IConsole::createSharedFolder()" /></para>
     5169                <para><link linkend="IVirtualBox__createSharedFolder">IVirtualBox::createSharedFolder()</link></para>
     5170              </listitem>
     5171
     5172              <listitem>
     5173                <para><link linkend="IMachine__createSharedFolder">IMachine::createSharedFolder()</link></para>
     5174              </listitem>
     5175
     5176              <listitem>
     5177                <para><link linkend="IConsole__createSharedFolder">IConsole::createSharedFolder()</link></para>
    50555178              </listitem>
    50565179            </itemizedlist> Also, a new property named
    5057           <computeroutput>autoMount</computeroutput> was added to the <xref
    5058           linkend="ISharedFolder" xreflabel="ISharedFolder" />
     5180          <computeroutput>autoMount</computeroutput> was added to the
     5181          <link linkend="ISharedFolder">ISharedFolder</link>
    50595182          interface.</para>
    50605183        </listitem>
    … …  
    50715194
    50725195              <listitem>
    5073                 <para><xref linkend="IAppliance__write"
    5074                 xreflabel="IAppliance::write()" /> received an extra parameter
     5196                <para><link linkend="IAppliance__write">IAppliance::write()</link>
     5197                received an extra parameter
    50755198                <computeroutput>manifest</computeroutput>, which can suppress
    50765199                creating the manifest file on export.</para>
    … …  
    50785201
    50795202              <listitem>
    5080                 <para><xref linkend="IVFSExplorer__entryList"
    5081                 xreflabel="IVFSExplorer::entryList()" /> received two extra
    5082                 parameters <computeroutput>sizes</computeroutput> and
     5203                <para><link linkend="IVFSExplorer__entryList">IVFSExplorer::entryList()</link>
     5204                received two extra parameters
     5205                <computeroutput>sizes</computeroutput> and
    50835206                <computeroutput>modes</computeroutput>, which contains the
    50845207                sizes (in bytes) and the file access modes (in octal form) of
    … …  
    51005223              <listitem>
    51015224                <para><computeroutput>IVRDPServer</computeroutput> has been
    5102                 renamed to <xref linkend="IVRDEServer"
    5103                 xreflabel="IVRDEServer" />.</para>
     5225                renamed to
     5226                <link linkend="IVRDEServer">IVRDEServer</link>.</para>
    51045227              </listitem>
    51055228
    51065229              <listitem>
    51075230                <para><computeroutput>IRemoteDisplayInfo</computeroutput> has
    5108                 been renamed to <xref linkend="IVRDEServerInfo"
    5109                 xreflabel="IVRDEServerInfo" />.</para>
    5110               </listitem>
    5111 
    5112               <listitem>
    5113                 <para><xref linkend="IMachine__VRDEServer"
    5114                 xreflabel="IMachine::VRDEServer" /> replaces
     5231                been renamed to
     5232                <link linkend="IVRDEServerInfo">IVRDEServerInfo</link>.</para>
     5233              </listitem>
     5234
     5235              <listitem>
     5236                <para><link linkend="IMachine__VRDEServer">IMachine::VRDEServer</link>
     5237                replaces
    51155238                <computeroutput>VRDPServer.</computeroutput></para>
    51165239              </listitem>
    51175240
    51185241              <listitem>
    5119                 <para><xref linkend="IConsole__VRDEServerInfo"
    5120                 xreflabel="IConsole::VRDEServerInfo" /> replaces
     5242                <para><link linkend="IConsole__VRDEServerInfo">IConsole::VRDEServerInfo</link>
     5243                replaces
    51215244                <computeroutput>RemoteDisplayInfo</computeroutput>.</para>
    51225245              </listitem>
    51235246
    51245247              <listitem>
    5125                 <para><xref linkend="ISystemProperties__VRDEAuthLibrary"
    5126                 xreflabel="ISystemProperties::VRDEAuthLibrary" /> replaces
     5248                <para><link linkend="ISystemProperties__VRDEAuthLibrary">ISystemProperties::VRDEAuthLibrary</link>
     5249                replaces
    51275250                <computeroutput>RemoteDisplayAuthLibrary</computeroutput>.</para>
    51285251              </listitem>
    … …  
    51335256                generic VRDE properties: <itemizedlist>
    51345257                    <listitem>
    5135                       <para><xref linkend="IVRDEServer__setVRDEProperty"
    5136                       xreflabel="IVRDEServer::setVRDEProperty" /></para>
     5258                      <para><link linkend="IVRDEServer__setVRDEProperty">IVRDEServer::setVRDEProperty</link></para>
    51375259                    </listitem>
    51385260
    51395261                    <listitem>
    5140                       <para><xref linkend="IVRDEServer__getVRDEProperty"
    5141                       xreflabel="IVRDEServer::getVRDEProperty" /></para>
     5262                      <para><link linkend="IVRDEServer__getVRDEProperty">IVRDEServer::getVRDEProperty</link></para>
    51425263                    </listitem>
    51435264
    51445265                    <listitem>
    5145                       <para><xref linkend="IVRDEServer__VRDEProperties"
    5146                       xreflabel="IVRDEServer::VRDEProperties" /></para>
     5266                      <para><link linkend="IVRDEServer__VRDEProperties">IVRDEServer::VRDEProperties</link></para>
    51475267                    </listitem>
    51485268                  </itemizedlist></para>
    … …  
    51975317          been updated and made more generic. Because of that,
    51985318          <computeroutput>VRDPAuthType</computeroutput> enumeration has been
    5199           renamed to <xref linkend="AuthType" xreflabel="AuthType" />.</para>
     5319          renamed to <link linkend="AuthType">AuthType</link>.</para>
    52005320        </listitem>
    52015321      </itemizedlist>
    … …  
    52105330          <itemizedlist>
    52115331              <listitem>
    5212                 <para>IMachine::getCpuProperty() is now <xref
    5213                 linkend="IMachine__getCPUProperty"
    5214                 xreflabel="IMachine::getCPUProperty()" />;</para>
    5215               </listitem>
    5216 
    5217               <listitem>
    5218                 <para>IMachine::setCpuProperty() is now <xref
    5219                 linkend="IMachine__setCPUProperty"
    5220                 xreflabel="IMachine::setCPUProperty()" />;</para>
    5221               </listitem>
    5222 
    5223               <listitem>
    5224                 <para>IMachine::getCpuIdLeaf() is now <xref
    5225                 linkend="IMachine__getCPUIDLeaf"
    5226                 xreflabel="IMachine::getCPUIDLeaf()" />;</para>
    5227               </listitem>
    5228 
    5229               <listitem>
    5230                 <para>IMachine::setCpuIdLeaf() is now <xref
    5231                 linkend="IMachine__setCPUIDLeaf"
    5232                 xreflabel="IMachine::setCPUIDLeaf()" />;</para>
    5233               </listitem>
    5234 
    5235               <listitem>
    5236                 <para>IMachine::removeCpuIdLeaf() is now <xref
    5237                 linkend="IMachine__removeCPUIDLeaf"
    5238                 xreflabel="IMachine::removeCPUIDLeaf()" />;</para>
    5239               </listitem>
    5240 
    5241               <listitem>
    5242                 <para>IMachine::removeAllCpuIdLeafs() is now <xref
    5243                 linkend="IMachine__removeAllCPUIDLeaves"
    5244                 xreflabel="IMachine::removeAllCPUIDLeaves()" />;</para>
    5245               </listitem>
    5246 
    5247               <listitem>
    5248                 <para>the CpuPropertyType enum is now <xref
    5249                 linkend="CPUPropertyType"
    5250                 xreflabel="CPUPropertyType" />.</para>
     5332                <para>IMachine::getCpuProperty() is now
     5333                <link linkend="IMachine__getCPUProperty">IMachine::getCPUProperty()</link>;</para>
     5334              </listitem>
     5335
     5336              <listitem>
     5337                <para>IMachine::setCpuProperty() is now
     5338                <link linkend="IMachine__setCPUProperty">IMachine::setCPUProperty()</link>;</para>
     5339              </listitem>
     5340
     5341              <listitem>
     5342                <para>IMachine::getCpuIdLeaf() is now
     5343                <link linkend="IMachine__getCPUIDLeaf">IMachine::getCPUIDLeaf()</link>;</para>
     5344              </listitem>
     5345
     5346              <listitem>
     5347                <para>IMachine::setCpuIdLeaf() is now
     5348                <link linkend="IMachine__setCPUIDLeaf">IMachine::setCPUIDLeaf()</link>;</para>
     5349              </listitem>
     5350
     5351              <listitem>
     5352                <para>IMachine::removeCpuIdLeaf() is now
     5353                <link linkend="IMachine__removeCPUIDLeaf">IMachine::removeCPUIDLeaf()</link>;</para>
     5354              </listitem>
     5355
     5356              <listitem>
     5357                <para>IMachine::removeAllCpuIdLeafs() is now
     5358                <link linkend="IMachine__removeAllCPUIDLeaves">IMachine::removeAllCPUIDLeaves()</link>;</para>
     5359              </listitem>
     5360
     5361              <listitem>
     5362                <para>the CpuPropertyType enum is now
     5363                <link linkend="CPUPropertyType">CPUPropertyType</link>.</para>
    52515364              </listitem>
    52525365
    … …  
    52595372
    52605373        <listitem>
    5261           <para>When creating a VM configuration with <xref
    5262           linkend="IVirtualBox__createMachine"
    5263           xreflabel="IVirtualBox::createMachine()" /> it is now possible to
    5264           ignore existing configuration files which would previously have
    5265           caused a failure. For this the
    5266           <computeroutput>override</computeroutput> parameter was
    5267           added.</para>
     5374          <para>When creating a VM configuration with
     5375          <link linkend="IVirtualBox__createMachine">IVirtualBox::createMachine()</link>
     5376          it is now possible to ignore existing configuration files which would
     5377          previously have caused a failure. For this the
     5378          <computeroutput>override</computeroutput> parameter was added.</para>
    52685379        </listitem>
    52695380
    … …  
    52795390        <listitem>
    52805391          <para>The IoBackendType enumeration was replaced with a boolean flag
    5281           (see <xref linkend="IStorageController__useHostIOCache"
    5282           xreflabel="IStorageController::useHostIOCache" />).</para>
     5392          (see
     5393          <link linkend="IStorageController__useHostIOCache">IStorageController::useHostIOCache</link>).</para>
    52835394        </listitem>
    52845395
    … …  
    52925403
    52935404              <listitem>
    5294                 <para><xref linkend="IMachine__readSavedThumbnailToArray"
    5295                 xreflabel="IMachine::readSavedThumbnailToArray()" /></para>
    5296               </listitem>
    5297 
    5298               <listitem>
    5299                 <para><xref linkend="IMachine__querySavedScreenshotInfo"
    5300                 xreflabel="IMachine::querySavedScreenshotPNGSize()" /></para>
    5301               </listitem>
    5302 
    5303               <listitem>
    5304                 <para><xref linkend="IMachine__readSavedScreenshotToArray"
    5305                 xreflabel="IMachine::readSavedScreenshotPNGToArray()" /></para>
     5405                <para><link linkend="IMachine__readSavedThumbnailToArray">IMachine::readSavedThumbnailToArray()</link></para>
     5406              </listitem>
     5407
     5408              <listitem>
     5409                <para><link linkend="IMachine__querySavedScreenshotInfo">IMachine::querySavedScreenshotPNGSize()</link></para>
     5410              </listitem>
     5411
     5412              <listitem>
     5413                <para><link linkend="IMachine__readSavedScreenshotToArray">IMachine::readSavedScreenshotPNGToArray()</link></para>
    53065414              </listitem>
    53075415            </itemizedlist></para>
    … …  
    53265434          attaching CD/DVD drives to arbitrary controllers), we seized the
    53275435          opportunity to rework all interfaces dealing with storage media to
    5328           make the API more flexible as well as logical. The <xref
    5329           linkend="IStorageController" xreflabel="IStorageController" />,
    5330           <xref linkend="IMedium" xreflabel="IMedium" />, <xref
    5331           linkend="IMediumAttachment" xreflabel="IMediumAttachment" /> and,
    5332           <xref linkend="IMachine" xreflabel="IMachine" /> interfaces were
     5436          make the API more flexible as well as logical. The
     5437          <link linkend="IStorageController">IStorageController</link>,
     5438          <link linkend="IMedium">IMedium</link>,
     5439          <link linkend="IMediumAttachment">IMediumAttachment</link> and
     5440          <link linkend="IMachine">IMachine</link> interfaces were
    53335441          affected the most. Existing code using them to configure storage and
    53345442          media needs to be carefully checked.</para>
    53355443
    53365444          <para>All media (hard disks, floppies and CDs/DVDs) are now
    5337           uniformly handled through the <xref linkend="IMedium"
    5338           xreflabel="IMedium" /> interface. The device-specific interfaces
     5445          uniformly handled through the <link linkend="IMedium">IMedium</link>
     5446          interface. The device-specific interfaces
    53395447          (<code>IHardDisk</code>, <code>IDVDImage</code>,
    53405448          <code>IHostDVDDrive</code>, <code>IFloppyImage</code> and
    … …  
    53475455          <para><code>IMachine::attachHardDisk</code> and similar methods have
    53485456          been renamed and generalized to deal with any type of drive and
    5349           medium. <xref linkend="IMachine__attachDevice"
    5350           xreflabel="IMachine::attachDevice()" /> is the API method for adding
    5351           any drive to a storage controller. The floppy and DVD/CD drives are
    5352           no longer handled specially, and that means you can have more than
    5353           one of them. As before, drives can only be changed while the VM is
    5354           powered off. Mounting (or unmounting) removable media at runtime is
    5355           possible with <xref linkend="IMachine__mountMedium"
    5356           xreflabel="IMachine::mountMedium()" />.</para>
     5457          medium.
     5458          <link linkend="IMachine__attachDevice">IMachine::attachDevice()</link>
     5459          is the API method for adding any drive to a storage controller. The
     5460          floppy and DVD/CD drives are no longer handled specially, and that
     5461          means you can have more than one of them. As before, drives can only
     5462          be changed while the VM is powered off. Mounting (or unmounting)
     5463          removable media at runtime is possible with
     5464          <link linkend="IMachine__mountMedium">IMachine::mountMedium()</link>.</para>
    53575465
    53585466          <para>Newly created virtual machines have no storage controllers
    … …  
    53725480
    53735481        <listitem>
    5374           <para>Reading the <xref linkend="IMedium__state"
    5375           xreflabel="IMedium::state" /> attribute no longer
    5376           automatically performs an accessibility check; a new method <xref
    5377           linkend="IMedium__refreshState"
    5378           xreflabel="IMedium::refreshState()" /> does this. The attribute only
    5379           returns the state any more.</para>
     5482          <para>Reading the
     5483          <link linkend="IMedium__state">IMedium::state</link> attribute no
     5484          longer automatically performs an accessibility check; a new method
     5485          <link linkend="IMedium__refreshState">IMedium::refreshState()</link>
     5486          does this. The attribute only returns the state now.</para>
    53805487        </listitem>
    53815488
    … …  
    53875494          IConsole::discardCurrentState and
    53885495          IConsole::discardCurrentSnapshotAndState were removed; corresponding
    5389           new functionality is in <computeroutput>IConsole::restoreSnapshot()</computeroutput>.
     5496          new functionality is in
     5497          <computeroutput>IConsole::restoreSnapshot()</computeroutput>.
    53905498          Also, when <computeroutput>IConsole::takeSnapshot()</computeroutput>
    53915499          is called on a running virtual machine, a live snapshot will be
    … …  
    54185526          modified:<itemizedlist>
    54195527              <listitem>
    5420                 <para><xref linkend="IHost__removeHostOnlyNetworkInterface"
    5421                 xreflabel="IHost::removeHostOnlyNetworkInterface()" /></para>
    5422               </listitem>
    5423 
    5424               <listitem>
    5425                 <para><xref linkend="IHost__removeUSBDeviceFilter"
    5426                 xreflabel="IHost::removeUSBDeviceFilter()" /></para>
     5528                <para><link linkend="IHost__removeHostOnlyNetworkInterface">IHost::removeHostOnlyNetworkInterface()</link></para>
     5529              </listitem>
     5530
     5531              <listitem>
     5532                <para><link linkend="IHost__removeUSBDeviceFilter">IHost::removeUSBDeviceFilter()</link></para>
    54275533              </listitem>
    54285534            </itemizedlist></para>
    … …  
    54485554          casting is no longer needed to call methods from a parent class. In
    54495555          particular, IHardDisk and other classes now properly derive from
    5450           <xref linkend="IMedium" xreflabel="IMedium" />.</para>
     5556          <link linkend="IMedium">IMedium</link>.</para>
    54515557        </listitem>
    54525558
    … …  
    54785584
    54795585        <listitem>
    5480           <para>The type of <xref linkend="IVirtualBoxErrorInfo__resultCode"
    5481           xreflabel="IVirtualBoxErrorInfo::resultCode" /> changed from
     5586          <para>The type of
     5587          <link linkend="IVirtualBoxErrorInfo__resultCode">IVirtualBoxErrorInfo::resultCode</link>
     5588          changed from
    54825589          <computeroutput>result</computeroutput> to
    54835590          <computeroutput>long</computeroutput>.</para>
    … …  
    54955602
    54965603        <listitem>
    5497           <para>The method IConsole::powerDownAsync was renamed to <xref
    5498           linkend="IConsole__powerDown" xreflabel="IConsole::powerDown" />,
     5604          <para>The method IConsole::powerDownAsync was renamed to
     5605          <link linkend="IConsole__powerDown">IConsole::powerDown</link>,
    54995606          and the previous method with that name was deleted. So effectively a
    55005607          parameter was added.</para>
    … …  
    55025609
    55035610        <listitem>
    5504           <para>In the <xref linkend="IFramebuffer"
    5505           xreflabel="IFramebuffer" /> interface, the following were
    5506           removed:<itemizedlist>
     5611          <para>In the
     5612          <link linkend="IFramebuffer">IFramebuffer</link> interface, the
     5613          following were removed:<itemizedlist>
    55075614              <listitem>
    55085615                <para>the <computeroutput>operationSupported</computeroutput>
    … …  
    55275634
    55285635        <listitem>
    5529           <para>In the <xref linkend="IDisplay" xreflabel="IDisplay" />
     5636          <para>In the <link linkend="IDisplay">IDisplay</link>
    55305637          interface, the following were removed:<itemizedlist>
    55315638              <listitem>
    … …  
    56405747            <listitem>
    56415748              <para>The HostNetworkInterfaceType enum has been renamed to
    5642               <xref linkend="HostNetworkInterfaceMediumType"
    5643               xreflabel="HostNetworkInterfaceMediumType" /></para>
     5749              <link linkend="HostNetworkInterfaceMediumType">HostNetworkInterfaceMediumType</link></para>
    56445750            </listitem>
    56455751
    56465752            <listitem>
    56475753              <para>The IHostNetworkInterface::type attribute has been renamed
    5648               to <xref linkend="IHostNetworkInterface__mediumType"
    5649               xreflabel="IHostNetworkInterface::mediumType" /></para>
     5754              to
     5755              <link linkend="IHostNetworkInterface__mediumType">IHostNetworkInterface::mediumType</link></para>
    56505756            </listitem>
    56515757
    … …  
    56575763            <listitem>
    56585764              <para>In the IHost interface, createHostNetworkInterface() has
    5659               been renamed to <xref
    5660               linkend="IHost__createHostOnlyNetworkInterface"
    5661               xreflabel="createHostOnlyNetworkInterface()" /></para>
     5765              been renamed to
     5766              <link linkend="IHost__createHostOnlyNetworkInterface">createHostOnlyNetworkInterface()</link></para>
    56625767            </listitem>
    56635768
    56645769            <listitem>
    56655770              <para>Similarly, removeHostNetworkInterface() has been renamed
    5666               to <xref linkend="IHost__removeHostOnlyNetworkInterface"
    5667               xreflabel="removeHostOnlyNetworkInterface()" /></para>
     5771              to
     5772              <link linkend="IHost__removeHostOnlyNetworkInterface">removeHostOnlyNetworkInterface()</link></para>
    56685773            </listitem>
    56695774          </itemizedlist>
    … …  
    57075812              the back-end that is in use for a particular hard disk image.
    57085813              ISystemProperties::hardDiskFormats[] contains a list of all
    5709               back-ends supported by the system. <xref
    5710               linkend="ISystemProperties__defaultHardDiskFormat"
    5711               xreflabel="ISystemProperties::defaultHardDiskFormat" /> contains
    5712               the default system format.</para>
    5713             </listitem>
    5714 
    5715             <listitem>
    5716               <para>In addition, the new <xref linkend="IMedium"
    5717               xreflabel="IMedium" /> interface is a generic interface for hard
    5718               disk, DVD and floppy images that contains the attributes and
    5719               methods shared between them. It can be considered a parent class
    5720               of the more specific interfaces for those images, which are now
    5721               IHardDisk2, IDVDImage2 and IFloppyImage2.</para>
     5814              back-ends supported by the system.
     5815              <link linkend="ISystemProperties__defaultHardDiskFormat">ISystemProperties::defaultHardDiskFormat</link>
     5816              contains the default system format.</para>
     5817            </listitem>
     5818
     5819            <listitem>
     5820              <para>In addition, the new
     5821              <link linkend="IMedium">IMedium</link> interface is a generic
     5822              interface for hard disk, DVD and floppy images that contains the
     5823              attributes and methods shared between them. It can be considered
     5824              a parent class of the more specific interfaces for those images,
     5825              which are now IHardDisk2, IDVDImage2 and IFloppyImage2.</para>
    57225826
    57235827              <para>In each case, the "2" versions of these interfaces replace
    … …  
    57435847
    57445848        <listitem>
    5745           <para><xref linkend="IGuestOSType" xreflabel="IGuestOSType" /> was
     5849          <para><link linkend="IGuestOSType">IGuestOSType</link> was
    57465850          extended to group operating systems into families and for 64-bit
    57475851          support.</para>
    … …  
    57495853
    57505854        <listitem>
    5751           <para>The <xref linkend="IHostNetworkInterface"
    5752           xreflabel="IHostNetworkInterface" /> interface was completely
    5753           rewritten to account for the changes in how Host Interface
    5754           Networking is now implemented in VirtualBox 2.1.</para>
     5855          <para>The
     5856          <link linkend="IHostNetworkInterface">IHostNetworkInterface</link>
     5857          interface was completely rewritten to account for the changes in how
     5858          Host Interface Networking is now implemented in VirtualBox
     5859          2.1.</para>
    57555860        </listitem>
    57565861
    … …  
    57615866
    57625867        <listitem>
    5763           <para>Added <xref linkend="IHost__getProcessorFeature"
    5764           xreflabel="IHost::getProcessorFeature()" /> and <xref
    5765           linkend="ProcessorFeature" xreflabel="ProcessorFeature" />
     5868          <para>Added
     5869          <link linkend="IHost__getProcessorFeature">IHost::getProcessorFeature()</link>
     5870          and <link linkend="ProcessorFeature">ProcessorFeature</link>
    57665871          enumeration.</para>
    57675872        </listitem>
    57685873
    57695874        <listitem>
    5770           <para>The parameter list for <xref
    5771           linkend="IVirtualBox__createMachine"
    5772           xreflabel="IVirtualBox::createMachine()" /> was modified.</para>
     5875          <para>The parameter list for
     5876          <link linkend="IVirtualBox__createMachine">IVirtualBox::createMachine()</link>
     5877          was modified.</para>
    57735878        </listitem>
    57745879
    … …  
    57785883
    57795884        <listitem>
    5780           <para>New attributes in IMachine: <xref
    5781           linkend="IMachine__accelerate3DEnabled"
    5782           xreflabel="accelerate3DEnabled" />, HWVirtExVPIDEnabled,
    5783           <computeroutput>IMachine::guestPropertyNotificationPatterns</computeroutput>, <xref
    5784           linkend="IMachine__CPUCount" xreflabel="CPUCount" />.</para>
    5785         </listitem>
    5786 
    5787         <listitem>
    5788           <para>Added <xref linkend="IConsole__powerUpPaused"
    5789           xreflabel="IConsole::powerUpPaused()" /> and <xref
    5790           linkend="IConsole__getGuestEnteredACPIMode"
    5791           xreflabel="IConsole::getGuestEnteredACPIMode()" />.</para>
     5885          <para>New attributes in IMachine:
     5886          <link linkend="IMachine__accelerate3DEnabled">accelerate3DEnabled</link>,
     5887          HWVirtExVPIDEnabled,
     5888          <computeroutput>IMachine::guestPropertyNotificationPatterns</computeroutput>,
     5889          <link linkend="IMachine__CPUCount">CPUCount</link>.</para>
     5890        </listitem>
     5891
     5892        <listitem>
     5893          <para>Added
     5894          <link linkend="IConsole__powerUpPaused">IConsole::powerUpPaused()</link>
     5895          and
     5896          <link linkend="IConsole__getGuestEnteredACPIMode">IConsole::getGuestEnteredACPIMode()</link>.</para>
    57925897        </listitem>
    57935898

  • trunk/doc/manual/xidl2docbook.xsl

    r46213 r56532  
    66        VirtualBox.xidl.
    77
    8     Copyright (C) 2006-2012 Oracle Corporation
     8    Copyright (C) 2006-2015 Oracle Corporation
    99
    1010    This file is part of VirtualBox Open Source Edition (OSE), as
    … …  
    5454      <xsl:choose>
    5555        <xsl:when test="//interface[@name=$type]">
    56           <xref>
    57             <xsl:attribute name="apiref">yes</xsl:attribute>
     56          <link>
    5857            <xsl:attribute name="linkend">
    5958              <xsl:value-of select="translate($type, ':', '_')" />
    6059            </xsl:attribute>
    6160            <xsl:value-of select="$type" />
    62           </xref>
     61          </link>
    6362        </xsl:when>
    6463        <xsl:when test="//enum[@name=$type]">
    65           <xref>
    66             <xsl:attribute name="apiref">yes</xsl:attribute>
     64          <link>
    6765            <xsl:attribute name="linkend">
    6866              <xsl:value-of select="translate($type, ':', '_')" />
    6967            </xsl:attribute>
    7068            <xsl:value-of select="$type" />
    71           </xref>
     69          </link>
    7270        </xsl:when>
    7371        <xsl:otherwise>
    … …  
    122120          <xsl:choose>
    123121            <xsl:when test="$wsmap='suppress'">
    124               <note>
     122              <para><note><para>
    125123                This interface is not supported in the web service.
    126               </note>
     124              </para></note></para>
    127125            </xsl:when>
    128126            <xsl:when test="$wsmap='struct'">
    129               <note>With the web service, this interface is mapped to a structure. Attributes that return this interface will not return an object, but a complete structure
    130               containing the attributes listed below as structure members.</note>
     127              <para><note><para>With the web service, this interface is mapped to a structure. Attributes that return this interface will not return an object, but a complete structure
     128              containing the attributes listed below as structure members.</para></note></para>
    131129            </xsl:when>
    132130            <xsl:when test="$wsonly='yes'">
    133               <note>This interface is supported in the web service only, not in COM/XPCOM.</note>
     131              <para><note><para>This interface is supported in the web service only, not in COM/XPCOM.</para></note></para>
    134132            </xsl:when>
    135133          </xsl:choose>
    136134
    137135          <xsl:if test="$reportExtends">
    138             <note>
     136            <para><note><para>
    139137                This interface extends
    140                 <xref>
    141                   <xsl:attribute name="apiref">yes</xsl:attribute>
     138                <link>
    142139                  <xsl:attribute name="linkend"><xsl:value-of select="$extends" /></xsl:attribute>
    143140                  <xsl:value-of select="$extends" />
    144                 </xref>
     141                </link>
    145142                and therefore supports all its methods and attributes as well.
    146             </note>
     143            </para></note></para>
    147144          </xsl:if>
    148145
    … …  
    181178                  </programlisting>
    182179                  <xsl:if test="( ($attrtype=($G_setSuppressedInterfaces/@name)) )">
    183                     <note>
     180                    <para><note><para>
    184181                      This attribute is not supported in the web service.
    185                     </note>
     182                    </para></note></para>
    186183                  </xsl:if>
    187184                  <xsl:apply-templates select="desc" />
    … …  
    209206                  <xsl:if test="   (param[@type=($G_setSuppressedInterfaces/@name)])
    210207                                or (param[@mod='ptr'])" >
    211                     <note>
     208                    <para><note><para>
    212209                      This method is not supported in the web service.
    213                     </note>
     210                    </para></note></para>
    214211                  </xsl:if>
    215212                  <!-- make a set of all parameters with in and out direction -->
    … …  
    256253                          </glossterm>
    257254                          <glossdef>
    258                             <para>
    259                               <xsl:apply-templates select="desc" />
    260                             </para>
     255                            <xsl:if test="not(desc)">
     256                              <para/>
     257                            </xsl:if>
     258                            <xsl:apply-templates select="desc" />
    261259                          </glossdef>
    262260                        </glossentry>
    … …  
    320318              </glossterm>
    321319              <glossdef>
     320                <xsl:if test="not(desc)">
     321                  <para/>
     322                </xsl:if>
    322323                <xsl:apply-templates select="desc" />
    323324              </glossdef>
    … …  
    398399
    399400<xsl:template match="desc">
     401  <!-- todo: wrapping the entire content in a single para is actually not
     402       entirely correct, as it contains empty lines denoting new paragraphs -->
     403  <para>
    400404  <xsl:apply-templates />
     405  </para>
    401406</xsl:template>
    402407
    … …  
    411416<!-- <link to="DeviceType::HardDisk"/> -->
    412417<xsl:template match="link">
    413   <xref>
    414     <xsl:attribute name="apiref">yes</xsl:attribute>
     418  <link>
    415419    <xsl:variable name="tmp" select="@to" />
    416420    <xsl:variable name="enumNameFromCombinedName">
    … …  
    493497      </xsl:otherwise>
    494498    </xsl:choose>
    495   </xref>
     499  </link>
    496500</xsl:template>
    497501
    … …  
    502506<xsl:template match="note">
    503507  <xsl:if test="not(@internal='yes')">
    504     <note>
     508    <note><para>
    505509      <xsl:apply-templates />
    506     </note>
     510    </para></note>
    507511  </xsl:if>
    508512</xsl:template>
    … …  
    545549<xsl:template match="li">
    546550  <listitem>
    547     <xsl:apply-templates />
     551    <para>
     552      <xsl:apply-templates />
     553    </para>
    548554  </listitem>
    549555</xsl:template>
Note: See TracChangeset for help on using the changeset viewer.

© 2024 Oracle Support Privacy / Do Not Sell My Info Terms of Use Trademark Policy Automated Access Etiquette