settings.h@ 79732

Last change on this file since 79732 was 79732, checked in by vboxsync, 6 years ago
Main: Redoing the IDHCPServer interface, part I. bugref:9288
Property svn:eol-style set to `native` Property svn:keywords set to `Date Revision Author Id`
File size: 43.7 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_Legacy);
341
342	com::Utf8Str strValue;
343	DHCPOptionEncoding_T enmEncoding;
344	};
345
346	typedef std::map<DhcpOpt_T, DhcpOptValue> DhcpOptionMap;
347	typedef DhcpOptionMap::value_type DhcpOptValuePair;
348	typedef DhcpOptionMap::iterator DhcpOptIterator;
349	typedef DhcpOptionMap::const_iterator DhcpOptConstIterator;
350
351	struct DHCPConfig
352	{
353	DHCPConfig();
354
355	DhcpOptionMap OptionMap;
356	uint32_t secMinLeaseTime;
357	uint32_t secDefaultLeaseTime;
358	uint32_t secMaxLeaseTime;
359	};
360
361	struct DHCPIndividualConfig : DHCPConfig
362	{
363	DHCPIndividualConfig();
364
365	com::Utf8Str strMACAddress;
366	com::Utf8Str strVMName;
367	ULONG uSlot;
368	com::Utf8Str strFixedAddress;
369	};
370
371	typedef std::map<com::Utf8Str, DHCPIndividualConfig> DHCPIndividualConfigMap;
372
373	struct DHCPServer
374	{
375	DHCPServer();
376
377	com::Utf8Str strNetworkName;
378	com::Utf8Str strIPAddress;
379	com::Utf8Str strIPLower;
380	com::Utf8Str strIPUpper;
381	bool fEnabled;
382	DHCPConfig GlobalConfig;
383	DHCPIndividualConfigMap IndividualConfigs;
384	};
385
386	typedef std::list<DHCPServer> DHCPServersList;
387
388
389	/**
390	* NAT Networking settings (NAT service).
391	*/
392	struct NATNetwork
393	{
394	NATNetwork();
395
396	com::Utf8Str strNetworkName;
397	com::Utf8Str strIPv4NetworkCidr;
398	com::Utf8Str strIPv6Prefix;
399	bool fEnabled;
400	bool fIPv6Enabled;
401	bool fAdvertiseDefaultIPv6Route;
402	bool fNeedDhcpServer;
403	uint32_t u32HostLoopback6Offset;
404	NATLoopbackOffsetList llHostLoopbackOffsetList;
405	NATRulesMap mapPortForwardRules4;
406	NATRulesMap mapPortForwardRules6;
407	};
408
409	typedef std::list<NATNetwork> NATNetworksList;
410
411
412	class MainConfigFile : public ConfigFileBase
413	{
414	public:
415	MainConfigFile(const com::Utf8Str *pstrFilename);
416
417	void readMachineRegistry(const xml::ElementNode &elmMachineRegistry);
418	void readNATNetworks(const xml::ElementNode &elmNATNetworks);
419
420	void write(const com::Utf8Str strFilename);
421
422	Host host;
423	SystemProperties systemProperties;
424	MediaRegistry mediaRegistry;
425	MachinesRegistry llMachines;
426	DHCPServersList llDhcpServers;
427	NATNetworksList llNATNetworks;
428	StringsMap mapExtraDataItems;
429
430	private:
431	void bumpSettingsVersionIfNeeded();
432	void buildUSBDeviceSources(xml::ElementNode &elmParent, const USBDeviceSourcesList &ll);
433	void readUSBDeviceSources(const xml::ElementNode &elmDeviceSources, USBDeviceSourcesList &ll);
434	void buildDHCPServers(xml::ElementNode &elmDHCPServers, DHCPServersList const &ll);
435	void buildDHCPOptions(xml::ElementNode &elmOptions, DHCPConfig const &rConfig, bool fIgnoreSubnetMask);
436	void readDHCPServers(const xml::ElementNode &elmDHCPServers);
437	void readDHCPOptions(DHCPConfig &rConfig, const xml::ElementNode &elmOptions, bool fIgnoreSubnetMask);
438	bool convertGuiProxySettings(const com::Utf8Str &strUIProxySettings);
439	};
440
441	////////////////////////////////////////////////////////////////////////////////
442	//
443	// Machine XML structures
444	//
445	////////////////////////////////////////////////////////////////////////////////
446
447	/**
448	* NOTE: If you add any fields in here, you must update a) the constructor and b)
449	* the operator== which is used by MachineConfigFile::operator==(), or otherwise
450	* your settings might never get saved.
451	*/
452	struct VRDESettings
453	{
454	VRDESettings();
455
456	bool areDefaultSettings(SettingsVersion_T sv) const;
457
458	bool operator==(const VRDESettings& v) const;
459
460	bool fEnabled;
461	AuthType_T authType;
462	uint32_t ulAuthTimeout;
463	com::Utf8Str strAuthLibrary;
464	bool fAllowMultiConnection,
465	fReuseSingleConnection;
466	com::Utf8Str strVrdeExtPack;
467	StringsMap mapProperties;
468	};
469
470	/**
471	* NOTE: If you add any fields in here, you must update a) the constructor and b)
472	* the operator== which is used by MachineConfigFile::operator==(), or otherwise
473	* your settings might never get saved.
474	*/
475	struct BIOSSettings
476	{
477	BIOSSettings();
478
479	bool areDefaultSettings() const;
480
481	bool operator==(const BIOSSettings &d) const;
482
483	bool fACPIEnabled,
484	fIOAPICEnabled,
485	fLogoFadeIn,
486	fLogoFadeOut,
487	fPXEDebugEnabled;
488	uint32_t ulLogoDisplayTime;
489	BIOSBootMenuMode_T biosBootMenuMode;
490	APICMode_T apicMode; // requires settings version 1.16 (VirtualBox 5.1)
491	int64_t llTimeOffset;
492	com::Utf8Str strLogoImagePath;
493	};
494
495	/** List for keeping a recording feature list. */
496	typedef std::map<RecordingFeature_T, bool> RecordingFeatureMap;
497
498	struct RecordingScreenSettings
499	{
500	RecordingScreenSettings();
501
502	virtual ~RecordingScreenSettings();
503
504	void applyDefaults(void);
505
506	bool areDefaultSettings(void) const;
507
508	bool isFeatureEnabled(RecordingFeature_T enmFeature) const;
509
510	bool operator==(const RecordingScreenSettings &d) const;
511
512	/** Whether to record this screen or not. */
513	bool fEnabled; // requires settings version 1.14 (VirtualBox 4.3)
514	/** Destination to record to. */
515	RecordingDestination_T enmDest; /** @todo Implement with next settings version bump. */
516	/** Which features are enable or not. */
517	RecordingFeatureMap featureMap; /** @todo Implement with next settings version bump. */
518	/** Maximum time (in s) to record. If set to 0, no time limit is set. */
519	uint32_t ulMaxTimeS; // requires settings version 1.14 (VirtualBox 4.3)
520	/** Options string for hidden / advanced / experimental features. */
521	com::Utf8Str strOptions; // new since VirtualBox 5.2.
522
523	/**
524	* Structure holding settings for audio recording.
525	*/
526	struct Audio
527	{
528	Audio()
529	: enmAudioCodec(RecordingAudioCodec_Opus)
530	, uHz(22050)
531	, cBits(16)
532	, cChannels(2) { }
533
534	/** The audio codec type to use. */
535	RecordingAudioCodec_T enmAudioCodec; /** @todo Implement with next settings version bump. */
536	/** Hz rate. */
537	uint16_t uHz; /** @todo Implement with next settings version bump. */
538	/** Bits per sample. */
539	uint8_t cBits; /** @todo Implement with next settings version bump. */
540	/** Number of audio channels. */
541	uint8_t cChannels; /** @todo Implement with next settings version bump. */
542	} Audio;
543
544	/**
545	* Structure holding settings for video recording.
546	*/
547	struct Video
548	{
549	Video()
550	: enmCodec(RecordingVideoCodec_VP8)
551	, ulWidth(1024)
552	, ulHeight(768)
553	, ulRate(512)
554	, ulFPS(25) { }
555
556	/** The codec to use. */
557	RecordingVideoCodec_T enmCodec; /** @todo Implement with next settings version bump. */
558	/** Target frame width in pixels (X). */
559	uint32_t ulWidth; // requires settings version 1.14 (VirtualBox 4.3)
560	/** Target frame height in pixels (Y). */
561	uint32_t ulHeight; // requires settings version 1.14 (VirtualBox 4.3)
562	/** Encoding rate. */
563	uint32_t ulRate; // requires settings version 1.14 (VirtualBox 4.3)
564	/** Frames per second (FPS). */
565	uint32_t ulFPS; // requires settings version 1.14 (VirtualBox 4.3)
566	} Video;
567
568	/**
569	* Structure holding settings if the destination is a file.
570	*/
571	struct File
572	{
573	File()
574	: ulMaxSizeMB(0) { }
575
576	/** Maximum size (in MB) the file is allowed to have.
577	* When reaching the limit, recording will stop. */
578	uint32_t ulMaxSizeMB; // requires settings version 1.14 (VirtualBox 4.3)
579	/** Absolute file name path to use for recording. */
580	com::Utf8Str strName; // requires settings version 1.14 (VirtualBox 4.3)
581	} File;
582	};
583
584	/** Map for keeping settings per virtual screen.
585	* The key specifies the screen ID. */
586	typedef std::map<uint32_t, RecordingScreenSettings> RecordingScreenMap;
587
588	/**
589	* NOTE: If you add any fields in here, you must update a) the constructor and b)
590	* the operator== which is used by MachineConfigFile::operator==(), or otherwise
591	* your settings might never get saved.
592	*/
593	struct RecordingSettings
594	{
595	RecordingSettings();
596
597	void applyDefaults(void);
598
599	bool areDefaultSettings(void) const;
600
601	bool operator==(const RecordingSettings &d) const;
602
603	/** Whether recording as a whole is enabled or disabled. */
604	bool fEnabled; // requires settings version 1.14 (VirtualBox 4.3)
605	/** Map of handled recording screen settings.
606	* The key specifies the screen ID. */
607	RecordingScreenMap mapScreens;
608	};
609
610	/**
611	* NOTE: If you add any fields in here, you must update a) the constructor and b)
612	* the operator== which is used by MachineConfigFile::operator==(), or otherwise
613	* your settings might never get saved.
614	*/
615	struct USBController
616	{
617	USBController();
618
619	bool operator==(const USBController &u) const;
620
621	com::Utf8Str strName;
622	USBControllerType_T enmType;
623	};
624
625	typedef std::list<USBController> USBControllerList;
626
627	struct USB
628	{
629	USB();
630
631	bool operator==(const USB &u) const;
632
633	/** List of USB controllers present. */
634	USBControllerList llUSBControllers;
635	/** List of USB device filters. */
636	USBDeviceFiltersList llDeviceFilters;
637	};
638
639	struct NAT
640	{
641	NAT();
642
643	bool areDNSDefaultSettings() const;
644	bool areAliasDefaultSettings() const;
645	bool areTFTPDefaultSettings() const;
646	bool areDefaultSettings() const;
647
648	bool operator==(const NAT &n) const;
649
650	com::Utf8Str strNetwork;
651	com::Utf8Str strBindIP;
652	uint32_t u32Mtu;
653	uint32_t u32SockRcv;
654	uint32_t u32SockSnd;
655	uint32_t u32TcpRcv;
656	uint32_t u32TcpSnd;
657	com::Utf8Str strTFTPPrefix;
658	com::Utf8Str strTFTPBootFile;
659	com::Utf8Str strTFTPNextServer;
660	bool fDNSPassDomain;
661	bool fDNSProxy;
662	bool fDNSUseHostResolver;
663	bool fAliasLog;
664	bool fAliasProxyOnly;
665	bool fAliasUseSamePorts;
666	NATRulesMap mapRules;
667	};
668
669	/**
670	* NOTE: If you add any fields in here, you must update a) the constructor and b)
671	* the operator== which is used by MachineConfigFile::operator==(), or otherwise
672	* your settings might never get saved.
673	*/
674	struct NetworkAdapter
675	{
676	NetworkAdapter();
677
678	bool areGenericDriverDefaultSettings() const;
679	bool areDefaultSettings(SettingsVersion_T sv) const;
680	bool areDisabledDefaultSettings() const;
681
682	bool operator==(const NetworkAdapter &n) const;
683
684	uint32_t ulSlot;
685
686	NetworkAdapterType_T type;
687	bool fEnabled;
688	com::Utf8Str strMACAddress;
689	bool fCableConnected;
690	uint32_t ulLineSpeed;
691	NetworkAdapterPromiscModePolicy_T enmPromiscModePolicy;
692	bool fTraceEnabled;
693	com::Utf8Str strTraceFile;
694
695	NetworkAttachmentType_T mode;
696	NAT nat;
697	com::Utf8Str strBridgedName;
698	com::Utf8Str strHostOnlyName;
699	com::Utf8Str strInternalNetworkName;
700	com::Utf8Str strGenericDriver;
701	StringsMap genericProperties;
702	com::Utf8Str strNATNetworkName;
703	uint32_t ulBootPriority;
704	com::Utf8Str strBandwidthGroup; // requires settings version 1.13 (VirtualBox 4.2)
705	};
706
707	typedef std::list<NetworkAdapter> NetworkAdaptersList;
708
709	/**
710	* NOTE: If you add any fields in here, you must update a) the constructor and b)
711	* the operator== which is used by MachineConfigFile::operator==(), or otherwise
712	* your settings might never get saved.
713	*/
714	struct SerialPort
715	{
716	SerialPort();
717
718	bool operator==(const SerialPort &n) const;
719
720	uint32_t ulSlot;
721
722	bool fEnabled;
723	uint32_t ulIOBase;
724	uint32_t ulIRQ;
725	PortMode_T portMode;
726	com::Utf8Str strPath;
727	bool fServer;
728	UartType_T uartType;
729	};
730
731	typedef std::list<SerialPort> SerialPortsList;
732
733	/**
734	* NOTE: If you add any fields in here, you must update a) the constructor and b)
735	* the operator== which is used by MachineConfigFile::operator==(), or otherwise
736	* your settings might never get saved.
737	*/
738	struct ParallelPort
739	{
740	ParallelPort();
741
742	bool operator==(const ParallelPort &d) const;
743
744	uint32_t ulSlot;
745
746	bool fEnabled;
747	uint32_t ulIOBase;
748	uint32_t ulIRQ;
749	com::Utf8Str strPath;
750	};
751
752	typedef std::list<ParallelPort> ParallelPortsList;
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 AudioAdapter
760	{
761	AudioAdapter();
762
763	bool areDefaultSettings(SettingsVersion_T sv) const;
764
765	bool operator==(const AudioAdapter &a) const;
766
767	bool fEnabled;
768	bool fEnabledIn;
769	bool fEnabledOut;
770	AudioControllerType_T controllerType;
771	AudioCodecType_T codecType;
772	AudioDriverType_T driverType;
773	settings::StringsMap properties;
774	};
775
776	/**
777	* NOTE: If you add any fields in here, you must update a) the constructor and b)
778	* the operator== which is used by MachineConfigFile::operator==(), or otherwise
779	* your settings might never get saved.
780	*/
781	struct SharedFolder
782	{
783	SharedFolder();
784
785	bool operator==(const SharedFolder &a) const;
786
787	com::Utf8Str strName,
788	strHostPath;
789	bool fWritable;
790	bool fAutoMount;
791	com::Utf8Str strAutoMountPoint;
792	};
793
794	typedef std::list<SharedFolder> SharedFoldersList;
795
796	/**
797	* NOTE: If you add any fields in here, you must update a) the constructor and b)
798	* the operator== which is used by MachineConfigFile::operator==(), or otherwise
799	* your settings might never get saved.
800	*/
801	struct GuestProperty
802	{
803	GuestProperty();
804
805	bool operator==(const GuestProperty &g) const;
806
807	com::Utf8Str strName,
808	strValue;
809	uint64_t timestamp;
810	com::Utf8Str strFlags;
811	};
812
813	typedef std::list<GuestProperty> GuestPropertiesList;
814
815	typedef std::map<uint32_t, DeviceType_T> BootOrderMap;
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 CpuIdLeaf
823	{
824	CpuIdLeaf();
825
826	bool operator==(const CpuIdLeaf &c) const;
827
828	uint32_t idx;
829	uint32_t idxSub;
830	uint32_t uEax;
831	uint32_t uEbx;
832	uint32_t uEcx;
833	uint32_t uEdx;
834	};
835
836	typedef std::list<CpuIdLeaf> CpuIdLeafsList;
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 Cpu
844	{
845	Cpu();
846
847	bool operator==(const Cpu &c) const;
848
849	uint32_t ulId;
850	};
851
852	typedef std::list<Cpu> CpuList;
853
854	/**
855	* NOTE: If you add any fields in here, you must update a) the constructor and b)
856	* the operator== which is used by MachineConfigFile::operator==(), or otherwise
857	* your settings might never get saved.
858	*/
859	struct BandwidthGroup
860	{
861	BandwidthGroup();
862
863	bool operator==(const BandwidthGroup &i) const;
864
865	com::Utf8Str strName;
866	uint64_t cMaxBytesPerSec;
867	BandwidthGroupType_T enmType;
868	};
869
870	typedef std::list<BandwidthGroup> BandwidthGroupList;
871
872	/**
873	* NOTE: If you add any fields in here, you must update a) the constructor and b)
874	* the operator== which is used by MachineConfigFile::operator==(), or otherwise
875	* your settings might never get saved.
876	*/
877	struct IOSettings
878	{
879	IOSettings();
880
881	bool areIOCacheDefaultSettings() const;
882	bool areDefaultSettings() const;
883
884	bool operator==(const IOSettings &i) const;
885
886	bool fIOCacheEnabled;
887	uint32_t ulIOCacheSize;
888	BandwidthGroupList llBandwidthGroups;
889	};
890
891	/**
892	* NOTE: If you add any fields in here, you must update a) the constructor and b)
893	* the operator== which is used by MachineConfigFile::operator==(), or otherwise
894	* your settings might never get saved.
895	*/
896	struct HostPCIDeviceAttachment
897	{
898	HostPCIDeviceAttachment();
899
900	bool operator==(const HostPCIDeviceAttachment &a) const;
901
902	com::Utf8Str strDeviceName;
903	uint32_t uHostAddress;
904	uint32_t uGuestAddress;
905	};
906
907	typedef std::list<HostPCIDeviceAttachment> HostPCIDeviceAttachmentList;
908
909	/**
910	* A device attached to a storage controller. This can either be a
911	* hard disk or a DVD drive or a floppy drive and also specifies
912	* which medium is "in" the drive; as a result, this is a combination
913	* of the Main IMedium and IMediumAttachment interfaces.
914	*
915	* NOTE: If you add any fields in here, you must update a) the constructor and b)
916	* the operator== which is used by MachineConfigFile::operator==(), or otherwise
917	* your settings might never get saved.
918	*/
919	struct AttachedDevice
920	{
921	AttachedDevice();
922
923	bool operator==(const AttachedDevice &a) const;
924
925	DeviceType_T deviceType; // only HardDisk, DVD or Floppy are allowed
926
927	// DVDs can be in pass-through mode:
928	bool fPassThrough;
929
930	// Whether guest-triggered eject of DVDs will keep the medium in the
931	// VM config or not:
932	bool fTempEject;
933
934	// Whether the medium is non-rotational:
935	bool fNonRotational;
936
937	// Whether the medium supports discarding unused blocks:
938	bool fDiscard;
939
940	// Whether the medium is hot-pluggable:
941	bool fHotPluggable;
942
943	int32_t lPort;
944	int32_t lDevice;
945
946	// if an image file is attached to the device (ISO, RAW, or hard disk image such as VDI),
947	// this is its UUID; it depends on deviceType which media registry this then needs to
948	// be looked up in. If no image file (only permitted for DVDs and floppies), then the UUID is NULL
949	com::Guid uuid;
950
951	// for DVDs and floppies, the attachment can also be a host device:
952	com::Utf8Str strHostDriveSrc; // if != NULL, value of <HostDrive>/@src
953
954	// Bandwidth group the device is attached to.
955	com::Utf8Str strBwGroup;
956	};
957
958	typedef std::list<AttachedDevice> AttachedDevicesList;
959
960	/**
961	* NOTE: If you add any fields in here, you must update a) the constructor and b)
962	* the operator== which is used by MachineConfigFile::operator==(), or otherwise
963	* your settings might never get saved.
964	*/
965	struct StorageController
966	{
967	StorageController();
968
969	bool operator==(const StorageController &s) const;
970
971	com::Utf8Str strName;
972	StorageBus_T storageBus; // _SATA, _SCSI, _IDE, _SAS
973	StorageControllerType_T controllerType;
974	uint32_t ulPortCount;
975	uint32_t ulInstance;
976	bool fUseHostIOCache;
977	bool fBootable;
978
979	// only for when controllerType == StorageControllerType_IntelAhci:
980	int32_t lIDE0MasterEmulationPort,
981	lIDE0SlaveEmulationPort,
982	lIDE1MasterEmulationPort,
983	lIDE1SlaveEmulationPort;
984
985	AttachedDevicesList llAttachedDevices;
986	};
987
988	typedef std::list<StorageController> StorageControllersList;
989
990	/**
991	* We wrap the storage controllers list into an extra struct so we can
992	* use an undefined struct without needing std::list<> in all the headers.
993	*
994	* NOTE: If you add any fields in here, you must update a) the constructor and b)
995	* the operator== which is used by MachineConfigFile::operator==(), or otherwise
996	* your settings might never get saved.
997	*/
998	struct Storage
999	{
1000	bool operator==(const Storage &s) const;
1001
1002	StorageControllersList llStorageControllers;
1003	};
1004
1005	/**
1006	* Representation of Machine hardware; this is used in the MachineConfigFile.hardwareMachine
1007	* field.
1008	*
1009	* NOTE: If you add any fields in here, you must update a) the constructor and b)
1010	* the operator== which is used by MachineConfigFile::operator==(), or otherwise
1011	* your settings might never get saved.
1012	*/
1013	struct Hardware
1014	{
1015	Hardware();
1016
1017	bool areParavirtDefaultSettings(SettingsVersion_T sv) const;
1018	bool areBootOrderDefaultSettings() const;
1019	bool areDisplayDefaultSettings() const;
1020	bool areAllNetworkAdaptersDefaultSettings(SettingsVersion_T sv) const;
1021
1022	bool operator==(const Hardware&) const;
1023
1024	com::Utf8Str strVersion; // hardware version, optional
1025	com::Guid uuid; // hardware uuid, optional (null).
1026
1027	bool fHardwareVirt,
1028	fNestedPaging,
1029	fLargePages,
1030	fVPID,
1031	fUnrestrictedExecution,
1032	fHardwareVirtForce,
1033	fUseNativeApi,
1034	fSyntheticCpu,
1035	fTripleFaultReset,
1036	fPAE,
1037	fAPIC, // requires settings version 1.16 (VirtualBox 5.1)
1038	fX2APIC; // requires settings version 1.16 (VirtualBox 5.1)
1039	bool fIBPBOnVMExit; //< added out of cycle, after 1.16 was out.
1040	bool fIBPBOnVMEntry; //< added out of cycle, after 1.16 was out.
1041	bool fSpecCtrl; //< added out of cycle, after 1.16 was out.
1042	bool fSpecCtrlByHost; //< added out of cycle, after 1.16 was out.
1043	bool fL1DFlushOnSched ; //< added out of cycle, after 1.16 was out.
1044	bool fL1DFlushOnVMEntry ; //< added out of cycle, after 1.16 was out.
1045	bool fMDSClearOnSched; //< added out of cycle, after 1.16 was out.
1046	bool fMDSClearOnVMEntry; //< added out of cycle, after 1.16 was out.
1047	bool fNestedHWVirt; //< requires settings version 1.17 (VirtualBox 6.0)
1048	typedef enum LongModeType { LongMode_Enabled, LongMode_Disabled, LongMode_Legacy } LongModeType;
1049	LongModeType enmLongMode;
1050	uint32_t cCPUs;
1051	bool fCpuHotPlug; // requires settings version 1.10 (VirtualBox 3.2)
1052	CpuList llCpus; // requires settings version 1.10 (VirtualBox 3.2)
1053	bool fHPETEnabled; // requires settings version 1.10 (VirtualBox 3.2)
1054	uint32_t ulCpuExecutionCap; // requires settings version 1.11 (VirtualBox 3.3)
1055	uint32_t uCpuIdPortabilityLevel; // requires settings version 1.15 (VirtualBox 5.0)
1056	com::Utf8Str strCpuProfile; // requires settings version 1.16 (VirtualBox 5.1)
1057
1058	CpuIdLeafsList llCpuIdLeafs;
1059
1060	uint32_t ulMemorySizeMB;
1061
1062	BootOrderMap mapBootOrder; // item 0 has highest priority
1063
1064	GraphicsControllerType_T graphicsControllerType;
1065	uint32_t ulVRAMSizeMB;
1066	uint32_t cMonitors;
1067	bool fAccelerate3D,
1068	fAccelerate2DVideo; // requires settings version 1.8 (VirtualBox 3.1)
1069
1070	FirmwareType_T firmwareType; // requires settings version 1.9 (VirtualBox 3.1)
1071
1072	PointingHIDType_T pointingHIDType; // requires settings version 1.10 (VirtualBox 3.2)
1073	KeyboardHIDType_T keyboardHIDType; // requires settings version 1.10 (VirtualBox 3.2)
1074
1075	ChipsetType_T chipsetType; // requires settings version 1.11 (VirtualBox 4.0)
1076	ParavirtProvider_T paravirtProvider; // requires settings version 1.15 (VirtualBox 4.4)
1077	com::Utf8Str strParavirtDebug; // requires settings version 1.16 (VirtualBox 5.1)
1078
1079	bool fEmulatedUSBCardReader; // 1.12 (VirtualBox 4.1)
1080
1081	VRDESettings vrdeSettings;
1082
1083	BIOSSettings biosSettings;
1084	RecordingSettings recordingSettings;
1085	USB usbSettings;
1086	NetworkAdaptersList llNetworkAdapters;
1087	SerialPortsList llSerialPorts;
1088	ParallelPortsList llParallelPorts;
1089	AudioAdapter audioAdapter;
1090	Storage storage;
1091
1092	// technically these two have no business in the hardware section, but for some
1093	// clever reason <Hardware> is where they are in the XML....
1094	SharedFoldersList llSharedFolders;
1095	ClipboardMode_T clipboardMode;
1096	DnDMode_T dndMode;
1097
1098	uint32_t ulMemoryBalloonSize;
1099	bool fPageFusionEnabled;
1100
1101	GuestPropertiesList llGuestProperties;
1102
1103	IOSettings ioSettings; // requires settings version 1.10 (VirtualBox 3.2)
1104	HostPCIDeviceAttachmentList pciAttachments; // requires settings version 1.12 (VirtualBox 4.1)
1105
1106	com::Utf8Str strDefaultFrontend; // requires settings version 1.14 (VirtualBox 4.3)
1107	};
1108
1109	/**
1110	* Settings that has to do with debugging.
1111	*/
1112	struct Debugging
1113	{
1114	Debugging();
1115
1116	bool areDefaultSettings() const;
1117
1118	bool operator==(const Debugging &rOther) const;
1119
1120	bool fTracingEnabled;
1121	bool fAllowTracingToAccessVM;
1122	com::Utf8Str strTracingConfig;
1123	};
1124
1125	/**
1126	* Settings that has to do with autostart.
1127	*/
1128	struct Autostart
1129	{
1130	Autostart();
1131
1132	bool areDefaultSettings() const;
1133
1134	bool operator==(const Autostart &rOther) const;
1135
1136	bool fAutostartEnabled;
1137	uint32_t uAutostartDelay;
1138	AutostopType_T enmAutostopType;
1139	};
1140
1141	struct Snapshot;
1142	typedef std::list<Snapshot> SnapshotsList;
1143
1144	/**
1145	* NOTE: If you add any fields in here, you must update a) the constructor and b)
1146	* the operator== which is used by MachineConfigFile::operator==(), or otherwise
1147	* your settings might never get saved.
1148	*/
1149	struct Snapshot
1150	{
1151	Snapshot();
1152
1153	bool operator==(const Snapshot &s) const;
1154
1155	com::Guid uuid;
1156	com::Utf8Str strName,
1157	strDescription; // optional
1158	RTTIMESPEC timestamp;
1159
1160	com::Utf8Str strStateFile; // for online snapshots only
1161
1162	Hardware hardware;
1163
1164	Debugging debugging;
1165	Autostart autostart;
1166
1167	SnapshotsList llChildSnapshots;
1168
1169	static const struct Snapshot Empty;
1170	};
1171
1172	/**
1173	* NOTE: If you add any fields in here, you must update a) the constructor and b)
1174	* the operator== which is used by MachineConfigFile::operator==(), or otherwise
1175	* your settings might never get saved.
1176	*/
1177	struct MachineUserData
1178	{
1179	MachineUserData();
1180
1181	bool operator==(const MachineUserData &c) const;
1182
1183	com::Utf8Str strName;
1184	bool fDirectoryIncludesUUID;
1185	bool fNameSync;
1186	com::Utf8Str strDescription;
1187	StringsList llGroups;
1188	com::Utf8Str strOsType;
1189	com::Utf8Str strSnapshotFolder;
1190	bool fTeleporterEnabled;
1191	uint32_t uTeleporterPort;
1192	com::Utf8Str strTeleporterAddress;
1193	com::Utf8Str strTeleporterPassword;
1194	FaultToleranceState_T enmFaultToleranceState;
1195	uint32_t uFaultTolerancePort;
1196	com::Utf8Str strFaultToleranceAddress;
1197	com::Utf8Str strFaultTolerancePassword;
1198	uint32_t uFaultToleranceInterval;
1199	bool fRTCUseUTC;
1200	IconBlob ovIcon;
1201	VMProcPriority_T enmVMPriority;
1202	};
1203
1204
1205	/**
1206	* MachineConfigFile represents an XML machine configuration. All the machine settings
1207	* that go out to the XML (or are read from it) are in here.
1208	*
1209	* NOTE: If you add any fields in here, you must update a) the constructor and b)
1210	* the operator== which is used by Machine::saveSettings(), or otherwise your settings
1211	* might never get saved.
1212	*/
1213	class MachineConfigFile : public ConfigFileBase
1214	{
1215	public:
1216	com::Guid uuid;
1217
1218	MachineUserData machineUserData;
1219
1220	com::Utf8Str strStateFile;
1221	bool fCurrentStateModified; // optional, default is true
1222	RTTIMESPEC timeLastStateChange; // optional, defaults to now
1223	bool fAborted; // optional, default is false
1224
1225	com::Guid uuidCurrentSnapshot;
1226
1227	Hardware hardwareMachine;
1228	MediaRegistry mediaRegistry;
1229	Debugging debugging;
1230	Autostart autostart;
1231
1232	StringsMap mapExtraDataItems;
1233
1234	SnapshotsList llFirstSnapshot; // first snapshot or empty list if there's none
1235
1236	MachineConfigFile(const com::Utf8Str *pstrFilename);
1237
1238	bool operator==(const MachineConfigFile &m) const;
1239
1240	bool canHaveOwnMediaRegistry() const;
1241
1242	void importMachineXML(const xml::ElementNode &elmMachine);
1243
1244	void write(const com::Utf8Str &strFilename);
1245
1246	enum
1247	{
1248	BuildMachineXML_IncludeSnapshots = 0x01,
1249	BuildMachineXML_WriteVBoxVersionAttribute = 0x02,
1250	BuildMachineXML_SkipRemovableMedia = 0x04,
1251	BuildMachineXML_MediaRegistry = 0x08,
1252	BuildMachineXML_SuppressSavedState = 0x10
1253	};
1254	void buildMachineXML(xml::ElementNode &elmMachine,
1255	uint32_t fl,
1256	std::list<xml::ElementNode> pllElementsWithUuidAttributes);
1257
1258	static bool isAudioDriverAllowedOnThisHost(AudioDriverType_T drv);
1259	static AudioDriverType_T getHostDefaultAudioDriver();
1260
1261	private:
1262	void readNetworkAdapters(const xml::ElementNode &elmHardware, NetworkAdaptersList &ll);
1263	void readAttachedNetworkMode(const xml::ElementNode &pelmMode, bool fEnabled, NetworkAdapter &nic);
1264	void readCpuIdTree(const xml::ElementNode &elmCpuid, CpuIdLeafsList &ll);
1265	void readCpuTree(const xml::ElementNode &elmCpu, CpuList &ll);
1266	void readSerialPorts(const xml::ElementNode &elmUART, SerialPortsList &ll);
1267	void readParallelPorts(const xml::ElementNode &elmLPT, ParallelPortsList &ll);
1268	void readAudioAdapter(const xml::ElementNode &elmAudioAdapter, AudioAdapter &aa);
1269	void readGuestProperties(const xml::ElementNode &elmGuestProperties, Hardware &hw);
1270	void readStorageControllerAttributes(const xml::ElementNode &elmStorageController, StorageController &sctl);
1271	void readHardware(const xml::ElementNode &elmHardware, Hardware &hw);
1272	void readHardDiskAttachments_pre1_7(const xml::ElementNode &elmHardDiskAttachments, Storage &strg);
1273	void readStorageControllers(const xml::ElementNode &elmStorageControllers, Storage &strg);
1274	void readDVDAndFloppies_pre1_9(const xml::ElementNode &elmHardware, Storage &strg);
1275	void readTeleporter(const xml::ElementNode pElmTeleporter, MachineUserData pUserData);
1276	void readDebugging(const xml::ElementNode pElmDbg, Debugging pDbg);
1277	void readAutostart(const xml::ElementNode pElmAutostart, Autostart pAutostart);
1278	void readGroups(const xml::ElementNode elmGroups, StringsList pllGroups);
1279	bool readSnapshot(const com::Guid &curSnapshotUuid, uint32_t depth, const xml::ElementNode &elmSnapshot, Snapshot &snap);
1280	void convertOldOSType_pre1_5(com::Utf8Str &str);
1281	void readMachine(const xml::ElementNode &elmMachine);
1282
1283	void buildHardwareXML(xml::ElementNode &elmParent, const Hardware &hw, uint32_t fl, std::list<xml::ElementNode> pllElementsWithUuidAttributes);
1284	void buildNetworkXML(NetworkAttachmentType_T mode, bool fEnabled, xml::ElementNode &elmParent, const NetworkAdapter &nic);
1285	void buildStorageControllersXML(xml::ElementNode &elmParent,
1286	const Storage &st,
1287	bool fSkipRemovableMedia,
1288	std::list<xml::ElementNode> pllElementsWithUuidAttributes);
1289	void buildDebuggingXML(xml::ElementNode pElmParent, const Debugging pDbg);
1290	void buildAutostartXML(xml::ElementNode pElmParent, const Autostart pAutostart);
1291	void buildGroupsXML(xml::ElementNode pElmParent, const StringsList pllGroups);
1292	void buildSnapshotXML(uint32_t depth, xml::ElementNode &elmParent, const Snapshot &snap);
1293
1294	void bumpSettingsVersionIfNeeded();
1295	};
1296
1297	} // namespace settings
1298
1299
1300	#endif /* !VBOX_INCLUDED_settings_h */

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

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

Download in other formats: