Changeset 7349 in vbox
- Timestamp:
- Mar 7, 2008 11:19:09 AM (17 years ago)
- Location:
- trunk/src/VBox/Main
- Files:
-
- 5 edited
-
MachineImpl.cpp (modified) (1 diff)
-
VirtualBoxImpl.cpp (modified) (2 diffs)
-
idl/VirtualBox.xidl (modified) (16 diffs)
-
include/MachineImpl.h (modified) (1 diff)
-
include/VirtualBoxImpl.h (modified) (2 diffs)
Legend:
- Unmodified
- Added
- Removed
-
trunk/src/VBox/Main/MachineImpl.cpp
r7341 r7349 2248 2248 } 2249 2249 2250 STDMETHODIMP Machine::SaveSettingsWithBackup (BSTR *aBakFileName) 2251 { 2252 if (!aBakFileName) 2253 return E_POINTER; 2254 2255 AutoCaller autoCaller (this); 2256 CheckComRCReturnRC (autoCaller.rc()); 2257 2258 /* saveSettings() needs mParent lock */ 2259 AutoMultiLock <2> alock (mParent->wlock(), this->wlock()); 2260 2261 HRESULT rc = checkStateDependency (MutableStateDep); 2262 CheckComRCReturnRC (rc); 2263 2264 /* the settings file path may never be null */ 2265 ComAssertRet (mData->mConfigFileFull, E_FAIL); 2266 2267 /* perform backup only when there was auto-conversion */ 2268 if (mData->mSettingsFileVersion != VBOX_XML_VERSION_FULL) 2269 { 2270 Bstr bakFileName; 2271 2272 HRESULT rc = VirtualBox::backupSettingsFile (mData->mConfigFileFull, 2273 mData->mSettingsFileVersion, 2274 bakFileName); 2275 CheckComRCReturnRC (rc); 2276 2277 bakFileName.cloneTo (aBakFileName); 2278 } 2279 2280 /* save all VM data excluding snapshots */ 2281 return saveSettings(); 2282 } 2283 2250 2284 STDMETHODIMP Machine::DiscardSettings() 2251 2285 { -
trunk/src/VBox/Main/VirtualBoxImpl.cpp
r7341 r7349 2145 2145 STDMETHODIMP VirtualBox::SaveSettings() 2146 2146 { 2147 AutoCaller autoCaller (this); 2148 CheckComRCReturnRC (autoCaller.rc()); 2149 2150 return saveSettings(); 2151 } 2152 2153 STDMETHODIMP VirtualBox::SaveSettingsWithBackup (BSTR *aBakFileName) 2154 { 2155 if (!aBakFileName) 2156 return E_POINTER; 2157 2158 AutoCaller autoCaller (this); 2159 CheckComRCReturnRC (autoCaller.rc()); 2160 2161 /* saveSettings() needs write lock */ 2162 AutoLock alock (this); 2163 2164 /* perform backup only when there was auto-conversion */ 2165 if (mData.mSettingsFileVersion != VBOX_XML_VERSION_FULL) 2166 { 2167 Bstr bakFileName; 2168 2169 HRESULT rc = backupSettingsFile (mData.mCfgFile.mName, 2170 mData.mSettingsFileVersion, 2171 bakFileName); 2172 CheckComRCReturnRC (rc); 2173 2174 bakFileName.cloneTo (aBakFileName); 2175 } 2176 2147 2177 return saveSettings(); 2148 2178 } … … 4266 4296 aFile.uri(), err.rc()); 4267 4297 } 4298 4299 return S_OK; 4300 } 4301 4302 /** 4303 * Creates a backup copy of the given settings file by suffixing it with the 4304 * supplied version format string and optionally with numbers from .0 to .9 4305 * if the backup file already exists. 4306 * 4307 * @param aFileName Orignal settings file name. 4308 * @param aOldFormat Version of the original format. 4309 * @param aBakFileName File name of the created backup copy (only on success). 4310 */ 4311 /* static */ 4312 HRESULT VirtualBox::backupSettingsFile (const Bstr &aFileName, 4313 const Utf8Str &aOldFormat, 4314 Bstr &aBakFileName) 4315 { 4316 Utf8Str of = aFileName; 4317 Utf8Str nf = Utf8StrFmt ("%s.%s.bak", of.raw(), aOldFormat.raw()); 4318 4319 int vrc = RTFileCopyEx (of, nf, RTFILECOPY_FLAG_NO_DENY_WRITE, 4320 NULL, NULL); 4321 4322 /* try progressive suffix from .0 to .9 on failure */ 4323 if (vrc == VERR_ALREADY_EXISTS) 4324 { 4325 Utf8Str tmp = nf; 4326 for (int i = 0; i <= 9 && RT_FAILURE (vrc); ++ i) 4327 { 4328 nf = Utf8StrFmt ("%s.%d", tmp.raw(), i); 4329 vrc = RTFileCopyEx (of, nf, RTFILECOPY_FLAG_NO_DENY_WRITE, 4330 NULL, NULL); 4331 } 4332 } 4333 4334 if (RT_FAILURE (vrc)) 4335 return setError (E_FAIL, 4336 tr ("Could not copy the settings file '%s' to '%s' (%Vrc)"), 4337 of.raw(), nf.raw(), vrc); 4338 4339 aBakFileName = nf; 4268 4340 4269 4341 return S_OK; -
trunk/src/VBox/Main/idl/VirtualBox.xidl
r7341 r7349 877 877 <interface 878 878 name="IVirtualBox" extends="$dispatched" 879 uuid=" 3d835db8-0d0b-4d3e-a83e-ed1dea86c4f5"879 uuid="2d3b9ea7-25f5-4f07-a8e1-7dd7e0dcf667" 880 880 wsmap="managed" 881 881 > … … 932 932 (<tt>VirtualBox.xml</tt>). 933 933 934 The version string has the following format: 935 <pre>x.y-platform</pre> 936 where <tt>x</tt> and <tt>y</tt> are the major and the minor format 937 versions, and <tt>platform</tt> is the platform identifier. 934 The version string has the following format: 935 <pre> 936 x.y-platform 937 </pre> 938 where <tt>x</tt> and <tt>y</tt> are the major and the minor format 939 versions, and <tt>platform</tt> is the platform identifier. 938 940 939 941 The current version usually matches the value of the … … 945 947 versions to the most recent version when reading them (usually at 946 948 VirtualBox startup) but it doesn't save the changes back until 947 948 949 950 951 952 953 954 955 956 957 958 959 960 <see>settingsFormatVersion </see>949 you call a method that implicitly saves settings (such as 950 <link to="#setExtraData()"/>) or call <link to="#saveSettings()"/> 951 explicitly. Therefore, if the value of this attribute differs from the 952 value of <link to="#settingsFormatVersion"/>, then it 953 means that the settings file was converted but the result of the 954 conversion is not yet saved to disk. 955 956 The above feature may be used by interactive front-ends to inform users 957 about the settings file format change and offer them to explicitly save 958 all converted settings files (the global and VM-specific ones), 959 optionally create bacup copies of the old settings files before saving, 960 etc. 961 962 <see>settingsFormatVersion, saveSettingsWithBackup()</see> 961 963 </desc> 962 964 </attribute> … … 966 968 Most recent version of the settings file format. 967 969 968 The version string has the following format: 969 <pre>x.y-platform</pre> 970 where <tt>x</tt> and <tt>y</tt> are the major and the minor format 971 versions, and <tt>platform</tt> is the platform identifier. 972 973 VirtualBox uses this version of the format when saving settings files 974 (either as a result of method calls that require to save settings or as 975 a result of an explicit call to <link to="#saveSettings()"/>). 976 977 <see>settingsFileVersion</see> 970 The version string has the following format: 971 <pre> 972 x.y-platform 973 </pre> 974 where <tt>x</tt> and <tt>y</tt> are the major and the minor format 975 versions, and <tt>platform</tt> is the platform identifier. 976 977 VirtualBox uses this version of the format when saving settings files 978 (either as a result of method calls that require to save settings or as 979 a result of an explicit call to <link to="#saveSettings()"/>). 980 981 <see>settingsFileVersion</see> 978 982 </desc> 979 983 </attribute> … … 1079 1083 any case, the full path to the settings file will look like: 1080 1084 <pre> 1081 <base_folder>/<machine_name>/<machine_name>.xml</pre> 1085 <base_folder>/<machine_name>/<machine_name>.xml 1086 </pre> 1082 1087 1083 1088 Optionally the UUID of the machine can be predefined. If this is … … 2102 2107 </method> 2103 2108 2109 <method name="saveSettingsWithBackup"> 2110 <desc> 2111 Creates a backup copy of the global settings file 2112 (<link to="#settingsFilePath"/>) in case of auto-conversion, and then 2113 calls <link to="#saveSettings()"/>. 2114 2115 Note that the backup copy is created <b>only</b> if the settings file 2116 auto-conversion took place (see <link to="#settingsFileVersion"/> for 2117 details). Otherwise, this call is fully equivalent to 2118 <link to="#saveSettings()"/> and no backup copying is done. 2119 2120 The backup copy is created in the same directory where the original 2121 settings file is located. It is given the following file name: 2122 <pre> 2123 original.xml.x.y-platform.bak 2124 </pre> 2125 where <tt>original.xml</tt> is the original settings file name 2126 (excluding path), and <tt>x.y-platform</tt> is the version of the old 2127 format of the settings file (before auto-conversion). 2128 2129 If the given backup file already exists, this method will try to add the 2130 <tt>.N</tt> suffix to the backup file name (where <tt>N</tt> counts from 2131 0 to 9) and copy it again until it succeeds. If all suffixes are 2132 occupied, or if any other copy error occurs, this method will return a 2133 failure. 2134 2135 If the copy operation succeeds, the @a bakFileName return argument will 2136 receive a full path to the created backup file (for informational 2137 purposes). Note that this will happen even if the subsequent 2138 <link to="#saveSettings()"/> call performed by this method after the 2139 copy operation, fails. 2140 2141 <note> 2142 The VirtualBox API never calls this method. It is intended purely for 2143 the purposes of creating backup copies of the settings files by 2144 front-ends before saving the results of the automatically performed 2145 settings conversion to disk. 2146 </note> 2147 2148 <see>settingsFileVersion</see> 2149 </desc> 2150 <param name="bakFileName" type="wstring" dir="return"> 2151 <desc>Full path to the created backup copy.</desc> 2152 </param> 2153 </method> 2154 2104 2155 </interface> 2105 2156 … … 2430 2481 <interface 2431 2482 name="IMachine" extends="$unknown" 2432 uuid=" c929abcc-5373-4ed9-9b56-201430b37868"2483 uuid="4f6b4977-95fd-40b1-8391-fc165c040635" 2433 2484 wsmap="managed" 2434 2485 > … … 2727 2778 </attribute> 2728 2779 2729 <attribute name="settingsFileVersion" type="wstring" readonly="yes"> 2730 <desc> 2731 Current version of the format of the settings file of this machine 2732 (<link to="#settingsFilePath"/>). 2733 2734 The version string has the following format: 2735 <pre>x.y-platform</pre> 2736 where <tt>x</tt> and <tt>y</tt> are the major and the minor format 2737 versions, and <tt>platform</tt> is the platform identifier. 2738 2739 The current version usually matches the value of the 2740 <link to="IVirtualBox::settingsFormatVersion"/> attribute unless the 2741 settings file was created by an older version of VirtualBox and there 2742 was a change of the settings file format since then. 2743 2744 Note that VirtualBox automatically converts settings files from older 2745 versions to the most recent version when reading them (usually at 2746 VirtualBox startup) but it doesn't save the changes back until 2747 you call a method that implicitly saves settings (such as 2748 <link to="#setExtraData()"/>) or call <link to="#saveSettings()"/> 2749 explicitly. Therefore, if the value of this attribute differs from the 2750 value of <link to="IVirtualBox::settingsFormatVersion"/>, then it 2751 means that the settings file was converted but the result of the 2752 conversion is not yet saved to disk. 2753 2754 The above feature may be used by interactive front-ends to inform users 2755 about the settings file format change and offer them to explicitly save 2756 all converted settings files (the global and VM-specific ones), 2757 optionally create bacup copies of the old settings files before saving, 2758 etc. 2759 2760 <see>IVirtualBox::settingsFormatVersion</see> 2761 </desc> 2762 </attribute> 2780 <attribute name="settingsFileVersion" type="wstring" readonly="yes"> 2781 <desc> 2782 Current version of the format of the settings file of this machine 2783 (<link to="#settingsFilePath"/>). 2784 2785 The version string has the following format: 2786 <pre> 2787 x.y-platform 2788 /pre> 2789 where <tt>x</tt> and <tt>y</tt> are the major and the minor format 2790 versions, and <tt>platform</tt> is the platform identifier. 2791 2792 The current version usually matches the value of the 2793 <link to="IVirtualBox::settingsFormatVersion"/> attribute unless the 2794 settings file was created by an older version of VirtualBox and there 2795 was a change of the settings file format since then. 2796 2797 Note that VirtualBox automatically converts settings files from older 2798 versions to the most recent version when reading them (usually at 2799 VirtualBox startup) but it doesn't save the changes back until 2800 you call a method that implicitly saves settings (such as 2801 <link to="#setExtraData()"/>) or call <link to="#saveSettings()"/> 2802 explicitly. Therefore, if the value of this attribute differs from the 2803 value of <link to="IVirtualBox::settingsFormatVersion"/>, then it 2804 means that the settings file was converted but the result of the 2805 conversion is not yet saved to disk. 2806 2807 The above feature may be used by interactive front-ends to inform users 2808 about the settings file format change and offer them to explicitly save 2809 all converted settings files (the global and VM-specific ones), 2810 optionally create bacup copies of the old settings files before saving, 2811 etc. 2812 2813 <see>IVirtualBox::settingsFormatVersion, saveSettingsWithBackup()</see> 2814 </desc> 2815 </attribute> 2763 2816 2764 2817 <attribute name="settingsModified" type="boolean" readonly="yes"> … … 2777 2830 <note> 2778 2831 For newly created unregistered machines, the value of this 2779 property is always TRUE until <link to="#saveSettings "/>2832 property is always TRUE until <link to="#saveSettings()"/> 2780 2833 is called (no matter if any machine settings have been 2781 2834 changed after the creation or not). For opened machines … … 2989 3042 <note>Attaching a hard disk to a machine creates a <i>lazy</i> 2990 3043 attachment. In particular, no differeincing images are 2991 actually created until <link to="#saveSettings "/> is called to3044 actually created until <link to="#saveSettings()"/> is called to 2992 3045 commit all changed settings.</note> 2993 3046 … … 3030 3083 detachment. In particular, if the detached hard disk is a 3031 3084 differencing hard disk, it is not actually deleted until 3032 <link to="#saveSettings "/> is called to commit all changed settings.3033 Keep in mind, that doing <link to="#saveSettings "/> will3085 <link to="#saveSettings()"/> is called to commit all changed settings. 3086 Keep in mind, that doing <link to="#saveSettings()"/> will 3034 3087 <b>physically delete</b> all detached differencing hard disks, 3035 3088 so be careful. … … 3156 3209 Saves any changes to machine settings made since the session 3157 3210 has been opened or a new machine has been created, or since the 3158 last call to <link to="#saveSettings "/> or <link to="#discardSettings"/>.3211 last call to <link to="#saveSettings()"/> or <link to="#discardSettings()"/>. 3159 3212 For registered machines, new settings become visible to all 3160 3213 other VirtualBox clients after successful invocation of this 3161 3214 method. 3162 3215 <note> 3163 The method sends <link to="IVirtualBoxCallback::onMachineDataChange "/>3216 The method sends <link to="IVirtualBoxCallback::onMachineDataChange()"/> 3164 3217 notification event after the configuration has been successfully 3165 3218 saved (only for registered machines). … … 3175 3228 </method> 3176 3229 3230 <method name="saveSettingsWithBackup"> 3231 <desc> 3232 Creates a backup copy of the machine settings file (<link 3233 to="#settingsFilePath"/>) in case of auto-conversion, and then calls 3234 <link to="#saveSettings()"/>. 3235 3236 Note that the backup copy is created <b>only</b> if the settings file 3237 auto-conversion took place (see <link to="#settingsFileVersion"/> for 3238 details). Otherwise, this call is fully equivalent to 3239 <link to="#saveSettings()"/> and no backup copying is done. 3240 3241 The backup copy is created in the same directory where the original 3242 settings file is located. It is given the following file name: 3243 <pre> 3244 original.xml.x.y-platform.bak 3245 </pre> 3246 where <tt>original.xml</tt> is the original settings file name 3247 (excluding path), and <tt>x.y-platform</tt> is the version of the old 3248 format of the settings file (before auto-conversion). 3249 3250 If the given backup file already exists, this method will try to add the 3251 <tt>.N</tt> suffix to the backup file name (where <tt>N</tt> counts from 3252 0 to 9) and copy it again until it succeeds. If all suffixes are 3253 occupied, or if any other copy error occurs, this method will return a 3254 failure. 3255 3256 If the copy operation succeeds, the @a bakFileName return argument will 3257 receive a full path to the created backup file (for informational 3258 purposes). Note that this will happen even if the subsequent 3259 <link to="#saveSettings()"/> call performed by this method after the 3260 copy operation, fails. 3261 3262 <note> 3263 The VirtualBox API never calls this method. It is intended purely for 3264 the purposes of creating backup copies of the settings files by 3265 front-ends before saving the results of the automatically performed 3266 settings conversion to disk. 3267 </note> 3268 3269 <see>settingsFileVersion</see> 3270 </desc> 3271 <param name="bakFileName" type="wstring" dir="return"> 3272 <desc>Full path to the created backup copy.</desc> 3273 </param> 3274 </method> 3275 3177 3276 <method name="discardSettings"> 3178 3277 <desc> 3179 3278 Discards any changes to the machine settings made since the session 3180 has been opened or since the last call to <link to="#saveSettings "/>3279 has been opened or since the last call to <link to="#saveSettings()"/> 3181 3280 or <link to="#discardSettings"/>. 3182 3281 <note> … … 3210 3309 <note> 3211 3310 The deleted machine settings file can be restored (saved again) 3212 by calling <link to="#saveSettings "/>.3311 by calling <link to="#saveSettings()"/>. 3213 3312 </note> 3214 3313 </desc> … … 4009 4108 <note> 4010 4109 On success, this method implicitly calls 4011 <link to="IMachine::saveSettings "/> to save all current machine4110 <link to="IMachine::saveSettings()"/> to save all current machine 4012 4111 settings (including runtime changes to the DVD drive, etc.). 4013 4112 Together with the impossibility to change any VM settings when it is … … 4163 4262 4164 4263 <note> 4165 This method implicitly calls <link to="IMachine::saveSettings "/> to4264 This method implicitly calls <link to="IMachine::saveSettings()"/> to 4166 4265 save all current machine settings before taking an offline snapshot. 4167 4266 </note> -
trunk/src/VBox/Main/include/MachineImpl.h
r7341 r7349 496 496 STDMETHOD(SetExtraData)(INPTR BSTR aKey, INPTR BSTR aValue); 497 497 STDMETHOD(SaveSettings)(); 498 STDMETHOD(SaveSettingsWithBackup) (BSTR *aBakFileName); 498 499 STDMETHOD(DiscardSettings)(); 499 500 STDMETHOD(DeleteSettings)(); -
trunk/src/VBox/Main/include/VirtualBoxImpl.h
r7341 r7349 183 183 184 184 STDMETHOD(SaveSettings)(); 185 STDMETHOD(SaveSettingsWithBackup) (BSTR *aBakFileName); 185 186 186 187 /* public methods only for internal purposes */ … … 329 330 settings::File &aFile, 330 331 Utf8Str &aFormatVersion); 332 333 static HRESULT backupSettingsFile (const Bstr &aFileName, 334 const Utf8Str &aOldFormat, 335 Bstr &aBakFileName); 331 336 332 337 static HRESULT handleUnexpectedExceptions (RT_SRC_POS_DECL);
Note:
See TracChangeset
for help on using the changeset viewer.
