settings.h@ 75380

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

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

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

Download in other formats: