settings.h@ 81299

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

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

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

Download in other formats: