settings.h@ 68699

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

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

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

Download in other formats: