settings.h@ 78345

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

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

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

Download in other formats: