Index: trunk/src/VBox/Main/idl/VirtualBox.xidl
===================================================================
--- trunk/src/VBox/Main/idl/VirtualBox.xidl	(revision 22165)
+++ trunk/src/VBox/Main/idl/VirtualBox.xidl	(revision 22173)
@@ -347,4 +347,49 @@
 
   <enum
+       name="SettingsVersion"
+       uuid="6e151282-c338-428a-989d-5f2402d87e6f"
+       >
+      <desc>
+          Settings version of VirtualBox settings files. This is written to
+          the "version" attribute of the root "VirtualBox" element in the settings
+          file XML and indicates which VirtualBox version wrote the file.
+      </desc>
+
+      <const name="Null"    value="0">
+          <desc>Null value, indicates invalid version.</desc>
+      </const>
+      <const name="v1_0"     value="1">
+          <desc>Settings version "1.0", understood by VirtualBox 3.0 and above.</desc>
+      </const>
+      <const name="v1_1"     value="2">
+          <desc>Settings version "1.7", understood by VirtualBox 3.0 and above.</desc>
+      </const>
+      <const name="v1_2"     value="3">
+          <desc>Settings version "1.2", understood by VirtualBox 3.0 and above.</desc>
+      </const>
+      <const name="v1_3pre"  value="4">
+          <desc>Settings version "1.3pre", understood by VirtualBox 3.0 and above.</desc>
+      </const>
+      <const name="v1_3"     value="5">
+          <desc>Settings version "1.3", understood by VirtualBox 3.0 and above.</desc>
+      </const>
+      <const name="v1_4"     value="6">
+          <desc>Settings version "1.4", understood by VirtualBox 3.0 and above.</desc>
+      </const>
+      <const name="v1_5"     value="7">
+          <desc>Settings version "1.5", understood by VirtualBox 3.0 and above.</desc>
+      </const>
+      <const name="v1_6"     value="8">
+          <desc>Settings version "1.6", understood by VirtualBox 3.0 and above.</desc>
+      </const>
+      <const name="v1_7"     value="9">
+          <desc>Settings version "1.7", understood by VirtualBox 3.0 and above.</desc>
+      </const>
+      <const name="v1_8"     value="10">
+          <desc>Settings version "1.8", understood by VirtualBox 3.1 and above.</desc>
+      </const>
+  </enum>
+
+  <enum
        name="AccessMode"
        uuid="1da0007c-ddf7-4be8-bcac-d84a1558785f"
@@ -1401,60 +1446,4 @@
     </attribute>
 
-    <attribute name="settingsFileVersion" type="wstring" readonly="yes">
-      <desc>
-        Current version of the format of the global VirtualBox settings file
-        (<tt>VirtualBox.xml</tt>).
-
-        The version string has the following format:
-        <pre>
-          x.y-platform
-        </pre>
-        where @c x and @c y are the major and the minor format
-        versions, and @c platform is the platform identifier.
-
-        The current version usually matches the value of the
-        <link to="#settingsFormatVersion"/> attribute unless the
-        settings file was created by an older version of VirtualBox and there
-        was a change of the settings file format since then.
-
-        Note that VirtualBox automatically converts settings files from older
-        versions to the most recent version when reading them (usually at
-        VirtualBox startup) but it doesn't save the changes back until
-        you call a method that implicitly saves settings (such as
-        <link to="#setExtraData"/>) or call <link to="#saveSettings"/>
-        explicitly. Therefore, if the value of this attribute differs from the
-        value of <link to="#settingsFormatVersion"/>, then it
-        means that the settings file was converted but the result of the
-        conversion is not yet saved to disk.
-
-        The above feature may be used by interactive front-ends to inform users
-        about the settings file format change and offer them to explicitly save
-        all converted settings files (the global and VM-specific ones),
-        optionally create backup copies of the old settings files before saving,
-        etc.
-
-        <see>settingsFormatVersion, saveSettingsWithBackup()</see>
-      </desc>
-    </attribute>
-
-    <attribute name="settingsFormatVersion" type="wstring" readonly="yes">
-      <desc>
-        Most recent version of the settings file format.
-
-        The version string has the following format:
-        <pre>
-          x.y-platform
-        </pre>
-        where @c x and @c y are the major and the minor format
-        versions, and @c platform is the platform identifier.
-
-        VirtualBox uses this version of the format when saving settings files
-        (either as a result of method calls that require to save settings or as
-        a result of an explicit call to <link to="#saveSettings"/>).
-
-        <see>settingsFileVersion</see>
-      </desc>
-    </attribute>
-
     <attribute name="host" type="IHost" readonly="yes">
       <desc>Associated host object.</desc>
@@ -2297,27 +2286,11 @@
     </method>
 
-    <method name="getNextExtraDataKey">
-      <desc>
-        Returns the global extra data key name following the supplied key.
-
-        An error is returned if the supplied @a key does not exist. An empty
-        string is returned in @a nextKey if the supplied key is the last key. When
-        supplying @c null or an empty string for the @a key, the first key item
-        is returned in @a nextKey (if there is any). @a nextValue is an optional
-        parameter and if supplied, the next key's value is returned in it.
-
-        <result name="VBOX_E_OBJECT_NOT_FOUND">
-          Extra data @a key not found.
-        </result>
-
-      </desc>
-      <param name="key" type="wstring" dir="in">
-        <desc>Name of the data key to follow.</desc>
-      </param>
-      <param name="nextKey" type="wstring" dir="out">
-        <desc>Name of the next data key.</desc>
-      </param>
-      <param name="nextValue" type="wstring" dir="out">
-        <desc>Value of the next data key.</desc>
+    <method name="getExtraDataKeys">
+      <desc>
+        Returns an array representing the global extra data keys which currently
+        have values defined.
+      </desc>
+      <param name="value" type="wstring" dir="return" safearray="yes">
+        <desc>Array of extra data keys.</desc>
       </param>
     </method>
@@ -2750,82 +2723,4 @@
       <param name="values" type="wstring" dir="out">
         <desc>Reserved, not currently used.</desc>
-      </param>
-    </method>
-
-    <method name="saveSettings">
-      <desc>
-        Saves the global settings to the global settings file
-        (<link to="#settingsFilePath"/>).
-
-        This method is only useful for explicitly saving the global settings
-        file after it has been auto-converted from the old format to the most
-        recent format (see <link to="#settingsFileVersion"/> for details).
-        Normally, the global settings file is implicitly saved when a global
-        setting is changed.
-
-        <result name="VBOX_E_FILE_ERROR">
-          Settings file not accessible.
-        </result>
-        <result name="VBOX_E_XML_ERROR">
-          Could not parse the settings file.
-        </result>
-
-      </desc>
-    </method>
-
-    <method name="saveSettingsWithBackup">
-      <desc>
-        Creates a backup copy of the global settings file
-        (<link to="IVirtualBox::settingsFilePath"/>) in case of auto-conversion,
-        and then calls <link to="IVirtualBox::saveSettings"/>.
-
-        Note that the backup copy is created <b>only</b> if the settings file
-        auto-conversion took place (see <link to="#settingsFileVersion"/> for
-        details). Otherwise, this call is fully equivalent to
-        <link to="IVirtualBox::saveSettings"/> and no backup copying is done.
-
-        The backup copy is created in the same directory where the original
-        settings file is located. It is given the following file name:
-        <pre>
-          original.xml.x.y-platform.bak
-        </pre>
-        where <tt>original.xml</tt> is the original settings file name
-        (excluding path), and <tt>x.y-platform</tt> is the version of the old
-        format of the settings file (before auto-conversion).
-
-        If the given backup file already exists, this method will try to add the
-        <tt>.N</tt> suffix to the backup file name (where @c N counts from
-        0 to 9) and copy it again until it succeeds. If all suffixes are
-        occupied, or if any other copy error occurs, this method will return a
-        failure.
-
-        If the copy operation succeeds, the @a bakFileName return argument will
-        receive a full path to the created backup file (for informational
-        purposes). Note that this will happen even if the subsequent
-        <link to="#saveSettings"/> call performed by this method after the
-        copy operation, fails.
-
-        <note>
-          The VirtualBox API never calls this method. It is intended purely for
-          the purposes of creating backup copies of the settings files by
-          front-ends before saving the results of the automatically performed
-          settings conversion to disk.
-        </note>
-
-        <see>settingsFileVersion</see>
-
-        <result name="VBOX_E_FILE_ERROR">
-          Settings file not accessible.
-        </result>
-        <result name="VBOX_E_XML_ERROR">
-          Could not parse the settings file.
-        </result>
-        <result name="VBOX_E_IPRT_ERROR">
-          Could not copy the settings file.
-        </result>
-
-      </desc>
-      <param name="bakFileName" type="wstring" dir="return">
-        <desc>Full path to the created backup copy.</desc>
       </param>
     </method>
@@ -4224,5 +4119,5 @@
         to OpenGL only. </desc>
     </attribute>
-    
+
     <attribute name="accelerate2DVideoEnabled" type="boolean" default="false">
       <desc>
@@ -4350,41 +4245,4 @@
       <desc>
         Full name of the file containing machine settings data.
-      </desc>
-    </attribute>
-
-    <attribute name="settingsFileVersion" type="wstring" readonly="yes">
-      <desc>
-        Current version of the format of the settings file of this machine
-        (<link to="IMachine::settingsFilePath"/>).
-
-        The version string has the following format:
-        <pre>
-          x.y-platform
-        </pre>
-        where @c x and @c y are the major and the minor format
-        versions, and @c platform is the platform identifier.
-
-        The current version usually matches the value of the
-        <link to="IVirtualBox::settingsFormatVersion"/> attribute unless the
-        settings file was created by an older version of VirtualBox and there
-        was a change of the settings file format since then.
-
-        Note that VirtualBox automatically converts settings files from older
-        versions to the most recent version when reading them (usually at
-        VirtualBox startup) but it doesn't save the changes back until
-        you call a method that implicitly saves settings (such as
-        <link to="#setExtraData"/>) or call <link to="#saveSettings"/>
-        explicitly. Therefore, if the value of this attribute differs from the
-        value of <link to="IVirtualBox::settingsFormatVersion"/>, then it
-        means that the settings file was converted but the result of the
-        conversion is not yet saved to disk.
-
-        The above feature may be used by interactive front-ends to inform users
-        about the settings file format change and offer them to explicitly save
-        all converted settings files (the global and VM-specific ones),
-        optionally create backup copies of the old settings files before saving,
-        etc.
-
-        <see>IVirtualBox::settingsFormatVersion, saveSettingsWithBackup()</see>
       </desc>
     </attribute>
@@ -4878,30 +4736,12 @@
     </method>
 
-    <method name="getNextExtraDataKey">
-      <desc>
-        Returns the machine-specific extra data key name following the
-        supplied key.
-
-        An error is returned if the supplied @a key does not exist. An empty
-        string is returned in @a nextKey if the supplied key is the last key.
-        When supplying @c null or an empty string for the @a key, the first key
-        item is returned in @a nextKey (if there is any). @a nextValue is an
-        optional parameter and if supplied, the next key's value is returned in
-        it.
-
-        <result name="VBOX_E_OBJECT_NOT_FOUND">
-          Extra data @a key not found.
-        </result>
-
-      </desc>
-      <param name="key" type="wstring" dir="in">
-        <desc>Name of the data key to follow.</desc>
-      </param>
-      <param name="nextKey" type="wstring" dir="out">
-        <desc>Name of the next data key.</desc>
-      </param>
-      <param name="nextValue" type="wstring" dir="out">
-        <desc>Value of the next data key.</desc>
-      </param>
+    <method name="getExtraDataKeys">
+        <desc>
+            Returns an array representing the machine-specific extra data keys
+            which currently have values defined.
+        </desc>
+        <param name="value" type="wstring" dir="return" safearray="yes">
+            <desc>Array of extra data keys.</desc>
+        </param>
     </method>
 
@@ -5003,64 +4843,4 @@
 
       </desc>
-    </method>
-
-    <method name="saveSettingsWithBackup">
-      <desc>
-        Creates a backup copy of the machine settings file (<link
-        to="IMachine::settingsFilePath"/>) in case of auto-conversion, and then calls
-        <link to="IMachine::saveSettings"/>.
-
-        Note that the backup copy is created <b>only</b> if the settings file
-        auto-conversion took place (see <link to="#settingsFileVersion"/> for
-        details). Otherwise, this call is fully equivalent to
-        <link to="IMachine::saveSettings"/> and no backup copying is done.
-
-        The backup copy is created in the same directory where the original
-        settings file is located. It is given the following file name:
-        <pre>
-          original.xml.x.y-platform.bak
-        </pre>
-        where <tt>original.xml</tt> is the original settings file name
-        (excluding path), and <tt>x.y-platform</tt> is the version of the old
-        format of the settings file (before auto-conversion).
-
-        If the given backup file already exists, this method will try to add the
-        <tt>.N</tt> suffix to the backup file name (where @c N counts from
-        0 to 9) and copy it again until it succeeds. If all suffixes are
-        occupied, or if any other copy error occurs, this method will return a
-        failure.
-
-        If the copy operation succeeds, the @a bakFileName return argument will
-        receive a full path to the created backup file (for informational
-        purposes). Note that this will happen even if the subsequent
-        <link to="#saveSettings"/> call performed by this method after the
-        copy operation, fails.
-
-        <note>
-          The VirtualBox API never calls this method. It is intended purely for
-          the purposes of creating backup copies of the settings files by
-          front-ends before saving the results of the automatically performed
-          settings conversion to disk.
-        </note>
-
-        <see>settingsFileVersion</see>
-
-        <result name="VBOX_E_FILE_ERROR">
-          Settings file not accessible.
-        </result>
-        <result name="VBOX_E_XML_ERROR">
-          Could not parse the settings file.
-        </result>
-        <result name="VBOX_E_INVALID_VM_STATE">
-          Virtual machine is not mutable.
-        </result>
-        <result name="E_ACCESSDENIED">
-          Modification request refused.
-        </result>
-
-      </desc>
-      <param name="bakFileName" type="wstring" dir="return">
-        <desc>Full path to the created backup copy.</desc>
-      </param>
     </method>
 
@@ -11895,12 +11675,28 @@
       <desc>Null value, also means "dummy audio driver".</desc>
     </const>
-    <const name="WinMM"         value="1"/>
-    <const name="OSS"           value="2"/>
-    <const name="ALSA"          value="3"/>
-    <const name="DirectSound"   value="4"/>
-    <const name="CoreAudio"     value="5"/>
-    <const name="MMPM"          value="6"/>
-    <const name="Pulse"         value="7"/>
-    <const name="SolAudio"      value="8"/>
+    <const name="WinMM"         value="1">
+        <desc>Windows multimedia (Windows hosts only).</desc>
+    </const>
+    <const name="OSS"           value="2">
+        <desc>Open Sound System (Linux hosts only).</desc>
+    </const>
+    <const name="ALSA"          value="3">
+        <desc>Advanced Linux Sound Architecture (Linux hosts only).</desc>
+    </const>
+    <const name="DirectSound"   value="4">
+        <desc>DirectSound (Windows hosts only).</desc>
+    </const>
+    <const name="CoreAudio"     value="5">
+        <desc>CoreAudio (Mac hosts only).</desc>
+    </const>
+    <const name="MMPM"          value="6">
+        <desc>Reserved for historical reasons.</desc>
+    </const>
+    <const name="Pulse"         value="7">
+        <desc>PulseAudio (Linux hosts only).</desc>
+    </const>
+    <const name="SolAudio"      value="8">
+        <desc>Solaris audio (Solaris hosts only).</desc>
+    </const>
   </enum>
 
