settings.h@ 67180

Last change on this file since 67180 was 64541, checked in by vboxsync, 8 years ago
Main/xml/Settings.cpp: change backup file handling on version bump (better error behavior), use the same logic for version parsing on import than for loading settings, update the internal settings version string consistently, have consistent logging of settings loading, saving and export, and report XML attribute errors more precisely if possible.
Property svn:eol-style set to `native` Property svn:keywords set to `Date Revision Author Id`
File size: 38.8 KB

Line
1	/** @file
2	* Settings file data structures.
3	*
4	* These structures are created by the settings file loader and filled with values
5	* copied from the raw XML data. This was all new with VirtualBox 3.1 and allows us
6	* to finally make the XML reader version-independent and read VirtualBox XML files
7	* from earlier and even newer (future) versions without requiring complicated,
8	* tedious and error-prone XSLT conversions.
9	*
10	* It is this file that defines all structures that map VirtualBox global and
11	* machine settings to XML files. These structures are used by the rest of Main,
12	* even though this header file does not require anything else in Main.
13	*
14	* Note: Headers in Main code have been tweaked to only declare the structures
15	* defined here so that this header need only be included from code files that
16	* actually use these structures.
17	*/
18
19	/*
20	* Copyright (C) 2007-2016 Oracle Corporation
21	*
22	* This file is part of VirtualBox Open Source Edition (OSE), as
23	* available from http://www.virtualbox.org. This file is free software;
24	* you can redistribute it and/or modify it under the terms of the GNU
25	* General Public License (GPL) as published by the Free Software
26	* Foundation, in version 2 as it comes in the "COPYING" file of the
27	* VirtualBox OSE distribution. VirtualBox OSE is distributed in the
28	* hope that it will be useful, but WITHOUT ANY WARRANTY of any kind.
29	*
30	* The contents of this file may alternatively be used under the terms
31	* of the Common Development and Distribution License Version 1.0
32	* (CDDL) only, as it comes in the "COPYING.CDDL" file of the
33	* VirtualBox OSE distribution, in which case the provisions of the
34	* CDDL are applicable instead of those of the GPL.
35	*
36	* You may elect to license modified versions of this file under the
37	* terms and conditions of either the GPL or the CDDL or both.
38	*/
39
40	#ifndef ___VBox_settings_h
41	#define ___VBox_settings_h
42
43	#include <iprt/time.h>
44
45	#include "VBox/com/VirtualBox.h"
46
47	#include <VBox/com/Guid.h>
48	#include <VBox/com/string.h>
49
50	#include <list>
51	#include <map>
52	#include <vector>
53
54	/**
55	* Maximum depth of a medium tree, to prevent stack overflows.
56	* XPCOM has a relatively low stack size for its workers, and we have
57	* to avoid crashes due to exceeding the limit both on reading and
58	* writing config files.
59	*/
60	#define SETTINGS_MEDIUM_DEPTH_MAX 300
61
62	/**
63	* Maximum depth of the snapshot tree, to prevent stack overflows.
64	* XPCOM has a relatively low stack size for its workers, and we have
65	* to avoid crashes due to exceeding the limit both on reading and
66	* writing config files. The bottleneck is reading config files with
67	* deep snapshot nesting, as libxml2 needs quite some stack space,
68	* so with the current stack size the margin isn't big.
69	*/
70	#define SETTINGS_SNAPSHOT_DEPTH_MAX 250
71
72	namespace xml
73	{
74	class ElementNode;
75	}
76
77	namespace settings
78	{
79
80	class ConfigFileError;
81
82	////////////////////////////////////////////////////////////////////////////////
83	//
84	// Structures shared between Machine XML and VirtualBox.xml
85	//
86	////////////////////////////////////////////////////////////////////////////////
87
88	typedef std::map<com::Utf8Str, com::Utf8Str> StringsMap;
89	typedef std::list<com::Utf8Str> StringsList;
90
91	/**
92	* USB device filter definition. This struct is used both in MainConfigFile
93	* (for global USB filters) and MachineConfigFile (for machine filters).
94	*
95	* NOTE: If you add any fields in here, you must update a) the constructor and b)
96	* the operator== which is used by MachineConfigFile::operator==(), or otherwise
97	* your settings might never get saved.
98	*/
99	struct USBDeviceFilter
100	{
101	USBDeviceFilter();
102
103	bool operator==(const USBDeviceFilter&u) const;
104
105	com::Utf8Str strName;
106	bool fActive;
107	com::Utf8Str strVendorId,
108	strProductId,
109	strRevision,
110	strManufacturer,
111	strProduct,
112	strSerialNumber,
113	strPort;
114	USBDeviceFilterAction_T action; // only used with host USB filters
115	com::Utf8Str strRemote; // irrelevant for host USB objects
116	uint32_t ulMaskedInterfaces; // irrelevant for host USB objects
117	};
118
119	typedef std::list<USBDeviceFilter> USBDeviceFiltersList;
120
121	struct Medium;
122	typedef std::list<Medium> MediaList;
123
124	/**
125	* NOTE: If you add any fields in here, you must update a) the constructor and b)
126	* the operator== which is used by MachineConfigFile::operator==(), or otherwise
127	* your settings might never get saved.
128	*/
129	struct Medium
130	{
131	Medium();
132
133	bool operator==(const Medium &m) const;
134
135	com::Guid uuid;
136	com::Utf8Str strLocation;
137	com::Utf8Str strDescription;
138
139	// the following are for hard disks only:
140	com::Utf8Str strFormat;
141	bool fAutoReset; // optional, only for diffs, default is false
142	StringsMap properties;
143	MediumType_T hdType;
144
145	MediaList llChildren; // only used with hard disks
146
147	static const struct Medium Empty;
148	};
149
150	/**
151	* A media registry. Starting with VirtualBox 3.3, this can appear in both the
152	* VirtualBox.xml file as well as machine XML files with settings version 1.11
153	* or higher, so these lists are now in ConfigFileBase.
154	*
155	* NOTE: If you add any fields in here, you must update a) the constructor and b)
156	* the operator== which is used by MachineConfigFile::operator==(), or otherwise
157	* your settings might never get saved.
158	*/
159	struct MediaRegistry
160	{
161	bool operator==(const MediaRegistry &m) const;
162
163	MediaList llHardDisks,
164	llDvdImages,
165	llFloppyImages;
166	};
167
168	/**
169	* NOTE: If you add any fields in here, you must update a) the constructor and b)
170	* the operator== which is used by MachineConfigFile::operator==(), or otherwise
171	* your settings might never get saved.
172	*/
173	struct NATRule
174	{
175	NATRule();
176
177	bool operator==(const NATRule &r) const;
178
179	com::Utf8Str strName;
180	NATProtocol_T proto;
181	uint16_t u16HostPort;
182	com::Utf8Str strHostIP;
183	uint16_t u16GuestPort;
184	com::Utf8Str strGuestIP;
185	};
186	typedef std::map<com::Utf8Str, NATRule> NATRulesMap;
187
188	struct NATHostLoopbackOffset
189	{
190	NATHostLoopbackOffset();
191
192	bool operator==(const NATHostLoopbackOffset &o) const;
193
194	bool operator==(const com::Utf8Str& strAddr)
195	{
196	return strLoopbackHostAddress == strAddr;
197	}
198
199	bool operator==(uint32_t off)
200	{
201	return u32Offset == off;
202	}
203
204	/** Note: 128/8 is only acceptable */
205	com::Utf8Str strLoopbackHostAddress;
206	uint32_t u32Offset;
207	};
208
209	typedef std::list<NATHostLoopbackOffset> NATLoopbackOffsetList;
210
211	typedef std::vector<uint8_t> IconBlob;
212
213	/**
214	* Common base class for both MainConfigFile and MachineConfigFile
215	* which contains some common logic for both.
216	*/
217	class ConfigFileBase
218	{
219	public:
220	bool fileExists();
221
222	void copyBaseFrom(const ConfigFileBase &b);
223
224	protected:
225	ConfigFileBase(const com::Utf8Str *pstrFilename);
226	/* Note: this copy constructor doesn't create a full copy of other, cause
227	* the file based stuff (xml doc) could not be copied. */
228	ConfigFileBase(const ConfigFileBase &other);
229
230	~ConfigFileBase();
231
232	typedef enum {Error, HardDisk, DVDImage, FloppyImage} MediaType;
233
234	static const char *stringifyMediaType(MediaType t);
235	SettingsVersion_T parseVersion(const com::Utf8Str &strVersion,
236	const xml::ElementNode *pElm);
237	void parseUUID(com::Guid &guid,
238	const com::Utf8Str &strUUID,
239	const xml::ElementNode *pElm) const;
240	void parseTimestamp(RTTIMESPEC &timestamp,
241	const com::Utf8Str &str,
242	const xml::ElementNode *pElm) const;
243	void parseBase64(IconBlob &binary,
244	const com::Utf8Str &str,
245	const xml::ElementNode *pElm) const;
246	com::Utf8Str stringifyTimestamp(const RTTIMESPEC &tm) const;
247	void toBase64(com::Utf8Str &str,
248	const IconBlob &binary) const;
249
250	void readExtraData(const xml::ElementNode &elmExtraData,
251	StringsMap &map);
252	void readUSBDeviceFilters(const xml::ElementNode &elmDeviceFilters,
253	USBDeviceFiltersList &ll);
254	void readMediumOne(MediaType t, const xml::ElementNode &elmMedium, Medium &med);
255	void readMedium(MediaType t, uint32_t depth, const xml::ElementNode &elmMedium, Medium &med);
256	void readMediaRegistry(const xml::ElementNode &elmMediaRegistry, MediaRegistry &mr);
257	void readNATForwardRulesMap(const xml::ElementNode &elmParent, NATRulesMap &mapRules);
258	void readNATLoopbacks(const xml::ElementNode &elmParent, NATLoopbackOffsetList &llLoopBacks);
259
260	void setVersionAttribute(xml::ElementNode &elm);
261	void specialBackupIfFirstBump();
262	void createStubDocument();
263
264	void buildExtraData(xml::ElementNode &elmParent, const StringsMap &me);
265	void buildUSBDeviceFilters(xml::ElementNode &elmParent,
266	const USBDeviceFiltersList &ll,
267	bool fHostMode);
268	void buildMedium(MediaType t,
269	uint32_t depth,
270	xml::ElementNode &elmMedium,
271	const Medium &mdm);
272	void buildMediaRegistry(xml::ElementNode &elmParent,
273	const MediaRegistry &mr);
274	void buildNATForwardRulesMap(xml::ElementNode &elmParent, const NATRulesMap &mapRules);
275	void buildNATLoopbacks(xml::ElementNode &elmParent, const NATLoopbackOffsetList &natLoopbackList);
276	void clearDocument();
277
278	struct Data;
279	Data *m;
280
281	friend class ConfigFileError;
282	};
283
284	////////////////////////////////////////////////////////////////////////////////
285	//
286	// VirtualBox.xml structures
287	//
288	////////////////////////////////////////////////////////////////////////////////
289
290	struct USBDeviceSource
291	{
292	com::Utf8Str strName;
293	com::Utf8Str strBackend;
294	com::Utf8Str strAddress;
295	StringsMap properties;
296	};
297
298	typedef std::list<USBDeviceSource> USBDeviceSourcesList;
299
300	struct Host
301	{
302	USBDeviceFiltersList llUSBDeviceFilters;
303	USBDeviceSourcesList llUSBDeviceSources;
304	};
305
306	struct SystemProperties
307	{
308	SystemProperties();
309
310	com::Utf8Str strDefaultMachineFolder;
311	com::Utf8Str strDefaultHardDiskFolder;
312	com::Utf8Str strDefaultHardDiskFormat;
313	com::Utf8Str strVRDEAuthLibrary;
314	com::Utf8Str strWebServiceAuthLibrary;
315	com::Utf8Str strDefaultVRDEExtPack;
316	com::Utf8Str strAutostartDatabasePath;
317	com::Utf8Str strDefaultAdditionsISO;
318	com::Utf8Str strDefaultFrontend;
319	com::Utf8Str strLoggingLevel;
320	uint32_t ulLogHistoryCount;
321	bool fExclusiveHwVirt;
322	};
323
324	struct MachineRegistryEntry
325	{
326	com::Guid uuid;
327	com::Utf8Str strSettingsFile;
328	};
329
330	typedef std::list<MachineRegistryEntry> MachinesRegistry;
331
332	struct DhcpOptValue
333	{
334	DhcpOptValue();
335	DhcpOptValue(const com::Utf8Str &aText, DhcpOptEncoding_T aEncoding = DhcpOptEncoding_Legacy);
336
337	com::Utf8Str text;
338	DhcpOptEncoding_T encoding;
339	};
340
341	typedef std::map<DhcpOpt_T, DhcpOptValue> DhcpOptionMap;
342	typedef DhcpOptionMap::value_type DhcpOptValuePair;
343	typedef DhcpOptionMap::iterator DhcpOptIterator;
344	typedef DhcpOptionMap::const_iterator DhcpOptConstIterator;
345
346	typedef struct VmNameSlotKey
347	{
348	VmNameSlotKey(const com::Utf8Str& aVmName, LONG aSlot);
349
350	bool operator<(const VmNameSlotKey& that) const;
351
352	const com::Utf8Str VmName;
353	LONG Slot;
354	} VmNameSlotKey;
355
356	typedef std::map<VmNameSlotKey, DhcpOptionMap> VmSlot2OptionsMap;
357	typedef VmSlot2OptionsMap::value_type VmSlot2OptionsPair;
358	typedef VmSlot2OptionsMap::iterator VmSlot2OptionsIterator;
359	typedef VmSlot2OptionsMap::const_iterator VmSlot2OptionsConstIterator;
360
361	struct DHCPServer
362	{
363	DHCPServer();
364
365	com::Utf8Str strNetworkName,
366	strIPAddress,
367	strIPLower,
368	strIPUpper;
369	bool fEnabled;
370	DhcpOptionMap GlobalDhcpOptions;
371	VmSlot2OptionsMap VmSlot2OptionsM;
372	};
373
374	typedef std::list<DHCPServer> DHCPServersList;
375
376
377	/**
378	* NAT Networking settings (NAT service).
379	*/
380	struct NATNetwork
381	{
382	NATNetwork();
383
384	com::Utf8Str strNetworkName;
385	com::Utf8Str strIPv4NetworkCidr;
386	com::Utf8Str strIPv6Prefix;
387	bool fEnabled;
388	bool fIPv6Enabled;
389	bool fAdvertiseDefaultIPv6Route;
390	bool fNeedDhcpServer;
391	uint32_t u32HostLoopback6Offset;
392	NATLoopbackOffsetList llHostLoopbackOffsetList;
393	NATRulesMap mapPortForwardRules4;
394	NATRulesMap mapPortForwardRules6;
395	};
396
397	typedef std::list<NATNetwork> NATNetworksList;
398
399
400	class MainConfigFile : public ConfigFileBase
401	{
402	public:
403	MainConfigFile(const com::Utf8Str *pstrFilename);
404
405	void readMachineRegistry(const xml::ElementNode &elmMachineRegistry);
406	void readDHCPServers(const xml::ElementNode &elmDHCPServers);
407	void readDhcpOptions(DhcpOptionMap& map, const xml::ElementNode& options);
408	void readNATNetworks(const xml::ElementNode &elmNATNetworks);
409
410	void write(const com::Utf8Str strFilename);
411
412	Host host;
413	SystemProperties systemProperties;
414	MediaRegistry mediaRegistry;
415	MachinesRegistry llMachines;
416	DHCPServersList llDhcpServers;
417	NATNetworksList llNATNetworks;
418	StringsMap mapExtraDataItems;
419
420	private:
421	void bumpSettingsVersionIfNeeded();
422	void buildUSBDeviceSources(xml::ElementNode &elmParent, const USBDeviceSourcesList &ll);
423	void readUSBDeviceSources(const xml::ElementNode &elmDeviceSources, USBDeviceSourcesList &ll);
424	};
425
426	////////////////////////////////////////////////////////////////////////////////
427	//
428	// Machine XML structures
429	//
430	////////////////////////////////////////////////////////////////////////////////
431
432	/**
433	* NOTE: If you add any fields in here, you must update a) the constructor and b)
434	* the operator== which is used by MachineConfigFile::operator==(), or otherwise
435	* your settings might never get saved.
436	*/
437	struct VRDESettings
438	{
439	VRDESettings();
440
441	bool areDefaultSettings(SettingsVersion_T sv) const;
442
443	bool operator==(const VRDESettings& v) const;
444
445	bool fEnabled;
446	AuthType_T authType;
447	uint32_t ulAuthTimeout;
448	com::Utf8Str strAuthLibrary;
449	bool fAllowMultiConnection,
450	fReuseSingleConnection;
451	com::Utf8Str strVrdeExtPack;
452	StringsMap mapProperties;
453	};
454
455	/**
456	* NOTE: If you add any fields in here, you must update a) the constructor and b)
457	* the operator== which is used by MachineConfigFile::operator==(), or otherwise
458	* your settings might never get saved.
459	*/
460	struct BIOSSettings
461	{
462	BIOSSettings();
463
464	bool areDefaultSettings() const;
465
466	bool operator==(const BIOSSettings &d) const;
467
468	bool fACPIEnabled,
469	fIOAPICEnabled,
470	fLogoFadeIn,
471	fLogoFadeOut,
472	fPXEDebugEnabled;
473	uint32_t ulLogoDisplayTime;
474	BIOSBootMenuMode_T biosBootMenuMode;
475	APICMode_T apicMode; // requires settings version 1.16 (VirtualBox 5.1)
476	int64_t llTimeOffset;
477	com::Utf8Str strLogoImagePath;
478	};
479
480	/**
481	* NOTE: If you add any fields in here, you must update a) the constructor and b)
482	* the operator== which is used by MachineConfigFile::operator==(), or otherwise
483	* your settings might never get saved.
484	*/
485	struct USBController
486	{
487	USBController();
488
489	bool operator==(const USBController &u) const;
490
491	com::Utf8Str strName;
492	USBControllerType_T enmType;
493	};
494
495	typedef std::list<USBController> USBControllerList;
496
497	struct USB
498	{
499	USB();
500
501	bool operator==(const USB &u) const;
502
503	/** List of USB controllers present. */
504	USBControllerList llUSBControllers;
505	/** List of USB device filters. */
506	USBDeviceFiltersList llDeviceFilters;
507	};
508
509	struct NAT
510	{
511	NAT();
512
513	bool areDNSDefaultSettings() const;
514	bool areAliasDefaultSettings() const;
515	bool areTFTPDefaultSettings() const;
516	bool areDefaultSettings() const;
517
518	bool operator==(const NAT &n) const;
519
520	com::Utf8Str strNetwork;
521	com::Utf8Str strBindIP;
522	uint32_t u32Mtu;
523	uint32_t u32SockRcv;
524	uint32_t u32SockSnd;
525	uint32_t u32TcpRcv;
526	uint32_t u32TcpSnd;
527	com::Utf8Str strTFTPPrefix;
528	com::Utf8Str strTFTPBootFile;
529	com::Utf8Str strTFTPNextServer;
530	bool fDNSPassDomain;
531	bool fDNSProxy;
532	bool fDNSUseHostResolver;
533	bool fAliasLog;
534	bool fAliasProxyOnly;
535	bool fAliasUseSamePorts;
536	NATRulesMap mapRules;
537	};
538
539	/**
540	* NOTE: If you add any fields in here, you must update a) the constructor and b)
541	* the operator== which is used by MachineConfigFile::operator==(), or otherwise
542	* your settings might never get saved.
543	*/
544	struct NetworkAdapter
545	{
546	NetworkAdapter();
547
548	bool areGenericDriverDefaultSettings() const;
549	bool areDefaultSettings(SettingsVersion_T sv) const;
550	bool areDisabledDefaultSettings() const;
551
552	bool operator==(const NetworkAdapter &n) const;
553
554	uint32_t ulSlot;
555
556	NetworkAdapterType_T type;
557	bool fEnabled;
558	com::Utf8Str strMACAddress;
559	bool fCableConnected;
560	uint32_t ulLineSpeed;
561	NetworkAdapterPromiscModePolicy_T enmPromiscModePolicy;
562	bool fTraceEnabled;
563	com::Utf8Str strTraceFile;
564
565	NetworkAttachmentType_T mode;
566	NAT nat;
567	com::Utf8Str strBridgedName;
568	com::Utf8Str strHostOnlyName;
569	com::Utf8Str strInternalNetworkName;
570	com::Utf8Str strGenericDriver;
571	StringsMap genericProperties;
572	com::Utf8Str strNATNetworkName;
573	uint32_t ulBootPriority;
574	com::Utf8Str strBandwidthGroup; // requires settings version 1.13 (VirtualBox 4.2)
575	};
576
577	typedef std::list<NetworkAdapter> NetworkAdaptersList;
578
579	/**
580	* NOTE: If you add any fields in here, you must update a) the constructor and b)
581	* the operator== which is used by MachineConfigFile::operator==(), or otherwise
582	* your settings might never get saved.
583	*/
584	struct SerialPort
585	{
586	SerialPort();
587
588	bool operator==(const SerialPort &n) const;
589
590	uint32_t ulSlot;
591
592	bool fEnabled;
593	uint32_t ulIOBase;
594	uint32_t ulIRQ;
595	PortMode_T portMode;
596	com::Utf8Str strPath;
597	bool fServer;
598	};
599
600	typedef std::list<SerialPort> SerialPortsList;
601
602	/**
603	* NOTE: If you add any fields in here, you must update a) the constructor and b)
604	* the operator== which is used by MachineConfigFile::operator==(), or otherwise
605	* your settings might never get saved.
606	*/
607	struct ParallelPort
608	{
609	ParallelPort();
610
611	bool operator==(const ParallelPort &d) const;
612
613	uint32_t ulSlot;
614
615	bool fEnabled;
616	uint32_t ulIOBase;
617	uint32_t ulIRQ;
618	com::Utf8Str strPath;
619	};
620
621	typedef std::list<ParallelPort> ParallelPortsList;
622
623	/**
624	* NOTE: If you add any fields in here, you must update a) the constructor and b)
625	* the operator== which is used by MachineConfigFile::operator==(), or otherwise
626	* your settings might never get saved.
627	*/
628	struct AudioAdapter
629	{
630	AudioAdapter();
631
632	bool areDefaultSettings(SettingsVersion_T sv) const;
633
634	bool operator==(const AudioAdapter &a) const;
635
636	bool fEnabled;
637	AudioControllerType_T controllerType;
638	AudioCodecType_T codecType;
639	AudioDriverType_T driverType;
640	settings::StringsMap properties;
641	};
642
643	/**
644	* NOTE: If you add any fields in here, you must update a) the constructor and b)
645	* the operator== which is used by MachineConfigFile::operator==(), or otherwise
646	* your settings might never get saved.
647	*/
648	struct SharedFolder
649	{
650	SharedFolder();
651
652	bool operator==(const SharedFolder &a) const;
653
654	com::Utf8Str strName,
655	strHostPath;
656	bool fWritable;
657	bool fAutoMount;
658	};
659
660	typedef std::list<SharedFolder> SharedFoldersList;
661
662	/**
663	* NOTE: If you add any fields in here, you must update a) the constructor and b)
664	* the operator== which is used by MachineConfigFile::operator==(), or otherwise
665	* your settings might never get saved.
666	*/
667	struct GuestProperty
668	{
669	GuestProperty();
670
671	bool operator==(const GuestProperty &g) const;
672
673	com::Utf8Str strName,
674	strValue;
675	uint64_t timestamp;
676	com::Utf8Str strFlags;
677	};
678
679	typedef std::list<GuestProperty> GuestPropertiesList;
680
681	typedef std::map<uint32_t, DeviceType_T> BootOrderMap;
682
683	/**
684	* NOTE: If you add any fields in here, you must update a) the constructor and b)
685	* the operator== which is used by MachineConfigFile::operator==(), or otherwise
686	* your settings might never get saved.
687	*/
688	struct CpuIdLeaf
689	{
690	CpuIdLeaf();
691
692	bool operator==(const CpuIdLeaf &c) const;
693
694	uint32_t ulId;
695	uint32_t ulEax;
696	uint32_t ulEbx;
697	uint32_t ulEcx;
698	uint32_t ulEdx;
699	};
700
701	typedef std::list<CpuIdLeaf> CpuIdLeafsList;
702
703	/**
704	* NOTE: If you add any fields in here, you must update a) the constructor and b)
705	* the operator== which is used by MachineConfigFile::operator==(), or otherwise
706	* your settings might never get saved.
707	*/
708	struct Cpu
709	{
710	Cpu();
711
712	bool operator==(const Cpu &c) const;
713
714	uint32_t ulId;
715	};
716
717	typedef std::list<Cpu> CpuList;
718
719	/**
720	* NOTE: If you add any fields in here, you must update a) the constructor and b)
721	* the operator== which is used by MachineConfigFile::operator==(), or otherwise
722	* your settings might never get saved.
723	*/
724	struct BandwidthGroup
725	{
726	BandwidthGroup();
727
728	bool operator==(const BandwidthGroup &i) const;
729
730	com::Utf8Str strName;
731	uint64_t cMaxBytesPerSec;
732	BandwidthGroupType_T enmType;
733	};
734
735	typedef std::list<BandwidthGroup> BandwidthGroupList;
736
737	/**
738	* NOTE: If you add any fields in here, you must update a) the constructor and b)
739	* the operator== which is used by MachineConfigFile::operator==(), or otherwise
740	* your settings might never get saved.
741	*/
742	struct IOSettings
743	{
744	IOSettings();
745
746	bool areIOCacheDefaultSettings() const;
747	bool areDefaultSettings() const;
748
749	bool operator==(const IOSettings &i) const;
750
751	bool fIOCacheEnabled;
752	uint32_t ulIOCacheSize;
753	BandwidthGroupList llBandwidthGroups;
754	};
755
756	/**
757	* NOTE: If you add any fields in here, you must update a) the constructor and b)
758	* the operator== which is used by MachineConfigFile::operator==(), or otherwise
759	* your settings might never get saved.
760	*/
761	struct HostPCIDeviceAttachment
762	{
763	HostPCIDeviceAttachment();
764
765	bool operator==(const HostPCIDeviceAttachment &a) const;
766
767	com::Utf8Str strDeviceName;
768	uint32_t uHostAddress;
769	uint32_t uGuestAddress;
770	};
771
772	typedef std::list<HostPCIDeviceAttachment> HostPCIDeviceAttachmentList;
773
774	/**
775	* A device attached to a storage controller. This can either be a
776	* hard disk or a DVD drive or a floppy drive and also specifies
777	* which medium is "in" the drive; as a result, this is a combination
778	* of the Main IMedium and IMediumAttachment interfaces.
779	*
780	* NOTE: If you add any fields in here, you must update a) the constructor and b)
781	* the operator== which is used by MachineConfigFile::operator==(), or otherwise
782	* your settings might never get saved.
783	*/
784	struct AttachedDevice
785	{
786	AttachedDevice();
787
788	bool operator==(const AttachedDevice &a) const;
789
790	DeviceType_T deviceType; // only HardDisk, DVD or Floppy are allowed
791
792	// DVDs can be in pass-through mode:
793	bool fPassThrough;
794
795	// Whether guest-triggered eject of DVDs will keep the medium in the
796	// VM config or not:
797	bool fTempEject;
798
799	// Whether the medium is non-rotational:
800	bool fNonRotational;
801
802	// Whether the medium supports discarding unused blocks:
803	bool fDiscard;
804
805	// Whether the medium is hot-pluggable:
806	bool fHotPluggable;
807
808	int32_t lPort;
809	int32_t lDevice;
810
811	// if an image file is attached to the device (ISO, RAW, or hard disk image such as VDI),
812	// this is its UUID; it depends on deviceType which media registry this then needs to
813	// be looked up in. If no image file (only permitted for DVDs and floppies), then the UUID is NULL
814	com::Guid uuid;
815
816	// for DVDs and floppies, the attachment can also be a host device:
817	com::Utf8Str strHostDriveSrc; // if != NULL, value of <HostDrive>/@src
818
819	// Bandwidth group the device is attached to.
820	com::Utf8Str strBwGroup;
821	};
822
823	typedef std::list<AttachedDevice> AttachedDevicesList;
824
825	/**
826	* NOTE: If you add any fields in here, you must update a) the constructor and b)
827	* the operator== which is used by MachineConfigFile::operator==(), or otherwise
828	* your settings might never get saved.
829	*/
830	struct StorageController
831	{
832	StorageController();
833
834	bool operator==(const StorageController &s) const;
835
836	com::Utf8Str strName;
837	StorageBus_T storageBus; // _SATA, _SCSI, _IDE, _SAS
838	StorageControllerType_T controllerType;
839	uint32_t ulPortCount;
840	uint32_t ulInstance;
841	bool fUseHostIOCache;
842	bool fBootable;
843
844	// only for when controllerType == StorageControllerType_IntelAhci:
845	int32_t lIDE0MasterEmulationPort,
846	lIDE0SlaveEmulationPort,
847	lIDE1MasterEmulationPort,
848	lIDE1SlaveEmulationPort;
849
850	AttachedDevicesList llAttachedDevices;
851	};
852
853	typedef std::list<StorageController> StorageControllersList;
854
855	/**
856	* We wrap the storage controllers list into an extra struct so we can
857	* use an undefined struct without needing std::list<> in all the headers.
858	*
859	* NOTE: If you add any fields in here, you must update a) the constructor and b)
860	* the operator== which is used by MachineConfigFile::operator==(), or otherwise
861	* your settings might never get saved.
862	*/
863	struct Storage
864	{
865	bool operator==(const Storage &s) const;
866
867	StorageControllersList llStorageControllers;
868	};
869
870	/**
871	* Representation of Machine hardware; this is used in the MachineConfigFile.hardwareMachine
872	* field.
873	*
874	* NOTE: If you add any fields in here, you must update a) the constructor and b)
875	* the operator== which is used by MachineConfigFile::operator==(), or otherwise
876	* your settings might never get saved.
877	*/
878	struct Hardware
879	{
880	Hardware();
881
882	bool areParavirtDefaultSettings(SettingsVersion_T sv) const;
883	bool areBootOrderDefaultSettings() const;
884	bool areDisplayDefaultSettings() const;
885	bool areVideoCaptureDefaultSettings() const;
886	bool areAllNetworkAdaptersDefaultSettings(SettingsVersion_T sv) const;
887
888	bool operator==(const Hardware&) const;
889
890	com::Utf8Str strVersion; // hardware version, optional
891	com::Guid uuid; // hardware uuid, optional (null).
892
893	bool fHardwareVirt,
894	fNestedPaging,
895	fLargePages,
896	fVPID,
897	fUnrestrictedExecution,
898	fHardwareVirtForce,
899	fSyntheticCpu,
900	fTripleFaultReset,
901	fPAE,
902	fAPIC, // requires settings version 1.16 (VirtualBox 5.1)
903	fX2APIC; // requires settings version 1.16 (VirtualBox 5.1)
904	typedef enum LongModeType { LongMode_Enabled, LongMode_Disabled, LongMode_Legacy } LongModeType;
905	LongModeType enmLongMode;
906	uint32_t cCPUs;
907	bool fCpuHotPlug; // requires settings version 1.10 (VirtualBox 3.2)
908	CpuList llCpus; // requires settings version 1.10 (VirtualBox 3.2)
909	bool fHPETEnabled; // requires settings version 1.10 (VirtualBox 3.2)
910	uint32_t ulCpuExecutionCap; // requires settings version 1.11 (VirtualBox 3.3)
911	uint32_t uCpuIdPortabilityLevel; // requires settings version 1.15 (VirtualBox 5.0)
912	com::Utf8Str strCpuProfile; // requires settings version 1.16 (VirtualBox 5.1)
913
914	CpuIdLeafsList llCpuIdLeafs;
915
916	uint32_t ulMemorySizeMB;
917
918	BootOrderMap mapBootOrder; // item 0 has highest priority
919
920	GraphicsControllerType_T graphicsControllerType;
921	uint32_t ulVRAMSizeMB;
922	uint32_t cMonitors;
923	bool fAccelerate3D,
924	fAccelerate2DVideo; // requires settings version 1.8 (VirtualBox 3.1)
925
926	uint32_t ulVideoCaptureHorzRes; // requires settings version 1.14 (VirtualBox 4.3)
927	uint32_t ulVideoCaptureVertRes; // requires settings version 1.14 (VirtualBox 4.3)
928	uint32_t ulVideoCaptureRate; // requires settings version 1.14 (VirtualBox 4.3)
929	uint32_t ulVideoCaptureFPS; // requires settings version 1.14 (VirtualBox 4.3)
930	uint32_t ulVideoCaptureMaxTime; // requires settings version 1.14 (VirtualBox 4.3)
931	uint32_t ulVideoCaptureMaxSize; // requires settings version 1.14 (VirtualBox 4.3)
932	bool fVideoCaptureEnabled; // requires settings version 1.14 (VirtualBox 4.3)
933	uint64_t u64VideoCaptureScreens; // requires settings version 1.14 (VirtualBox 4.3)
934	com::Utf8Str strVideoCaptureFile; // requires settings version 1.14 (VirtualBox 4.3)
935
936	FirmwareType_T firmwareType; // requires settings version 1.9 (VirtualBox 3.1)
937
938	PointingHIDType_T pointingHIDType; // requires settings version 1.10 (VirtualBox 3.2)
939	KeyboardHIDType_T keyboardHIDType; // requires settings version 1.10 (VirtualBox 3.2)
940
941	ChipsetType_T chipsetType; // requires settings version 1.11 (VirtualBox 4.0)
942	ParavirtProvider_T paravirtProvider; // requires settings version 1.15 (VirtualBox 4.4)
943	com::Utf8Str strParavirtDebug; // requires settings version 1.16 (VirtualBox 5.1)
944
945	bool fEmulatedUSBCardReader; // 1.12 (VirtualBox 4.1)
946
947	VRDESettings vrdeSettings;
948
949	BIOSSettings biosSettings;
950	USB usbSettings;
951	NetworkAdaptersList llNetworkAdapters;
952	SerialPortsList llSerialPorts;
953	ParallelPortsList llParallelPorts;
954	AudioAdapter audioAdapter;
955	Storage storage;
956
957	// technically these two have no business in the hardware section, but for some
958	// clever reason <Hardware> is where they are in the XML....
959	SharedFoldersList llSharedFolders;
960	ClipboardMode_T clipboardMode;
961	DnDMode_T dndMode;
962
963	uint32_t ulMemoryBalloonSize;
964	bool fPageFusionEnabled;
965
966	GuestPropertiesList llGuestProperties;
967
968	IOSettings ioSettings; // requires settings version 1.10 (VirtualBox 3.2)
969	HostPCIDeviceAttachmentList pciAttachments; // requires settings version 1.12 (VirtualBox 4.1)
970
971	com::Utf8Str strDefaultFrontend; // requires settings version 1.14 (VirtualBox 4.3)
972	};
973
974	/**
975	* Settings that has to do with debugging.
976	*/
977	struct Debugging
978	{
979	Debugging();
980
981	bool areDefaultSettings() const;
982
983	bool operator==(const Debugging &rOther) const;
984
985	bool fTracingEnabled;
986	bool fAllowTracingToAccessVM;
987	com::Utf8Str strTracingConfig;
988	};
989
990	/**
991	* Settings that has to do with autostart.
992	*/
993	struct Autostart
994	{
995	Autostart();
996
997	bool areDefaultSettings() const;
998
999	bool operator==(const Autostart &rOther) const;
1000
1001	bool fAutostartEnabled;
1002	uint32_t uAutostartDelay;
1003	AutostopType_T enmAutostopType;
1004	};
1005
1006	struct Snapshot;
1007	typedef std::list<Snapshot> SnapshotsList;
1008
1009	/**
1010	* NOTE: If you add any fields in here, you must update a) the constructor and b)
1011	* the operator== which is used by MachineConfigFile::operator==(), or otherwise
1012	* your settings might never get saved.
1013	*/
1014	struct Snapshot
1015	{
1016	Snapshot();
1017
1018	bool operator==(const Snapshot &s) const;
1019
1020	com::Guid uuid;
1021	com::Utf8Str strName,
1022	strDescription; // optional
1023	RTTIMESPEC timestamp;
1024
1025	com::Utf8Str strStateFile; // for online snapshots only
1026
1027	Hardware hardware;
1028
1029	Debugging debugging;
1030	Autostart autostart;
1031
1032	SnapshotsList llChildSnapshots;
1033
1034	static const struct Snapshot Empty;
1035	};
1036
1037	/**
1038	* NOTE: If you add any fields in here, you must update a) the constructor and b)
1039	* the operator== which is used by MachineConfigFile::operator==(), or otherwise
1040	* your settings might never get saved.
1041	*/
1042	struct MachineUserData
1043	{
1044	MachineUserData();
1045
1046	bool operator==(const MachineUserData &c) const;
1047
1048	com::Utf8Str strName;
1049	bool fDirectoryIncludesUUID;
1050	bool fNameSync;
1051	com::Utf8Str strDescription;
1052	StringsList llGroups;
1053	com::Utf8Str strOsType;
1054	com::Utf8Str strSnapshotFolder;
1055	bool fTeleporterEnabled;
1056	uint32_t uTeleporterPort;
1057	com::Utf8Str strTeleporterAddress;
1058	com::Utf8Str strTeleporterPassword;
1059	FaultToleranceState_T enmFaultToleranceState;
1060	uint32_t uFaultTolerancePort;
1061	com::Utf8Str strFaultToleranceAddress;
1062	com::Utf8Str strFaultTolerancePassword;
1063	uint32_t uFaultToleranceInterval;
1064	bool fRTCUseUTC;
1065	IconBlob ovIcon;
1066	com::Utf8Str strVMPriority;
1067	};
1068
1069
1070	/**
1071	* MachineConfigFile represents an XML machine configuration. All the machine settings
1072	* that go out to the XML (or are read from it) are in here.
1073	*
1074	* NOTE: If you add any fields in here, you must update a) the constructor and b)
1075	* the operator== which is used by Machine::saveSettings(), or otherwise your settings
1076	* might never get saved.
1077	*/
1078	class MachineConfigFile : public ConfigFileBase
1079	{
1080	public:
1081	com::Guid uuid;
1082
1083	MachineUserData machineUserData;
1084
1085	com::Utf8Str strStateFile;
1086	bool fCurrentStateModified; // optional, default is true
1087	RTTIMESPEC timeLastStateChange; // optional, defaults to now
1088	bool fAborted; // optional, default is false
1089
1090	com::Guid uuidCurrentSnapshot;
1091
1092	Hardware hardwareMachine;
1093	MediaRegistry mediaRegistry;
1094	Debugging debugging;
1095	Autostart autostart;
1096
1097	StringsMap mapExtraDataItems;
1098
1099	SnapshotsList llFirstSnapshot; // first snapshot or empty list if there's none
1100
1101	MachineConfigFile(const com::Utf8Str *pstrFilename);
1102
1103	bool operator==(const MachineConfigFile &m) const;
1104
1105	bool canHaveOwnMediaRegistry() const;
1106
1107	void importMachineXML(const xml::ElementNode &elmMachine);
1108
1109	void write(const com::Utf8Str &strFilename);
1110
1111	enum
1112	{
1113	BuildMachineXML_IncludeSnapshots = 0x01,
1114	BuildMachineXML_WriteVBoxVersionAttribute = 0x02,
1115	BuildMachineXML_SkipRemovableMedia = 0x04,
1116	BuildMachineXML_MediaRegistry = 0x08,
1117	BuildMachineXML_SuppressSavedState = 0x10
1118	};
1119	void buildMachineXML(xml::ElementNode &elmMachine,
1120	uint32_t fl,
1121	std::list<xml::ElementNode> pllElementsWithUuidAttributes);
1122
1123	static bool isAudioDriverAllowedOnThisHost(AudioDriverType_T drv);
1124	static AudioDriverType_T getHostDefaultAudioDriver();
1125
1126	private:
1127	void readNetworkAdapters(const xml::ElementNode &elmHardware, NetworkAdaptersList &ll);
1128	void readAttachedNetworkMode(const xml::ElementNode &pelmMode, bool fEnabled, NetworkAdapter &nic);
1129	void readCpuIdTree(const xml::ElementNode &elmCpuid, CpuIdLeafsList &ll);
1130	void readCpuTree(const xml::ElementNode &elmCpu, CpuList &ll);
1131	void readSerialPorts(const xml::ElementNode &elmUART, SerialPortsList &ll);
1132	void readParallelPorts(const xml::ElementNode &elmLPT, ParallelPortsList &ll);
1133	void readAudioAdapter(const xml::ElementNode &elmAudioAdapter, AudioAdapter &aa);
1134	void readGuestProperties(const xml::ElementNode &elmGuestProperties, Hardware &hw);
1135	void readStorageControllerAttributes(const xml::ElementNode &elmStorageController, StorageController &sctl);
1136	void readHardware(const xml::ElementNode &elmHardware, Hardware &hw);
1137	void readHardDiskAttachments_pre1_7(const xml::ElementNode &elmHardDiskAttachments, Storage &strg);
1138	void readStorageControllers(const xml::ElementNode &elmStorageControllers, Storage &strg);
1139	void readDVDAndFloppies_pre1_9(const xml::ElementNode &elmHardware, Storage &strg);
1140	void readTeleporter(const xml::ElementNode pElmTeleporter, MachineUserData pUserData);
1141	void readDebugging(const xml::ElementNode pElmDbg, Debugging pDbg);
1142	void readAutostart(const xml::ElementNode pElmAutostart, Autostart pAutostart);
1143	void readGroups(const xml::ElementNode elmGroups, StringsList pllGroups);
1144	bool readSnapshot(const com::Guid &curSnapshotUuid, uint32_t depth, const xml::ElementNode &elmSnapshot, Snapshot &snap);
1145	void convertOldOSType_pre1_5(com::Utf8Str &str);
1146	void readMachine(const xml::ElementNode &elmMachine);
1147
1148	void buildHardwareXML(xml::ElementNode &elmParent, const Hardware &hw, uint32_t fl, std::list<xml::ElementNode> pllElementsWithUuidAttributes);
1149	void buildNetworkXML(NetworkAttachmentType_T mode, bool fEnabled, xml::ElementNode &elmParent, const NetworkAdapter &nic);
1150	void buildStorageControllersXML(xml::ElementNode &elmParent,
1151	const Storage &st,
1152	bool fSkipRemovableMedia,
1153	std::list<xml::ElementNode> pllElementsWithUuidAttributes);
1154	void buildDebuggingXML(xml::ElementNode pElmParent, const Debugging pDbg);
1155	void buildAutostartXML(xml::ElementNode pElmParent, const Autostart pAutostart);
1156	void buildGroupsXML(xml::ElementNode pElmParent, const StringsList pllGroups);
1157	void buildSnapshotXML(uint32_t depth, xml::ElementNode &elmParent, const Snapshot &snap);
1158
1159	void bumpSettingsVersionIfNeeded();
1160	};
1161
1162	} // namespace settings
1163
1164
1165	#endif /* ___VBox_settings_h */

Note: See TracBrowser for help on using the repository browser.

source: vbox/trunk/include/VBox/settings.h@ 67180

Download in other formats: