settings.h@ 80138

Last change on this file since 80138 was 80074, checked in by vboxsync, 5 years ago
VMM,Main,++: Retired the unfinished FTM component.
Property svn:eol-style set to `native` Property svn:keywords set to `Date Revision Author Id`
File size: 44.0 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-2019 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_INCLUDED_settings_h
41	#define VBOX_INCLUDED_settings_h
42	#ifndef RT_WITHOUT_PRAGMA_ONCE
43	# pragma once
44	#endif
45
46	#include <iprt/time.h>
47
48	#include "VBox/com/VirtualBox.h"
49
50	#include <VBox/com/Guid.h>
51	#include <VBox/com/string.h>
52
53	#include <list>
54	#include <map>
55	#include <vector>
56
57	/**
58	* Maximum depth of a medium tree, to prevent stack overflows.
59	* XPCOM has a relatively low stack size for its workers, and we have
60	* to avoid crashes due to exceeding the limit both on reading and
61	* writing config files.
62	*/
63	#define SETTINGS_MEDIUM_DEPTH_MAX 300
64
65	/**
66	* Maximum depth of the snapshot tree, to prevent stack overflows.
67	* XPCOM has a relatively low stack size for its workers, and we have
68	* to avoid crashes due to exceeding the limit both on reading and
69	* writing config files. The bottleneck is reading config files with
70	* deep snapshot nesting, as libxml2 needs quite some stack space,
71	* so with the current stack size the margin isn't big.
72	*/
73	#define SETTINGS_SNAPSHOT_DEPTH_MAX 250
74
75	namespace xml
76	{
77	class ElementNode;
78	}
79
80	namespace settings
81	{
82
83	class ConfigFileError;
84
85	////////////////////////////////////////////////////////////////////////////////
86	//
87	// Structures shared between Machine XML and VirtualBox.xml
88	//
89	////////////////////////////////////////////////////////////////////////////////
90
91	typedef std::map<com::Utf8Str, com::Utf8Str> StringsMap;
92	typedef std::list<com::Utf8Str> StringsList;
93
94	/**
95	* USB device filter definition. This struct is used both in MainConfigFile
96	* (for global USB filters) and MachineConfigFile (for machine filters).
97	*
98	* NOTE: If you add any fields in here, you must update a) the constructor and b)
99	* the operator== which is used by MachineConfigFile::operator==(), or otherwise
100	* your settings might never get saved.
101	*/
102	struct USBDeviceFilter
103	{
104	USBDeviceFilter();
105
106	bool operator==(const USBDeviceFilter&u) const;
107
108	com::Utf8Str strName;
109	bool fActive;
110	com::Utf8Str strVendorId,
111	strProductId,
112	strRevision,
113	strManufacturer,
114	strProduct,
115	strSerialNumber,
116	strPort;
117	USBDeviceFilterAction_T action; // only used with host USB filters
118	com::Utf8Str strRemote; // irrelevant for host USB objects
119	uint32_t ulMaskedInterfaces; // irrelevant for host USB objects
120	};
121
122	typedef std::list<USBDeviceFilter> USBDeviceFiltersList;
123
124	struct Medium;
125	typedef std::list<Medium> MediaList;
126
127	/**
128	* NOTE: If you add any fields in here, you must update a) the constructor and b)
129	* the operator== which is used by MachineConfigFile::operator==(), or otherwise
130	* your settings might never get saved.
131	*/
132	struct Medium
133	{
134	Medium();
135
136	bool operator==(const Medium &m) const;
137
138	com::Guid uuid;
139	com::Utf8Str strLocation;
140	com::Utf8Str strDescription;
141
142	// the following are for hard disks only:
143	com::Utf8Str strFormat;
144	bool fAutoReset; // optional, only for diffs, default is false
145	StringsMap properties;
146	MediumType_T hdType;
147
148	MediaList llChildren; // only used with hard disks
149
150	static const struct Medium Empty;
151	};
152
153	/**
154	* A media registry. Starting with VirtualBox 3.3, this can appear in both the
155	* VirtualBox.xml file as well as machine XML files with settings version 1.11
156	* or higher, so these lists are now in ConfigFileBase.
157	*
158	* NOTE: If you add any fields in here, you must update a) the constructor and b)
159	* the operator== which is used by MachineConfigFile::operator==(), or otherwise
160	* your settings might never get saved.
161	*/
162	struct MediaRegistry
163	{
164	bool operator==(const MediaRegistry &m) const;
165
166	MediaList llHardDisks,
167	llDvdImages,
168	llFloppyImages;
169	};
170
171	/**
172	* NOTE: If you add any fields in here, you must update a) the constructor and b)
173	* the operator== which is used by MachineConfigFile::operator==(), or otherwise
174	* your settings might never get saved.
175	*/
176	struct NATRule
177	{
178	NATRule();
179
180	bool operator==(const NATRule &r) const;
181
182	com::Utf8Str strName;
183	NATProtocol_T proto;
184	uint16_t u16HostPort;
185	com::Utf8Str strHostIP;
186	uint16_t u16GuestPort;
187	com::Utf8Str strGuestIP;
188	};
189	typedef std::map<com::Utf8Str, NATRule> NATRulesMap;
190
191	struct NATHostLoopbackOffset
192	{
193	NATHostLoopbackOffset();
194
195	bool operator==(const NATHostLoopbackOffset &o) const;
196
197	bool operator==(const com::Utf8Str& strAddr)
198	{
199	return strLoopbackHostAddress == strAddr;
200	}
201
202	bool operator==(uint32_t off)
203	{
204	return u32Offset == off;
205	}
206
207	/** Note: 128/8 is only acceptable */
208	com::Utf8Str strLoopbackHostAddress;
209	uint32_t u32Offset;
210	};
211
212	typedef std::list<NATHostLoopbackOffset> NATLoopbackOffsetList;
213
214	typedef std::vector<uint8_t> IconBlob;
215
216	/**
217	* Common base class for both MainConfigFile and MachineConfigFile
218	* which contains some common logic for both.
219	*/
220	class ConfigFileBase
221	{
222	public:
223	bool fileExists();
224
225	void copyBaseFrom(const ConfigFileBase &b);
226
227	protected:
228	ConfigFileBase(const com::Utf8Str *pstrFilename);
229	/* Note: this copy constructor doesn't create a full copy of other, cause
230	* the file based stuff (xml doc) could not be copied. */
231	ConfigFileBase(const ConfigFileBase &other);
232
233	~ConfigFileBase();
234
235	typedef enum {Error, HardDisk, DVDImage, FloppyImage} MediaType;
236
237	static const char *stringifyMediaType(MediaType t);
238	SettingsVersion_T parseVersion(const com::Utf8Str &strVersion,
239	const xml::ElementNode *pElm);
240	void parseUUID(com::Guid &guid,
241	const com::Utf8Str &strUUID,
242	const xml::ElementNode *pElm) const;
243	void parseTimestamp(RTTIMESPEC &timestamp,
244	const com::Utf8Str &str,
245	const xml::ElementNode *pElm) const;
246	void parseBase64(IconBlob &binary,
247	const com::Utf8Str &str,
248	const xml::ElementNode *pElm) const;
249	com::Utf8Str stringifyTimestamp(const RTTIMESPEC &tm) const;
250	void toBase64(com::Utf8Str &str,
251	const IconBlob &binary) const;
252
253	void readExtraData(const xml::ElementNode &elmExtraData,
254	StringsMap &map);
255	void readUSBDeviceFilters(const xml::ElementNode &elmDeviceFilters,
256	USBDeviceFiltersList &ll);
257	void readMediumOne(MediaType t, const xml::ElementNode &elmMedium, Medium &med);
258	void readMedium(MediaType t, uint32_t depth, const xml::ElementNode &elmMedium, Medium &med);
259	void readMediaRegistry(const xml::ElementNode &elmMediaRegistry, MediaRegistry &mr);
260	void readNATForwardRulesMap(const xml::ElementNode &elmParent, NATRulesMap &mapRules);
261	void readNATLoopbacks(const xml::ElementNode &elmParent, NATLoopbackOffsetList &llLoopBacks);
262
263	void setVersionAttribute(xml::ElementNode &elm);
264	void specialBackupIfFirstBump();
265	void createStubDocument();
266
267	void buildExtraData(xml::ElementNode &elmParent, const StringsMap &me);
268	void buildUSBDeviceFilters(xml::ElementNode &elmParent,
269	const USBDeviceFiltersList &ll,
270	bool fHostMode);
271	void buildMedium(MediaType t,
272	uint32_t depth,
273	xml::ElementNode &elmMedium,
274	const Medium &mdm);
275	void buildMediaRegistry(xml::ElementNode &elmParent,
276	const MediaRegistry &mr);
277	void buildNATForwardRulesMap(xml::ElementNode &elmParent, const NATRulesMap &mapRules);
278	void buildNATLoopbacks(xml::ElementNode &elmParent, const NATLoopbackOffsetList &natLoopbackList);
279	void clearDocument();
280
281	struct Data;
282	Data *m;
283
284	friend class ConfigFileError;
285	};
286
287	////////////////////////////////////////////////////////////////////////////////
288	//
289	// VirtualBox.xml structures
290	//
291	////////////////////////////////////////////////////////////////////////////////
292
293	struct USBDeviceSource
294	{
295	com::Utf8Str strName;
296	com::Utf8Str strBackend;
297	com::Utf8Str strAddress;
298	StringsMap properties;
299	};
300
301	typedef std::list<USBDeviceSource> USBDeviceSourcesList;
302
303	struct Host
304	{
305	USBDeviceFiltersList llUSBDeviceFilters;
306	USBDeviceSourcesList llUSBDeviceSources;
307	};
308
309	struct SystemProperties
310	{
311	SystemProperties();
312
313	com::Utf8Str strDefaultMachineFolder;
314	com::Utf8Str strDefaultHardDiskFolder;
315	com::Utf8Str strDefaultHardDiskFormat;
316	com::Utf8Str strVRDEAuthLibrary;
317	com::Utf8Str strWebServiceAuthLibrary;
318	com::Utf8Str strDefaultVRDEExtPack;
319	com::Utf8Str strAutostartDatabasePath;
320	com::Utf8Str strDefaultAdditionsISO;
321	com::Utf8Str strDefaultFrontend;
322	com::Utf8Str strLoggingLevel;
323	com::Utf8Str strProxyUrl;
324	uint32_t uProxyMode; /*< ProxyMode_T /
325	uint32_t uLogHistoryCount;
326	bool fExclusiveHwVirt;
327	};
328
329	struct MachineRegistryEntry
330	{
331	com::Guid uuid;
332	com::Utf8Str strSettingsFile;
333	};
334
335	typedef std::list<MachineRegistryEntry> MachinesRegistry;
336
337	struct DhcpOptValue
338	{
339	DhcpOptValue();
340	DhcpOptValue(const com::Utf8Str &aText, DHCPOptionEncoding_T aEncoding = DHCPOptionEncoding_Normal);
341
342	com::Utf8Str strValue;
343	DHCPOptionEncoding_T enmEncoding;
344	};
345
346	typedef std::map<DHCPOption_T, DhcpOptValue> DhcpOptionMap;
347	typedef DhcpOptionMap::value_type DhcpOptValuePair;
348	typedef DhcpOptionMap::iterator DhcpOptIterator;
349	typedef DhcpOptionMap::const_iterator DhcpOptConstIterator;
350
351	struct DHCPGroupCondition
352	{
353	DHCPGroupCondition();
354
355	bool fInclusive;
356	DHCPGroupConditionType_T enmType;
357	com::Utf8Str strValue;
358	};
359	typedef std::vector<DHCPGroupCondition> DHCPGroupConditionVec;
360
361
362	struct DHCPConfig
363	{
364	DHCPConfig();
365
366	DhcpOptionMap mapOptions;
367	uint32_t secMinLeaseTime;
368	uint32_t secDefaultLeaseTime;
369	uint32_t secMaxLeaseTime;
370	com::Utf8Str strForcedOptions;
371	com::Utf8Str strSuppressedOptions;
372	};
373
374	struct DHCPGroupConfig : DHCPConfig
375	{
376	DHCPGroupConfig();
377
378	com::Utf8Str strName;
379	DHCPGroupConditionVec vecConditions;
380	};
381	typedef std::vector<DHCPGroupConfig> DHCPGroupConfigVec;
382
383	struct DHCPIndividualConfig : DHCPConfig
384	{
385	DHCPIndividualConfig();
386
387	com::Utf8Str strMACAddress;
388	com::Utf8Str strVMName;
389	uint32_t uSlot;
390	com::Utf8Str strFixedAddress;
391	};
392	typedef std::map<com::Utf8Str, DHCPIndividualConfig> DHCPIndividualConfigMap;
393
394	struct DHCPServer
395	{
396	DHCPServer();
397
398	com::Utf8Str strNetworkName;
399	com::Utf8Str strIPAddress;
400	com::Utf8Str strIPLower;
401	com::Utf8Str strIPUpper;
402	bool fEnabled;
403	DHCPConfig globalConfig;
404	DHCPGroupConfigVec vecGroupConfigs;
405	DHCPIndividualConfigMap mapIndividualConfigs;
406	};
407	typedef std::list<DHCPServer> DHCPServersList;
408
409
410	/**
411	* NAT Networking settings (NAT service).
412	*/
413	struct NATNetwork
414	{
415	NATNetwork();
416
417	com::Utf8Str strNetworkName;
418	com::Utf8Str strIPv4NetworkCidr;
419	com::Utf8Str strIPv6Prefix;
420	bool fEnabled;
421	bool fIPv6Enabled;
422	bool fAdvertiseDefaultIPv6Route;
423	bool fNeedDhcpServer;
424	uint32_t u32HostLoopback6Offset;
425	NATLoopbackOffsetList llHostLoopbackOffsetList;
426	NATRulesMap mapPortForwardRules4;
427	NATRulesMap mapPortForwardRules6;
428	};
429
430	typedef std::list<NATNetwork> NATNetworksList;
431
432
433	class MainConfigFile : public ConfigFileBase
434	{
435	public:
436	MainConfigFile(const com::Utf8Str *pstrFilename);
437
438	void readMachineRegistry(const xml::ElementNode &elmMachineRegistry);
439	void readNATNetworks(const xml::ElementNode &elmNATNetworks);
440
441	void write(const com::Utf8Str strFilename);
442
443	Host host;
444	SystemProperties systemProperties;
445	MediaRegistry mediaRegistry;
446	MachinesRegistry llMachines;
447	DHCPServersList llDhcpServers;
448	NATNetworksList llNATNetworks;
449	StringsMap mapExtraDataItems;
450
451	private:
452	void bumpSettingsVersionIfNeeded();
453	void buildUSBDeviceSources(xml::ElementNode &elmParent, const USBDeviceSourcesList &ll);
454	void readUSBDeviceSources(const xml::ElementNode &elmDeviceSources, USBDeviceSourcesList &ll);
455	void buildDHCPServers(xml::ElementNode &elmDHCPServers, DHCPServersList const &ll);
456	void buildDHCPOptions(xml::ElementNode &elmOptions, DHCPConfig const &rConfig, bool fIgnoreSubnetMask);
457	void readDHCPServers(const xml::ElementNode &elmDHCPServers);
458	void readDHCPOptions(DHCPConfig &rConfig, const xml::ElementNode &elmOptions, bool fIgnoreSubnetMask);
459	bool convertGuiProxySettings(const com::Utf8Str &strUIProxySettings);
460	};
461
462	////////////////////////////////////////////////////////////////////////////////
463	//
464	// Machine XML structures
465	//
466	////////////////////////////////////////////////////////////////////////////////
467
468	/**
469	* NOTE: If you add any fields in here, you must update a) the constructor and b)
470	* the operator== which is used by MachineConfigFile::operator==(), or otherwise
471	* your settings might never get saved.
472	*/
473	struct VRDESettings
474	{
475	VRDESettings();
476
477	bool areDefaultSettings(SettingsVersion_T sv) const;
478
479	bool operator==(const VRDESettings& v) const;
480
481	bool fEnabled;
482	AuthType_T authType;
483	uint32_t ulAuthTimeout;
484	com::Utf8Str strAuthLibrary;
485	bool fAllowMultiConnection,
486	fReuseSingleConnection;
487	com::Utf8Str strVrdeExtPack;
488	StringsMap mapProperties;
489	};
490
491	/**
492	* NOTE: If you add any fields in here, you must update a) the constructor and b)
493	* the operator== which is used by MachineConfigFile::operator==(), or otherwise
494	* your settings might never get saved.
495	*/
496	struct BIOSSettings
497	{
498	BIOSSettings();
499
500	bool areDefaultSettings() const;
501
502	bool operator==(const BIOSSettings &d) const;
503
504	bool fACPIEnabled,
505	fIOAPICEnabled,
506	fLogoFadeIn,
507	fLogoFadeOut,
508	fPXEDebugEnabled;
509	uint32_t ulLogoDisplayTime;
510	BIOSBootMenuMode_T biosBootMenuMode;
511	APICMode_T apicMode; // requires settings version 1.16 (VirtualBox 5.1)
512	int64_t llTimeOffset;
513	com::Utf8Str strLogoImagePath;
514	};
515
516	/** List for keeping a recording feature list. */
517	typedef std::map<RecordingFeature_T, bool> RecordingFeatureMap;
518
519	struct RecordingScreenSettings
520	{
521	RecordingScreenSettings();
522
523	virtual ~RecordingScreenSettings();
524
525	void applyDefaults(void);
526
527	bool areDefaultSettings(void) const;
528
529	bool isFeatureEnabled(RecordingFeature_T enmFeature) const;
530
531	bool operator==(const RecordingScreenSettings &d) const;
532
533	/** Whether to record this screen or not. */
534	bool fEnabled; // requires settings version 1.14 (VirtualBox 4.3)
535	/** Destination to record to. */
536	RecordingDestination_T enmDest; /** @todo Implement with next settings version bump. */
537	/** Which features are enable or not. */
538	RecordingFeatureMap featureMap; /** @todo Implement with next settings version bump. */
539	/** Maximum time (in s) to record. If set to 0, no time limit is set. */
540	uint32_t ulMaxTimeS; // requires settings version 1.14 (VirtualBox 4.3)
541	/** Options string for hidden / advanced / experimental features. */
542	com::Utf8Str strOptions; // new since VirtualBox 5.2.
543
544	/**
545	* Structure holding settings for audio recording.
546	*/
547	struct Audio
548	{
549	Audio()
550	: enmAudioCodec(RecordingAudioCodec_Opus)
551	, uHz(22050)
552	, cBits(16)
553	, cChannels(2) { }
554
555	/** The audio codec type to use. */
556	RecordingAudioCodec_T enmAudioCodec; /** @todo Implement with next settings version bump. */
557	/** Hz rate. */
558	uint16_t uHz; /** @todo Implement with next settings version bump. */
559	/** Bits per sample. */
560	uint8_t cBits; /** @todo Implement with next settings version bump. */
561	/** Number of audio channels. */
562	uint8_t cChannels; /** @todo Implement with next settings version bump. */
563	} Audio;
564
565	/**
566	* Structure holding settings for video recording.
567	*/
568	struct Video
569	{
570	Video()
571	: enmCodec(RecordingVideoCodec_VP8)
572	, ulWidth(1024)
573	, ulHeight(768)
574	, ulRate(512)
575	, ulFPS(25) { }
576
577	/** The codec to use. */
578	RecordingVideoCodec_T enmCodec; /** @todo Implement with next settings version bump. */
579	/** Target frame width in pixels (X). */
580	uint32_t ulWidth; // requires settings version 1.14 (VirtualBox 4.3)
581	/** Target frame height in pixels (Y). */
582	uint32_t ulHeight; // requires settings version 1.14 (VirtualBox 4.3)
583	/** Encoding rate. */
584	uint32_t ulRate; // requires settings version 1.14 (VirtualBox 4.3)
585	/** Frames per second (FPS). */
586	uint32_t ulFPS; // requires settings version 1.14 (VirtualBox 4.3)
587	} Video;
588
589	/**
590	* Structure holding settings if the destination is a file.
591	*/
592	struct File
593	{
594	File()
595	: ulMaxSizeMB(0) { }
596
597	/** Maximum size (in MB) the file is allowed to have.
598	* When reaching the limit, recording will stop. */
599	uint32_t ulMaxSizeMB; // requires settings version 1.14 (VirtualBox 4.3)
600	/** Absolute file name path to use for recording. */
601	com::Utf8Str strName; // requires settings version 1.14 (VirtualBox 4.3)
602	} File;
603	};
604
605	/** Map for keeping settings per virtual screen.
606	* The key specifies the screen ID. */
607	typedef std::map<uint32_t, RecordingScreenSettings> RecordingScreenMap;
608
609	/**
610	* NOTE: If you add any fields in here, you must update a) the constructor and b)
611	* the operator== which is used by MachineConfigFile::operator==(), or otherwise
612	* your settings might never get saved.
613	*/
614	struct RecordingSettings
615	{
616	RecordingSettings();
617
618	void applyDefaults(void);
619
620	bool areDefaultSettings(void) const;
621
622	bool operator==(const RecordingSettings &d) const;
623
624	/** Whether recording as a whole is enabled or disabled. */
625	bool fEnabled; // requires settings version 1.14 (VirtualBox 4.3)
626	/** Map of handled recording screen settings.
627	* The key specifies the screen ID. */
628	RecordingScreenMap mapScreens;
629	};
630
631	/**
632	* NOTE: If you add any fields in here, you must update a) the constructor and b)
633	* the operator== which is used by MachineConfigFile::operator==(), or otherwise
634	* your settings might never get saved.
635	*/
636	struct USBController
637	{
638	USBController();
639
640	bool operator==(const USBController &u) const;
641
642	com::Utf8Str strName;
643	USBControllerType_T enmType;
644	};
645
646	typedef std::list<USBController> USBControllerList;
647
648	struct USB
649	{
650	USB();
651
652	bool operator==(const USB &u) const;
653
654	/** List of USB controllers present. */
655	USBControllerList llUSBControllers;
656	/** List of USB device filters. */
657	USBDeviceFiltersList llDeviceFilters;
658	};
659
660	struct NAT
661	{
662	NAT();
663
664	bool areDNSDefaultSettings() const;
665	bool areAliasDefaultSettings() const;
666	bool areTFTPDefaultSettings() const;
667	bool areDefaultSettings() const;
668
669	bool operator==(const NAT &n) const;
670
671	com::Utf8Str strNetwork;
672	com::Utf8Str strBindIP;
673	uint32_t u32Mtu;
674	uint32_t u32SockRcv;
675	uint32_t u32SockSnd;
676	uint32_t u32TcpRcv;
677	uint32_t u32TcpSnd;
678	com::Utf8Str strTFTPPrefix;
679	com::Utf8Str strTFTPBootFile;
680	com::Utf8Str strTFTPNextServer;
681	bool fDNSPassDomain;
682	bool fDNSProxy;
683	bool fDNSUseHostResolver;
684	bool fAliasLog;
685	bool fAliasProxyOnly;
686	bool fAliasUseSamePorts;
687	NATRulesMap mapRules;
688	};
689
690	/**
691	* NOTE: If you add any fields in here, you must update a) the constructor and b)
692	* the operator== which is used by MachineConfigFile::operator==(), or otherwise
693	* your settings might never get saved.
694	*/
695	struct NetworkAdapter
696	{
697	NetworkAdapter();
698
699	bool areGenericDriverDefaultSettings() const;
700	bool areDefaultSettings(SettingsVersion_T sv) const;
701	bool areDisabledDefaultSettings() const;
702
703	bool operator==(const NetworkAdapter &n) const;
704
705	uint32_t ulSlot;
706
707	NetworkAdapterType_T type;
708	bool fEnabled;
709	com::Utf8Str strMACAddress;
710	bool fCableConnected;
711	uint32_t ulLineSpeed;
712	NetworkAdapterPromiscModePolicy_T enmPromiscModePolicy;
713	bool fTraceEnabled;
714	com::Utf8Str strTraceFile;
715
716	NetworkAttachmentType_T mode;
717	NAT nat;
718	com::Utf8Str strBridgedName;
719	com::Utf8Str strHostOnlyName;
720	com::Utf8Str strInternalNetworkName;
721	com::Utf8Str strGenericDriver;
722	StringsMap genericProperties;
723	com::Utf8Str strNATNetworkName;
724	uint32_t ulBootPriority;
725	com::Utf8Str strBandwidthGroup; // requires settings version 1.13 (VirtualBox 4.2)
726	};
727
728	typedef std::list<NetworkAdapter> NetworkAdaptersList;
729
730	/**
731	* NOTE: If you add any fields in here, you must update a) the constructor and b)
732	* the operator== which is used by MachineConfigFile::operator==(), or otherwise
733	* your settings might never get saved.
734	*/
735	struct SerialPort
736	{
737	SerialPort();
738
739	bool operator==(const SerialPort &n) const;
740
741	uint32_t ulSlot;
742
743	bool fEnabled;
744	uint32_t ulIOBase;
745	uint32_t ulIRQ;
746	PortMode_T portMode;
747	com::Utf8Str strPath;
748	bool fServer;
749	UartType_T uartType;
750	};
751
752	typedef std::list<SerialPort> SerialPortsList;
753
754	/**
755	* NOTE: If you add any fields in here, you must update a) the constructor and b)
756	* the operator== which is used by MachineConfigFile::operator==(), or otherwise
757	* your settings might never get saved.
758	*/
759	struct ParallelPort
760	{
761	ParallelPort();
762
763	bool operator==(const ParallelPort &d) const;
764
765	uint32_t ulSlot;
766
767	bool fEnabled;
768	uint32_t ulIOBase;
769	uint32_t ulIRQ;
770	com::Utf8Str strPath;
771	};
772
773	typedef std::list<ParallelPort> ParallelPortsList;
774
775	/**
776	* NOTE: If you add any fields in here, you must update a) the constructor and b)
777	* the operator== which is used by MachineConfigFile::operator==(), or otherwise
778	* your settings might never get saved.
779	*/
780	struct AudioAdapter
781	{
782	AudioAdapter();
783
784	bool areDefaultSettings(SettingsVersion_T sv) const;
785
786	bool operator==(const AudioAdapter &a) const;
787
788	bool fEnabled;
789	bool fEnabledIn;
790	bool fEnabledOut;
791	AudioControllerType_T controllerType;
792	AudioCodecType_T codecType;
793	AudioDriverType_T driverType;
794	settings::StringsMap properties;
795	};
796
797	/**
798	* NOTE: If you add any fields in here, you must update a) the constructor and b)
799	* the operator== which is used by MachineConfigFile::operator==(), or otherwise
800	* your settings might never get saved.
801	*/
802	struct SharedFolder
803	{
804	SharedFolder();
805
806	bool operator==(const SharedFolder &a) const;
807
808	com::Utf8Str strName,
809	strHostPath;
810	bool fWritable;
811	bool fAutoMount;
812	com::Utf8Str strAutoMountPoint;
813	};
814
815	typedef std::list<SharedFolder> SharedFoldersList;
816
817	/**
818	* NOTE: If you add any fields in here, you must update a) the constructor and b)
819	* the operator== which is used by MachineConfigFile::operator==(), or otherwise
820	* your settings might never get saved.
821	*/
822	struct GuestProperty
823	{
824	GuestProperty();
825
826	bool operator==(const GuestProperty &g) const;
827
828	com::Utf8Str strName,
829	strValue;
830	uint64_t timestamp;
831	com::Utf8Str strFlags;
832	};
833
834	typedef std::list<GuestProperty> GuestPropertiesList;
835
836	typedef std::map<uint32_t, DeviceType_T> BootOrderMap;
837
838	/**
839	* NOTE: If you add any fields in here, you must update a) the constructor and b)
840	* the operator== which is used by MachineConfigFile::operator==(), or otherwise
841	* your settings might never get saved.
842	*/
843	struct CpuIdLeaf
844	{
845	CpuIdLeaf();
846
847	bool operator==(const CpuIdLeaf &c) const;
848
849	uint32_t idx;
850	uint32_t idxSub;
851	uint32_t uEax;
852	uint32_t uEbx;
853	uint32_t uEcx;
854	uint32_t uEdx;
855	};
856
857	typedef std::list<CpuIdLeaf> CpuIdLeafsList;
858
859	/**
860	* NOTE: If you add any fields in here, you must update a) the constructor and b)
861	* the operator== which is used by MachineConfigFile::operator==(), or otherwise
862	* your settings might never get saved.
863	*/
864	struct Cpu
865	{
866	Cpu();
867
868	bool operator==(const Cpu &c) const;
869
870	uint32_t ulId;
871	};
872
873	typedef std::list<Cpu> CpuList;
874
875	/**
876	* NOTE: If you add any fields in here, you must update a) the constructor and b)
877	* the operator== which is used by MachineConfigFile::operator==(), or otherwise
878	* your settings might never get saved.
879	*/
880	struct BandwidthGroup
881	{
882	BandwidthGroup();
883
884	bool operator==(const BandwidthGroup &i) const;
885
886	com::Utf8Str strName;
887	uint64_t cMaxBytesPerSec;
888	BandwidthGroupType_T enmType;
889	};
890
891	typedef std::list<BandwidthGroup> BandwidthGroupList;
892
893	/**
894	* NOTE: If you add any fields in here, you must update a) the constructor and b)
895	* the operator== which is used by MachineConfigFile::operator==(), or otherwise
896	* your settings might never get saved.
897	*/
898	struct IOSettings
899	{
900	IOSettings();
901
902	bool areIOCacheDefaultSettings() const;
903	bool areDefaultSettings() const;
904
905	bool operator==(const IOSettings &i) const;
906
907	bool fIOCacheEnabled;
908	uint32_t ulIOCacheSize;
909	BandwidthGroupList llBandwidthGroups;
910	};
911
912	/**
913	* NOTE: If you add any fields in here, you must update a) the constructor and b)
914	* the operator== which is used by MachineConfigFile::operator==(), or otherwise
915	* your settings might never get saved.
916	*/
917	struct HostPCIDeviceAttachment
918	{
919	HostPCIDeviceAttachment();
920
921	bool operator==(const HostPCIDeviceAttachment &a) const;
922
923	com::Utf8Str strDeviceName;
924	uint32_t uHostAddress;
925	uint32_t uGuestAddress;
926	};
927
928	typedef std::list<HostPCIDeviceAttachment> HostPCIDeviceAttachmentList;
929
930	/**
931	* A device attached to a storage controller. This can either be a
932	* hard disk or a DVD drive or a floppy drive and also specifies
933	* which medium is "in" the drive; as a result, this is a combination
934	* of the Main IMedium and IMediumAttachment interfaces.
935	*
936	* NOTE: If you add any fields in here, you must update a) the constructor and b)
937	* the operator== which is used by MachineConfigFile::operator==(), or otherwise
938	* your settings might never get saved.
939	*/
940	struct AttachedDevice
941	{
942	AttachedDevice();
943
944	bool operator==(const AttachedDevice &a) const;
945
946	DeviceType_T deviceType; // only HardDisk, DVD or Floppy are allowed
947
948	// DVDs can be in pass-through mode:
949	bool fPassThrough;
950
951	// Whether guest-triggered eject of DVDs will keep the medium in the
952	// VM config or not:
953	bool fTempEject;
954
955	// Whether the medium is non-rotational:
956	bool fNonRotational;
957
958	// Whether the medium supports discarding unused blocks:
959	bool fDiscard;
960
961	// Whether the medium is hot-pluggable:
962	bool fHotPluggable;
963
964	int32_t lPort;
965	int32_t lDevice;
966
967	// if an image file is attached to the device (ISO, RAW, or hard disk image such as VDI),
968	// this is its UUID; it depends on deviceType which media registry this then needs to
969	// be looked up in. If no image file (only permitted for DVDs and floppies), then the UUID is NULL
970	com::Guid uuid;
971
972	// for DVDs and floppies, the attachment can also be a host device:
973	com::Utf8Str strHostDriveSrc; // if != NULL, value of <HostDrive>/@src
974
975	// Bandwidth group the device is attached to.
976	com::Utf8Str strBwGroup;
977	};
978
979	typedef std::list<AttachedDevice> AttachedDevicesList;
980
981	/**
982	* NOTE: If you add any fields in here, you must update a) the constructor and b)
983	* the operator== which is used by MachineConfigFile::operator==(), or otherwise
984	* your settings might never get saved.
985	*/
986	struct StorageController
987	{
988	StorageController();
989
990	bool operator==(const StorageController &s) const;
991
992	com::Utf8Str strName;
993	StorageBus_T storageBus; // _SATA, _SCSI, _IDE, _SAS
994	StorageControllerType_T controllerType;
995	uint32_t ulPortCount;
996	uint32_t ulInstance;
997	bool fUseHostIOCache;
998	bool fBootable;
999
1000	// only for when controllerType == StorageControllerType_IntelAhci:
1001	int32_t lIDE0MasterEmulationPort,
1002	lIDE0SlaveEmulationPort,
1003	lIDE1MasterEmulationPort,
1004	lIDE1SlaveEmulationPort;
1005
1006	AttachedDevicesList llAttachedDevices;
1007	};
1008
1009	typedef std::list<StorageController> StorageControllersList;
1010
1011	/**
1012	* We wrap the storage controllers list into an extra struct so we can
1013	* use an undefined struct without needing std::list<> in all the headers.
1014	*
1015	* NOTE: If you add any fields in here, you must update a) the constructor and b)
1016	* the operator== which is used by MachineConfigFile::operator==(), or otherwise
1017	* your settings might never get saved.
1018	*/
1019	struct Storage
1020	{
1021	bool operator==(const Storage &s) const;
1022
1023	StorageControllersList llStorageControllers;
1024	};
1025
1026	/**
1027	* Representation of Machine hardware; this is used in the MachineConfigFile.hardwareMachine
1028	* field.
1029	*
1030	* NOTE: If you add any fields in here, you must update a) the constructor and b)
1031	* the operator== which is used by MachineConfigFile::operator==(), or otherwise
1032	* your settings might never get saved.
1033	*/
1034	struct Hardware
1035	{
1036	Hardware();
1037
1038	bool areParavirtDefaultSettings(SettingsVersion_T sv) const;
1039	bool areBootOrderDefaultSettings() const;
1040	bool areDisplayDefaultSettings() const;
1041	bool areAllNetworkAdaptersDefaultSettings(SettingsVersion_T sv) const;
1042
1043	bool operator==(const Hardware&) const;
1044
1045	com::Utf8Str strVersion; // hardware version, optional
1046	com::Guid uuid; // hardware uuid, optional (null).
1047
1048	bool fHardwareVirt,
1049	fNestedPaging,
1050	fLargePages,
1051	fVPID,
1052	fUnrestrictedExecution,
1053	fHardwareVirtForce,
1054	fUseNativeApi,
1055	fSyntheticCpu,
1056	fTripleFaultReset,
1057	fPAE,
1058	fAPIC, // requires settings version 1.16 (VirtualBox 5.1)
1059	fX2APIC; // requires settings version 1.16 (VirtualBox 5.1)
1060	bool fIBPBOnVMExit; //< added out of cycle, after 1.16 was out.
1061	bool fIBPBOnVMEntry; //< added out of cycle, after 1.16 was out.
1062	bool fSpecCtrl; //< added out of cycle, after 1.16 was out.
1063	bool fSpecCtrlByHost; //< added out of cycle, after 1.16 was out.
1064	bool fL1DFlushOnSched ; //< added out of cycle, after 1.16 was out.
1065	bool fL1DFlushOnVMEntry ; //< added out of cycle, after 1.16 was out.
1066	bool fMDSClearOnSched; //< added out of cycle, after 1.16 was out.
1067	bool fMDSClearOnVMEntry; //< added out of cycle, after 1.16 was out.
1068	bool fNestedHWVirt; //< requires settings version 1.17 (VirtualBox 6.0)
1069	typedef enum LongModeType { LongMode_Enabled, LongMode_Disabled, LongMode_Legacy } LongModeType;
1070	LongModeType enmLongMode;
1071	uint32_t cCPUs;
1072	bool fCpuHotPlug; // requires settings version 1.10 (VirtualBox 3.2)
1073	CpuList llCpus; // requires settings version 1.10 (VirtualBox 3.2)
1074	bool fHPETEnabled; // requires settings version 1.10 (VirtualBox 3.2)
1075	uint32_t ulCpuExecutionCap; // requires settings version 1.11 (VirtualBox 3.3)
1076	uint32_t uCpuIdPortabilityLevel; // requires settings version 1.15 (VirtualBox 5.0)
1077	com::Utf8Str strCpuProfile; // requires settings version 1.16 (VirtualBox 5.1)
1078
1079	CpuIdLeafsList llCpuIdLeafs;
1080
1081	uint32_t ulMemorySizeMB;
1082
1083	BootOrderMap mapBootOrder; // item 0 has highest priority
1084
1085	GraphicsControllerType_T graphicsControllerType;
1086	uint32_t ulVRAMSizeMB;
1087	uint32_t cMonitors;
1088	bool fAccelerate3D,
1089	fAccelerate2DVideo; // requires settings version 1.8 (VirtualBox 3.1)
1090
1091	FirmwareType_T firmwareType; // requires settings version 1.9 (VirtualBox 3.1)
1092
1093	PointingHIDType_T pointingHIDType; // requires settings version 1.10 (VirtualBox 3.2)
1094	KeyboardHIDType_T keyboardHIDType; // requires settings version 1.10 (VirtualBox 3.2)
1095
1096	ChipsetType_T chipsetType; // requires settings version 1.11 (VirtualBox 4.0)
1097	ParavirtProvider_T paravirtProvider; // requires settings version 1.15 (VirtualBox 4.4)
1098	com::Utf8Str strParavirtDebug; // requires settings version 1.16 (VirtualBox 5.1)
1099
1100	bool fEmulatedUSBCardReader; // 1.12 (VirtualBox 4.1)
1101
1102	VRDESettings vrdeSettings;
1103
1104	BIOSSettings biosSettings;
1105	RecordingSettings recordingSettings;
1106	USB usbSettings;
1107	NetworkAdaptersList llNetworkAdapters;
1108	SerialPortsList llSerialPorts;
1109	ParallelPortsList llParallelPorts;
1110	AudioAdapter audioAdapter;
1111	Storage storage;
1112
1113	// technically these two have no business in the hardware section, but for some
1114	// clever reason <Hardware> is where they are in the XML....
1115	SharedFoldersList llSharedFolders;
1116	ClipboardMode_T clipboardMode;
1117	DnDMode_T dndMode;
1118
1119	uint32_t ulMemoryBalloonSize;
1120	bool fPageFusionEnabled;
1121
1122	GuestPropertiesList llGuestProperties;
1123
1124	IOSettings ioSettings; // requires settings version 1.10 (VirtualBox 3.2)
1125	HostPCIDeviceAttachmentList pciAttachments; // requires settings version 1.12 (VirtualBox 4.1)
1126
1127	com::Utf8Str strDefaultFrontend; // requires settings version 1.14 (VirtualBox 4.3)
1128	};
1129
1130	/**
1131	* Settings that has to do with debugging.
1132	*/
1133	struct Debugging
1134	{
1135	Debugging();
1136
1137	bool areDefaultSettings() const;
1138
1139	bool operator==(const Debugging &rOther) const;
1140
1141	bool fTracingEnabled;
1142	bool fAllowTracingToAccessVM;
1143	com::Utf8Str strTracingConfig;
1144	};
1145
1146	/**
1147	* Settings that has to do with autostart.
1148	*/
1149	struct Autostart
1150	{
1151	Autostart();
1152
1153	bool areDefaultSettings() const;
1154
1155	bool operator==(const Autostart &rOther) const;
1156
1157	bool fAutostartEnabled;
1158	uint32_t uAutostartDelay;
1159	AutostopType_T enmAutostopType;
1160	};
1161
1162	struct Snapshot;
1163	typedef std::list<Snapshot> SnapshotsList;
1164
1165	/**
1166	* NOTE: If you add any fields in here, you must update a) the constructor and b)
1167	* the operator== which is used by MachineConfigFile::operator==(), or otherwise
1168	* your settings might never get saved.
1169	*/
1170	struct Snapshot
1171	{
1172	Snapshot();
1173
1174	bool operator==(const Snapshot &s) const;
1175
1176	com::Guid uuid;
1177	com::Utf8Str strName,
1178	strDescription; // optional
1179	RTTIMESPEC timestamp;
1180
1181	com::Utf8Str strStateFile; // for online snapshots only
1182
1183	Hardware hardware;
1184
1185	Debugging debugging;
1186	Autostart autostart;
1187
1188	SnapshotsList llChildSnapshots;
1189
1190	static const struct Snapshot Empty;
1191	};
1192
1193	/**
1194	* NOTE: If you add any fields in here, you must update a) the constructor and b)
1195	* the operator== which is used by MachineConfigFile::operator==(), or otherwise
1196	* your settings might never get saved.
1197	*/
1198	struct MachineUserData
1199	{
1200	MachineUserData();
1201
1202	bool operator==(const MachineUserData &c) const;
1203
1204	com::Utf8Str strName;
1205	bool fDirectoryIncludesUUID;
1206	bool fNameSync;
1207	com::Utf8Str strDescription;
1208	StringsList llGroups;
1209	com::Utf8Str strOsType;
1210	com::Utf8Str strSnapshotFolder;
1211	bool fTeleporterEnabled;
1212	uint32_t uTeleporterPort;
1213	com::Utf8Str strTeleporterAddress;
1214	com::Utf8Str strTeleporterPassword;
1215	bool fRTCUseUTC;
1216	IconBlob ovIcon;
1217	VMProcPriority_T enmVMPriority;
1218	};
1219
1220
1221	/**
1222	* MachineConfigFile represents an XML machine configuration. All the machine settings
1223	* that go out to the XML (or are read from it) are in here.
1224	*
1225	* NOTE: If you add any fields in here, you must update a) the constructor and b)
1226	* the operator== which is used by Machine::saveSettings(), or otherwise your settings
1227	* might never get saved.
1228	*/
1229	class MachineConfigFile : public ConfigFileBase
1230	{
1231	public:
1232	com::Guid uuid;
1233
1234	MachineUserData machineUserData;
1235
1236	com::Utf8Str strStateFile;
1237	bool fCurrentStateModified; // optional, default is true
1238	RTTIMESPEC timeLastStateChange; // optional, defaults to now
1239	bool fAborted; // optional, default is false
1240
1241	com::Guid uuidCurrentSnapshot;
1242
1243	Hardware hardwareMachine;
1244	MediaRegistry mediaRegistry;
1245	Debugging debugging;
1246	Autostart autostart;
1247
1248	StringsMap mapExtraDataItems;
1249
1250	SnapshotsList llFirstSnapshot; // first snapshot or empty list if there's none
1251
1252	MachineConfigFile(const com::Utf8Str *pstrFilename);
1253
1254	bool operator==(const MachineConfigFile &m) const;
1255
1256	bool canHaveOwnMediaRegistry() const;
1257
1258	void importMachineXML(const xml::ElementNode &elmMachine);
1259
1260	void write(const com::Utf8Str &strFilename);
1261
1262	enum
1263	{
1264	BuildMachineXML_IncludeSnapshots = 0x01,
1265	BuildMachineXML_WriteVBoxVersionAttribute = 0x02,
1266	BuildMachineXML_SkipRemovableMedia = 0x04,
1267	BuildMachineXML_MediaRegistry = 0x08,
1268	BuildMachineXML_SuppressSavedState = 0x10
1269	};
1270	void buildMachineXML(xml::ElementNode &elmMachine,
1271	uint32_t fl,
1272	std::list<xml::ElementNode> pllElementsWithUuidAttributes);
1273
1274	static bool isAudioDriverAllowedOnThisHost(AudioDriverType_T drv);
1275	static AudioDriverType_T getHostDefaultAudioDriver();
1276
1277	private:
1278	void readNetworkAdapters(const xml::ElementNode &elmHardware, NetworkAdaptersList &ll);
1279	void readAttachedNetworkMode(const xml::ElementNode &pelmMode, bool fEnabled, NetworkAdapter &nic);
1280	void readCpuIdTree(const xml::ElementNode &elmCpuid, CpuIdLeafsList &ll);
1281	void readCpuTree(const xml::ElementNode &elmCpu, CpuList &ll);
1282	void readSerialPorts(const xml::ElementNode &elmUART, SerialPortsList &ll);
1283	void readParallelPorts(const xml::ElementNode &elmLPT, ParallelPortsList &ll);
1284	void readAudioAdapter(const xml::ElementNode &elmAudioAdapter, AudioAdapter &aa);
1285	void readGuestProperties(const xml::ElementNode &elmGuestProperties, Hardware &hw);
1286	void readStorageControllerAttributes(const xml::ElementNode &elmStorageController, StorageController &sctl);
1287	void readHardware(const xml::ElementNode &elmHardware, Hardware &hw);
1288	void readHardDiskAttachments_pre1_7(const xml::ElementNode &elmHardDiskAttachments, Storage &strg);
1289	void readStorageControllers(const xml::ElementNode &elmStorageControllers, Storage &strg);
1290	void readDVDAndFloppies_pre1_9(const xml::ElementNode &elmHardware, Storage &strg);
1291	void readTeleporter(const xml::ElementNode pElmTeleporter, MachineUserData pUserData);
1292	void readDebugging(const xml::ElementNode pElmDbg, Debugging pDbg);
1293	void readAutostart(const xml::ElementNode pElmAutostart, Autostart pAutostart);
1294	void readGroups(const xml::ElementNode elmGroups, StringsList pllGroups);
1295	bool readSnapshot(const com::Guid &curSnapshotUuid, uint32_t depth, const xml::ElementNode &elmSnapshot, Snapshot &snap);
1296	void convertOldOSType_pre1_5(com::Utf8Str &str);
1297	void readMachine(const xml::ElementNode &elmMachine);
1298
1299	void buildHardwareXML(xml::ElementNode &elmParent, const Hardware &hw, uint32_t fl, std::list<xml::ElementNode> pllElementsWithUuidAttributes);
1300	void buildNetworkXML(NetworkAttachmentType_T mode, bool fEnabled, xml::ElementNode &elmParent, const NetworkAdapter &nic);
1301	void buildStorageControllersXML(xml::ElementNode &elmParent,
1302	const Storage &st,
1303	bool fSkipRemovableMedia,
1304	std::list<xml::ElementNode> pllElementsWithUuidAttributes);
1305	void buildDebuggingXML(xml::ElementNode pElmParent, const Debugging pDbg);
1306	void buildAutostartXML(xml::ElementNode pElmParent, const Autostart pAutostart);
1307	void buildGroupsXML(xml::ElementNode pElmParent, const StringsList pllGroups);
1308	void buildSnapshotXML(uint32_t depth, xml::ElementNode &elmParent, const Snapshot &snap);
1309
1310	void bumpSettingsVersionIfNeeded();
1311	};
1312
1313	} // namespace settings
1314
1315
1316	#endif /* !VBOX_INCLUDED_settings_h */

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

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

Download in other formats: