VirtualBox

Changeset 22173 in vbox for trunk/src/VBox/Main/idl


Ignore:
Timestamp:
Aug 11, 2009 3:38:59 PM (16 years ago)
Author:
vboxsync
svn:sync-xref-src-repo-rev:
50951
Message:

Main: the big XML settings rework. Move XML reading/writing out of interface implementation code into separate layer so it can handle individual settings versions in the future.

File:
1 edited

Legend:

Unmodified
Added
Removed

  • trunk/src/VBox/Main/idl/VirtualBox.xidl

    r22165 r22173  
    347347
    348348  <enum
     349       name="SettingsVersion"
     350       uuid="6e151282-c338-428a-989d-5f2402d87e6f"
     351       >
     352      <desc>
     353          Settings version of VirtualBox settings files. This is written to
     354          the "version" attribute of the root "VirtualBox" element in the settings
     355          file XML and indicates which VirtualBox version wrote the file.
     356      </desc>
     357
     358      <const name="Null"    value="0">
     359          <desc>Null value, indicates invalid version.</desc>
     360      </const>
     361      <const name="v1_0"     value="1">
     362          <desc>Settings version "1.0", understood by VirtualBox 3.0 and above.</desc>
     363      </const>
     364      <const name="v1_1"     value="2">
     365          <desc>Settings version "1.7", understood by VirtualBox 3.0 and above.</desc>
     366      </const>
     367      <const name="v1_2"     value="3">
     368          <desc>Settings version "1.2", understood by VirtualBox 3.0 and above.</desc>
     369      </const>
     370      <const name="v1_3pre"  value="4">
     371          <desc>Settings version "1.3pre", understood by VirtualBox 3.0 and above.</desc>
     372      </const>
     373      <const name="v1_3"     value="5">
     374          <desc>Settings version "1.3", understood by VirtualBox 3.0 and above.</desc>
     375      </const>
     376      <const name="v1_4"     value="6">
     377          <desc>Settings version "1.4", understood by VirtualBox 3.0 and above.</desc>
     378      </const>
     379      <const name="v1_5"     value="7">
     380          <desc>Settings version "1.5", understood by VirtualBox 3.0 and above.</desc>
     381      </const>
     382      <const name="v1_6"     value="8">
     383          <desc>Settings version "1.6", understood by VirtualBox 3.0 and above.</desc>
     384      </const>
     385      <const name="v1_7"     value="9">
     386          <desc>Settings version "1.7", understood by VirtualBox 3.0 and above.</desc>
     387      </const>
     388      <const name="v1_8"     value="10">
     389          <desc>Settings version "1.8", understood by VirtualBox 3.1 and above.</desc>
     390      </const>
     391  </enum>
     392
     393  <enum
    349394       name="AccessMode"
    350395       uuid="1da0007c-ddf7-4be8-bcac-d84a1558785f"
    … …  
    14011446    </attribute>
    14021447
    1403     <attribute name="settingsFileVersion" type="wstring" readonly="yes">
    1404       <desc>
    1405         Current version of the format of the global VirtualBox settings file
    1406         (<tt>VirtualBox.xml</tt>).
    1407 
    1408         The version string has the following format:
    1409         <pre>
    1410           x.y-platform
    1411         </pre>
    1412         where @c x and @c y are the major and the minor format
    1413         versions, and @c platform is the platform identifier.
    1414 
    1415         The current version usually matches the value of the
    1416         <link to="#settingsFormatVersion"/> attribute unless the
    1417         settings file was created by an older version of VirtualBox and there
    1418         was a change of the settings file format since then.
    1419 
    1420         Note that VirtualBox automatically converts settings files from older
    1421         versions to the most recent version when reading them (usually at
    1422         VirtualBox startup) but it doesn't save the changes back until
    1423         you call a method that implicitly saves settings (such as
    1424         <link to="#setExtraData"/>) or call <link to="#saveSettings"/>
    1425         explicitly. Therefore, if the value of this attribute differs from the
    1426         value of <link to="#settingsFormatVersion"/>, then it
    1427         means that the settings file was converted but the result of the
    1428         conversion is not yet saved to disk.
    1429 
    1430         The above feature may be used by interactive front-ends to inform users
    1431         about the settings file format change and offer them to explicitly save
    1432         all converted settings files (the global and VM-specific ones),
    1433         optionally create backup copies of the old settings files before saving,
    1434         etc.
    1435 
    1436         <see>settingsFormatVersion, saveSettingsWithBackup()</see>
    1437       </desc>
    1438     </attribute>
    1439 
    1440     <attribute name="settingsFormatVersion" type="wstring" readonly="yes">
    1441       <desc>
    1442         Most recent version of the settings file format.
    1443 
    1444         The version string has the following format:
    1445         <pre>
    1446           x.y-platform
    1447         </pre>
    1448         where @c x and @c y are the major and the minor format
    1449         versions, and @c platform is the platform identifier.
    1450 
    1451         VirtualBox uses this version of the format when saving settings files
    1452         (either as a result of method calls that require to save settings or as
    1453         a result of an explicit call to <link to="#saveSettings"/>).
    1454 
    1455         <see>settingsFileVersion</see>
    1456       </desc>
    1457     </attribute>
    1458 
    14591448    <attribute name="host" type="IHost" readonly="yes">
    14601449      <desc>Associated host object.</desc>
    … …  
    22972286    </method>
    22982287
    2299     <method name="getNextExtraDataKey">
    2300       <desc>
    2301         Returns the global extra data key name following the supplied key.
    2302 
    2303         An error is returned if the supplied @a key does not exist. An empty
    2304         string is returned in @a nextKey if the supplied key is the last key. When
    2305         supplying @c null or an empty string for the @a key, the first key item
    2306         is returned in @a nextKey (if there is any). @a nextValue is an optional
    2307         parameter and if supplied, the next key's value is returned in it.
    2308 
    2309         <result name="VBOX_E_OBJECT_NOT_FOUND">
    2310           Extra data @a key not found.
    2311         </result>
    2312 
    2313       </desc>
    2314       <param name="key" type="wstring" dir="in">
    2315         <desc>Name of the data key to follow.</desc>
    2316       </param>
    2317       <param name="nextKey" type="wstring" dir="out">
    2318         <desc>Name of the next data key.</desc>
    2319       </param>
    2320       <param name="nextValue" type="wstring" dir="out">
    2321         <desc>Value of the next data key.</desc>
     2288    <method name="getExtraDataKeys">
     2289      <desc>
     2290        Returns an array representing the global extra data keys which currently
     2291        have values defined.
     2292      </desc>
     2293      <param name="value" type="wstring" dir="return" safearray="yes">
     2294        <desc>Array of extra data keys.</desc>
    23222295      </param>
    23232296    </method>
    … …  
    27502723      <param name="values" type="wstring" dir="out">
    27512724        <desc>Reserved, not currently used.</desc>
    2752       </param>
    2753     </method>
    2754 
    2755     <method name="saveSettings">
    2756       <desc>
    2757         Saves the global settings to the global settings file
    2758         (<link to="#settingsFilePath"/>).
    2759 
    2760         This method is only useful for explicitly saving the global settings
    2761         file after it has been auto-converted from the old format to the most
    2762         recent format (see <link to="#settingsFileVersion"/> for details).
    2763         Normally, the global settings file is implicitly saved when a global
    2764         setting is changed.
    2765 
    2766         <result name="VBOX_E_FILE_ERROR">
    2767           Settings file not accessible.
    2768         </result>
    2769         <result name="VBOX_E_XML_ERROR">
    2770           Could not parse the settings file.
    2771         </result>
    2772 
    2773       </desc>
    2774     </method>
    2775 
    2776     <method name="saveSettingsWithBackup">
    2777       <desc>
    2778         Creates a backup copy of the global settings file
    2779         (<link to="IVirtualBox::settingsFilePath"/>) in case of auto-conversion,
    2780         and then calls <link to="IVirtualBox::saveSettings"/>.
    2781 
    2782         Note that the backup copy is created <b>only</b> if the settings file
    2783         auto-conversion took place (see <link to="#settingsFileVersion"/> for
    2784         details). Otherwise, this call is fully equivalent to
    2785         <link to="IVirtualBox::saveSettings"/> and no backup copying is done.
    2786 
    2787         The backup copy is created in the same directory where the original
    2788         settings file is located. It is given the following file name:
    2789         <pre>
    2790           original.xml.x.y-platform.bak
    2791         </pre>
    2792         where <tt>original.xml</tt> is the original settings file name
    2793         (excluding path), and <tt>x.y-platform</tt> is the version of the old
    2794         format of the settings file (before auto-conversion).
    2795 
    2796         If the given backup file already exists, this method will try to add the
    2797         <tt>.N</tt> suffix to the backup file name (where @c N counts from
    2798         0 to 9) and copy it again until it succeeds. If all suffixes are
    2799         occupied, or if any other copy error occurs, this method will return a
    2800         failure.
    2801 
    2802         If the copy operation succeeds, the @a bakFileName return argument will
    2803         receive a full path to the created backup file (for informational
    2804         purposes). Note that this will happen even if the subsequent
    2805         <link to="#saveSettings"/> call performed by this method after the
    2806         copy operation, fails.
    2807 
    2808         <note>
    2809           The VirtualBox API never calls this method. It is intended purely for
    2810           the purposes of creating backup copies of the settings files by
    2811           front-ends before saving the results of the automatically performed
    2812           settings conversion to disk.
    2813         </note>
    2814 
    2815         <see>settingsFileVersion</see>
    2816 
    2817         <result name="VBOX_E_FILE_ERROR">
    2818           Settings file not accessible.
    2819         </result>
    2820         <result name="VBOX_E_XML_ERROR">
    2821           Could not parse the settings file.
    2822         </result>
    2823         <result name="VBOX_E_IPRT_ERROR">
    2824           Could not copy the settings file.
    2825         </result>
    2826 
    2827       </desc>
    2828       <param name="bakFileName" type="wstring" dir="return">
    2829         <desc>Full path to the created backup copy.</desc>
    28302725      </param>
    28312726    </method>
    … …  
    42244119        to OpenGL only. </desc>
    42254120    </attribute>
    4226    
     4121
    42274122    <attribute name="accelerate2DVideoEnabled" type="boolean" default="false">
    42284123      <desc>
    … …  
    43504245      <desc>
    43514246        Full name of the file containing machine settings data.
    4352       </desc>
    4353     </attribute>
    4354 
    4355     <attribute name="settingsFileVersion" type="wstring" readonly="yes">
    4356       <desc>
    4357         Current version of the format of the settings file of this machine
    4358         (<link to="IMachine::settingsFilePath"/>).
    4359 
    4360         The version string has the following format:
    4361         <pre>
    4362           x.y-platform
    4363         </pre>
    4364         where @c x and @c y are the major and the minor format
    4365         versions, and @c platform is the platform identifier.
    4366 
    4367         The current version usually matches the value of the
    4368         <link to="IVirtualBox::settingsFormatVersion"/> attribute unless the
    4369         settings file was created by an older version of VirtualBox and there
    4370         was a change of the settings file format since then.
    4371 
    4372         Note that VirtualBox automatically converts settings files from older
    4373         versions to the most recent version when reading them (usually at
    4374         VirtualBox startup) but it doesn't save the changes back until
    4375         you call a method that implicitly saves settings (such as
    4376         <link to="#setExtraData"/>) or call <link to="#saveSettings"/>
    4377         explicitly. Therefore, if the value of this attribute differs from the
    4378         value of <link to="IVirtualBox::settingsFormatVersion"/>, then it
    4379         means that the settings file was converted but the result of the
    4380         conversion is not yet saved to disk.
    4381 
    4382         The above feature may be used by interactive front-ends to inform users
    4383         about the settings file format change and offer them to explicitly save
    4384         all converted settings files (the global and VM-specific ones),
    4385         optionally create backup copies of the old settings files before saving,
    4386         etc.
    4387 
    4388         <see>IVirtualBox::settingsFormatVersion, saveSettingsWithBackup()</see>
    43894247      </desc>
    43904248    </attribute>
    … …  
    48784736    </method>
    48794737
    4880     <method name="getNextExtraDataKey">
    4881       <desc>
    4882         Returns the machine-specific extra data key name following the
    4883         supplied key.
    4884 
    4885         An error is returned if the supplied @a key does not exist. An empty
    4886         string is returned in @a nextKey if the supplied key is the last key.
    4887         When supplying @c null or an empty string for the @a key, the first key
    4888         item is returned in @a nextKey (if there is any). @a nextValue is an
    4889         optional parameter and if supplied, the next key's value is returned in
    4890         it.
    4891 
    4892         <result name="VBOX_E_OBJECT_NOT_FOUND">
    4893           Extra data @a key not found.
    4894         </result>
    4895 
    4896       </desc>
    4897       <param name="key" type="wstring" dir="in">
    4898         <desc>Name of the data key to follow.</desc>
    4899       </param>
    4900       <param name="nextKey" type="wstring" dir="out">
    4901         <desc>Name of the next data key.</desc>
    4902       </param>
    4903       <param name="nextValue" type="wstring" dir="out">
    4904         <desc>Value of the next data key.</desc>
    4905       </param>
     4738    <method name="getExtraDataKeys">
     4739        <desc>
     4740            Returns an array representing the machine-specific extra data keys
     4741            which currently have values defined.
     4742        </desc>
     4743        <param name="value" type="wstring" dir="return" safearray="yes">
     4744            <desc>Array of extra data keys.</desc>
     4745        </param>
    49064746    </method>
    49074747
    … …  
    50034843
    50044844      </desc>
    5005     </method>
    5006 
    5007     <method name="saveSettingsWithBackup">
    5008       <desc>
    5009         Creates a backup copy of the machine settings file (<link
    5010         to="IMachine::settingsFilePath"/>) in case of auto-conversion, and then calls
    5011         <link to="IMachine::saveSettings"/>.
    5012 
    5013         Note that the backup copy is created <b>only</b> if the settings file
    5014         auto-conversion took place (see <link to="#settingsFileVersion"/> for
    5015         details). Otherwise, this call is fully equivalent to
    5016         <link to="IMachine::saveSettings"/> and no backup copying is done.
    5017 
    5018         The backup copy is created in the same directory where the original
    5019         settings file is located. It is given the following file name:
    5020         <pre>
    5021           original.xml.x.y-platform.bak
    5022         </pre>
    5023         where <tt>original.xml</tt> is the original settings file name
    5024         (excluding path), and <tt>x.y-platform</tt> is the version of the old
    5025         format of the settings file (before auto-conversion).
    5026 
    5027         If the given backup file already exists, this method will try to add the
    5028         <tt>.N</tt> suffix to the backup file name (where @c N counts from
    5029         0 to 9) and copy it again until it succeeds. If all suffixes are
    5030         occupied, or if any other copy error occurs, this method will return a
    5031         failure.
    5032 
    5033         If the copy operation succeeds, the @a bakFileName return argument will
    5034         receive a full path to the created backup file (for informational
    5035         purposes). Note that this will happen even if the subsequent
    5036         <link to="#saveSettings"/> call performed by this method after the
    5037         copy operation, fails.
    5038 
    5039         <note>
    5040           The VirtualBox API never calls this method. It is intended purely for
    5041           the purposes of creating backup copies of the settings files by
    5042           front-ends before saving the results of the automatically performed
    5043           settings conversion to disk.
    5044         </note>
    5045 
    5046         <see>settingsFileVersion</see>
    5047 
    5048         <result name="VBOX_E_FILE_ERROR">
    5049           Settings file not accessible.
    5050         </result>
    5051         <result name="VBOX_E_XML_ERROR">
    5052           Could not parse the settings file.
    5053         </result>
    5054         <result name="VBOX_E_INVALID_VM_STATE">
    5055           Virtual machine is not mutable.
    5056         </result>
    5057         <result name="E_ACCESSDENIED">
    5058           Modification request refused.
    5059         </result>
    5060 
    5061       </desc>
    5062       <param name="bakFileName" type="wstring" dir="return">
    5063         <desc>Full path to the created backup copy.</desc>
    5064       </param>
    50654845    </method>
    50664846
    … …  
    1189511675      <desc>Null value, also means "dummy audio driver".</desc>
    1189611676    </const>
    11897     <const name="WinMM"         value="1"/>
    11898     <const name="OSS"           value="2"/>
    11899     <const name="ALSA"          value="3"/>
    11900     <const name="DirectSound"   value="4"/>
    11901     <const name="CoreAudio"     value="5"/>
    11902     <const name="MMPM"          value="6"/>
    11903     <const name="Pulse"         value="7"/>
    11904     <const name="SolAudio"      value="8"/>
     11677    <const name="WinMM"         value="1">
     11678        <desc>Windows multimedia (Windows hosts only).</desc>
     11679    </const>
     11680    <const name="OSS"           value="2">
     11681        <desc>Open Sound System (Linux hosts only).</desc>
     11682    </const>
     11683    <const name="ALSA"          value="3">
     11684        <desc>Advanced Linux Sound Architecture (Linux hosts only).</desc>
     11685    </const>
     11686    <const name="DirectSound"   value="4">
     11687        <desc>DirectSound (Windows hosts only).</desc>
     11688    </const>
     11689    <const name="CoreAudio"     value="5">
     11690        <desc>CoreAudio (Mac hosts only).</desc>
     11691    </const>
     11692    <const name="MMPM"          value="6">
     11693        <desc>Reserved for historical reasons.</desc>
     11694    </const>
     11695    <const name="Pulse"         value="7">
     11696        <desc>PulseAudio (Linux hosts only).</desc>
     11697    </const>
     11698    <const name="SolAudio"      value="8">
     11699        <desc>Solaris audio (Solaris hosts only).</desc>
     11700    </const>
    1190511701  </enum>
    1190611702
Note: See TracChangeset for help on using the changeset viewer.

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