settings.h@ 76450

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

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

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

Download in other formats: