settings.h@ 44948

Last change on this file since 44948 was 44948, checked in by vboxsync, 12 years ago
Main/SystemProperties+Machine: new config setting for default VM frontend. Frontend/VirtualBox+VBoxManage: changes to use the default VM frontend when starting a VM, other minor cleanups Main/xml/*.xsd: attempt to bring the XML schema close to reality doc/manual: document the new possibilities, and fix a few long standing inaccuracies
Property svn:eol-style set to `native` Property svn:keywords set to `Date Revision Author Id`
File size: 38.5 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-2013 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
53	namespace xml
54	{
55	class ElementNode;
56	}
57
58	namespace settings
59	{
60
61	class ConfigFileError;
62
63	////////////////////////////////////////////////////////////////////////////////
64	//
65	// Structures shared between Machine XML and VirtualBox.xml
66	//
67	////////////////////////////////////////////////////////////////////////////////
68
69	/**
70	* USB device filter definition. This struct is used both in MainConfigFile
71	* (for global USB filters) and MachineConfigFile (for machine filters).
72	*
73	* NOTE: If you add any fields in here, you must update a) the constructor and b)
74	* the operator== which is used by MachineConfigFile::operator==(), or otherwise
75	* your settings might never get saved.
76	*/
77	struct USBDeviceFilter
78	{
79	USBDeviceFilter()
80	: fActive(false),
81	action(USBDeviceFilterAction_Null),
82	ulMaskedInterfaces(0)
83	{}
84
85	bool operator==(const USBDeviceFilter&u) const;
86
87	com::Utf8Str strName;
88	bool fActive;
89	com::Utf8Str strVendorId,
90	strProductId,
91	strRevision,
92	strManufacturer,
93	strProduct,
94	strSerialNumber,
95	strPort;
96	USBDeviceFilterAction_T action; // only used with host USB filters
97	com::Utf8Str strRemote; // irrelevant for host USB objects
98	uint32_t ulMaskedInterfaces; // irrelevant for host USB objects
99	};
100
101	typedef std::map<com::Utf8Str, com::Utf8Str> StringsMap;
102	typedef std::list<com::Utf8Str> StringsList;
103
104	// ExtraDataItem (used by both VirtualBox.xml and machines XML)
105	struct USBDeviceFilter;
106	typedef std::list<USBDeviceFilter> USBDeviceFiltersList;
107
108	struct Medium;
109	typedef std::list<Medium> MediaList;
110
111	/**
112	* NOTE: If you add any fields in here, you must update a) the constructor and b)
113	* the operator== which is used by MachineConfigFile::operator==(), or otherwise
114	* your settings might never get saved.
115	*/
116	struct Medium
117	{
118	Medium()
119	: fAutoReset(false),
120	hdType(MediumType_Normal)
121	{}
122
123	com::Guid uuid;
124	com::Utf8Str strLocation;
125	com::Utf8Str strDescription;
126
127	// the following are for hard disks only:
128	com::Utf8Str strFormat;
129	bool fAutoReset; // optional, only for diffs, default is false
130	StringsMap properties;
131	MediumType_T hdType;
132
133	MediaList llChildren; // only used with hard disks
134
135	bool operator==(const Medium &m) const;
136	};
137
138	/**
139	* A media registry. Starting with VirtualBox 3.3, this can appear in both the
140	* VirtualBox.xml file as well as machine XML files with settings version 1.11
141	* or higher, so these lists are now in ConfigFileBase.
142	*
143	* NOTE: If you add any fields in here, you must update a) the constructor and b)
144	* the operator== which is used by MachineConfigFile::operator==(), or otherwise
145	* your settings might never get saved.
146	*/
147	struct MediaRegistry
148	{
149	MediaList llHardDisks,
150	llDvdImages,
151	llFloppyImages;
152
153	bool operator==(const MediaRegistry &m) const;
154	};
155
156	/**
157	* Common base class for both MainConfigFile and MachineConfigFile
158	* which contains some common logic for both.
159	*/
160	class ConfigFileBase
161	{
162	public:
163	bool fileExists();
164
165	void copyBaseFrom(const ConfigFileBase &b);
166
167	protected:
168	ConfigFileBase(const com::Utf8Str *pstrFilename);
169	/* Note: this copy constructor doesn't create a full copy of other, cause
170	* the file based stuff (xml doc) could not be copied. */
171	ConfigFileBase(const ConfigFileBase &other);
172
173	~ConfigFileBase();
174
175	void parseUUID(com::Guid &guid,
176	const com::Utf8Str &strUUID) const;
177	void parseTimestamp(RTTIMESPEC &timestamp,
178	const com::Utf8Str &str) const;
179
180	com::Utf8Str makeString(const RTTIMESPEC &tm);
181
182	void readExtraData(const xml::ElementNode &elmExtraData,
183	StringsMap &map);
184	void readUSBDeviceFilters(const xml::ElementNode &elmDeviceFilters,
185	USBDeviceFiltersList &ll);
186	typedef enum {Error, HardDisk, DVDImage, FloppyImage} MediaType;
187	void readMedium(MediaType t, const xml::ElementNode &elmMedium, MediaList &llMedia);
188	void readMediaRegistry(const xml::ElementNode &elmMediaRegistry, MediaRegistry &mr);
189
190	void setVersionAttribute(xml::ElementNode &elm);
191	void createStubDocument();
192
193	void buildExtraData(xml::ElementNode &elmParent, const StringsMap &me);
194	void buildUSBDeviceFilters(xml::ElementNode &elmParent,
195	const USBDeviceFiltersList &ll,
196	bool fHostMode);
197	void buildMedium(xml::ElementNode &elmMedium,
198	DeviceType_T devType,
199	const Medium &m,
200	uint32_t level);
201	void buildMediaRegistry(xml::ElementNode &elmParent,
202	const MediaRegistry &mr);
203	void clearDocument();
204
205	struct Data;
206	Data *m;
207
208	friend class ConfigFileError;
209	};
210
211	////////////////////////////////////////////////////////////////////////////////
212	//
213	// VirtualBox.xml structures
214	//
215	////////////////////////////////////////////////////////////////////////////////
216
217	struct Host
218	{
219	USBDeviceFiltersList llUSBDeviceFilters;
220	};
221
222	struct SystemProperties
223	{
224	SystemProperties()
225	: ulLogHistoryCount(3)
226	{}
227
228	com::Utf8Str strDefaultMachineFolder;
229	com::Utf8Str strDefaultHardDiskFolder;
230	com::Utf8Str strDefaultHardDiskFormat;
231	com::Utf8Str strVRDEAuthLibrary;
232	com::Utf8Str strWebServiceAuthLibrary;
233	com::Utf8Str strDefaultVRDEExtPack;
234	com::Utf8Str strAutostartDatabasePath;
235	com::Utf8Str strDefaultAdditionsISO;
236	com::Utf8Str strDefaultFrontend;
237	uint32_t ulLogHistoryCount;
238	};
239
240	struct MachineRegistryEntry
241	{
242	com::Guid uuid;
243	com::Utf8Str strSettingsFile;
244	};
245	typedef std::list<MachineRegistryEntry> MachinesRegistry;
246
247	struct DHCPServer
248	{
249	DHCPServer()
250	: fEnabled(false)
251	{}
252
253	com::Utf8Str strNetworkName,
254	strIPAddress,
255	strIPNetworkMask,
256	strIPLower,
257	strIPUpper;
258	bool fEnabled;
259	};
260	typedef std::list<DHCPServer> DHCPServersList;
261
262	class MainConfigFile : public ConfigFileBase
263	{
264	public:
265	MainConfigFile(const com::Utf8Str *pstrFilename);
266
267	void readMachineRegistry(const xml::ElementNode &elmMachineRegistry);
268	void readDHCPServers(const xml::ElementNode &elmDHCPServers);
269
270	void write(const com::Utf8Str strFilename);
271
272	Host host;
273	SystemProperties systemProperties;
274	MediaRegistry mediaRegistry;
275	MachinesRegistry llMachines;
276	DHCPServersList llDhcpServers;
277	StringsMap mapExtraDataItems;
278	};
279
280	////////////////////////////////////////////////////////////////////////////////
281	//
282	// Machine XML structures
283	//
284	////////////////////////////////////////////////////////////////////////////////
285
286	/**
287	* NOTE: If you add any fields in here, you must update a) the constructor and b)
288	* the operator== which is used by MachineConfigFile::operator==(), or otherwise
289	* your settings might never get saved.
290	*/
291	struct VRDESettings
292	{
293	VRDESettings()
294	: fEnabled(true),
295	authType(AuthType_Null),
296	ulAuthTimeout(5000),
297	fAllowMultiConnection(false),
298	fReuseSingleConnection(false)
299	{}
300
301	bool operator==(const VRDESettings& v) const;
302
303	bool fEnabled;
304	AuthType_T authType;
305	uint32_t ulAuthTimeout;
306	com::Utf8Str strAuthLibrary;
307	bool fAllowMultiConnection,
308	fReuseSingleConnection;
309	com::Utf8Str strVrdeExtPack;
310	StringsMap mapProperties;
311	};
312
313	/**
314	* NOTE: If you add any fields in here, you must update a) the constructor and b)
315	* the operator== which is used by MachineConfigFile::operator==(), or otherwise
316	* your settings might never get saved.
317	*/
318	struct BIOSSettings
319	{
320	BIOSSettings()
321	: fACPIEnabled(true),
322	fIOAPICEnabled(false),
323	fLogoFadeIn(true),
324	fLogoFadeOut(true),
325	ulLogoDisplayTime(0),
326	biosBootMenuMode(BIOSBootMenuMode_MessageAndMenu),
327	fPXEDebugEnabled(false),
328	llTimeOffset(0)
329	{}
330
331	bool operator==(const BIOSSettings &d) const;
332
333	bool fACPIEnabled,
334	fIOAPICEnabled,
335	fLogoFadeIn,
336	fLogoFadeOut;
337	uint32_t ulLogoDisplayTime;
338	com::Utf8Str strLogoImagePath;
339	BIOSBootMenuMode_T biosBootMenuMode;
340	bool fPXEDebugEnabled;
341	int64_t llTimeOffset;
342	};
343
344	/**
345	* NOTE: If you add any fields in here, you must update a) the constructor and b)
346	* the operator== which is used by MachineConfigFile::operator==(), or otherwise
347	* your settings might never get saved.
348	*/
349	struct USBController
350	{
351	USBController()
352	: fEnabled(false),
353	fEnabledEHCI(false)
354	{}
355
356	bool operator==(const USBController &u) const;
357
358	bool fEnabled;
359	bool fEnabledEHCI;
360	USBDeviceFiltersList llDeviceFilters;
361	};
362
363	struct NATRule
364	{
365	NATRule()
366	: proto(NATProtocol_TCP),
367	u16HostPort(0),
368	u16GuestPort(0)
369	{}
370
371	bool operator==(const NATRule &r) const
372	{
373	return strName == r.strName
374	&& proto == r.proto
375	&& u16HostPort == r.u16HostPort
376	&& strHostIP == r.strHostIP
377	&& u16GuestPort == r.u16GuestPort
378	&& strGuestIP == r.strGuestIP;
379	}
380
381	com::Utf8Str strName;
382	NATProtocol_T proto;
383	uint16_t u16HostPort;
384	com::Utf8Str strHostIP;
385	uint16_t u16GuestPort;
386	com::Utf8Str strGuestIP;
387	};
388	typedef std::list<NATRule> NATRuleList;
389
390	struct NAT
391	{
392	NAT()
393	: u32Mtu(0),
394	u32SockRcv(0),
395	u32SockSnd(0),
396	u32TcpRcv(0),
397	u32TcpSnd(0),
398	fDNSPassDomain(true), /* historically this value is true */
399	fDNSProxy(false),
400	fDNSUseHostResolver(false),
401	fAliasLog(false),
402	fAliasProxyOnly(false),
403	fAliasUseSamePorts(false)
404	{}
405
406	bool operator==(const NAT &n) const
407	{
408	return strNetwork == n.strNetwork
409	&& strBindIP == n.strBindIP
410	&& u32Mtu == n.u32Mtu
411	&& u32SockRcv == n.u32SockRcv
412	&& u32SockSnd == n.u32SockSnd
413	&& u32TcpSnd == n.u32TcpSnd
414	&& u32TcpRcv == n.u32TcpRcv
415	&& strTFTPPrefix == n.strTFTPPrefix
416	&& strTFTPBootFile == n.strTFTPBootFile
417	&& strTFTPNextServer == n.strTFTPNextServer
418	&& fDNSPassDomain == n.fDNSPassDomain
419	&& fDNSProxy == n.fDNSProxy
420	&& fDNSUseHostResolver == n.fDNSUseHostResolver
421	&& fAliasLog == n.fAliasLog
422	&& fAliasProxyOnly == n.fAliasProxyOnly
423	&& fAliasUseSamePorts == n.fAliasUseSamePorts
424	&& llRules == n.llRules;
425	}
426
427	com::Utf8Str strNetwork;
428	com::Utf8Str strBindIP;
429	uint32_t u32Mtu;
430	uint32_t u32SockRcv;
431	uint32_t u32SockSnd;
432	uint32_t u32TcpRcv;
433	uint32_t u32TcpSnd;
434	com::Utf8Str strTFTPPrefix;
435	com::Utf8Str strTFTPBootFile;
436	com::Utf8Str strTFTPNextServer;
437	bool fDNSPassDomain;
438	bool fDNSProxy;
439	bool fDNSUseHostResolver;
440	bool fAliasLog;
441	bool fAliasProxyOnly;
442	bool fAliasUseSamePorts;
443	NATRuleList llRules;
444	};
445	/**
446	* NOTE: If you add any fields in here, you must update a) the constructor and b)
447	* the operator== which is used by MachineConfigFile::operator==(), or otherwise
448	* your settings might never get saved.
449	*/
450	struct NetworkAdapter
451	{
452	NetworkAdapter()
453	: ulSlot(0),
454	type(NetworkAdapterType_Am79C970A),
455	fEnabled(false),
456	fCableConnected(false),
457	ulLineSpeed(0),
458	enmPromiscModePolicy(NetworkAdapterPromiscModePolicy_Deny),
459	fTraceEnabled(false),
460	mode(NetworkAttachmentType_Null),
461	ulBootPriority(0)
462	{}
463
464	bool operator==(const NetworkAdapter &n) const;
465
466	uint32_t ulSlot;
467
468	NetworkAdapterType_T type;
469	bool fEnabled;
470	com::Utf8Str strMACAddress;
471	bool fCableConnected;
472	uint32_t ulLineSpeed;
473	NetworkAdapterPromiscModePolicy_T enmPromiscModePolicy;
474	bool fTraceEnabled;
475	com::Utf8Str strTraceFile;
476
477	NetworkAttachmentType_T mode;
478	NAT nat;
479	com::Utf8Str strBridgedName;
480	com::Utf8Str strHostOnlyName;
481	com::Utf8Str strInternalNetworkName;
482	com::Utf8Str strGenericDriver;
483	StringsMap genericProperties;
484	uint32_t ulBootPriority;
485	com::Utf8Str strBandwidthGroup; // requires settings version 1.13 (VirtualBox 4.2)
486	};
487	typedef std::list<NetworkAdapter> NetworkAdaptersList;
488
489	/**
490	* NOTE: If you add any fields in here, you must update a) the constructor and b)
491	* the operator== which is used by MachineConfigFile::operator==(), or otherwise
492	* your settings might never get saved.
493	*/
494	struct SerialPort
495	{
496	SerialPort()
497	: ulSlot(0),
498	fEnabled(false),
499	ulIOBase(0x3f8),
500	ulIRQ(4),
501	portMode(PortMode_Disconnected),
502	fServer(false)
503	{}
504
505	bool operator==(const SerialPort &n) const;
506
507	uint32_t ulSlot;
508
509	bool fEnabled;
510	uint32_t ulIOBase;
511	uint32_t ulIRQ;
512	PortMode_T portMode;
513	com::Utf8Str strPath;
514	bool fServer;
515	};
516	typedef std::list<SerialPort> SerialPortsList;
517
518	/**
519	* NOTE: If you add any fields in here, you must update a) the constructor and b)
520	* the operator== which is used by MachineConfigFile::operator==(), or otherwise
521	* your settings might never get saved.
522	*/
523	struct ParallelPort
524	{
525	ParallelPort()
526	: ulSlot(0),
527	fEnabled(false),
528	ulIOBase(0x378),
529	ulIRQ(7)
530	{}
531
532	bool operator==(const ParallelPort &d) const;
533
534	uint32_t ulSlot;
535
536	bool fEnabled;
537	uint32_t ulIOBase;
538	uint32_t ulIRQ;
539	com::Utf8Str strPath;
540	};
541	typedef std::list<ParallelPort> ParallelPortsList;
542
543	/**
544	* NOTE: If you add any fields in here, you must update a) the constructor and b)
545	* the operator== which is used by MachineConfigFile::operator==(), or otherwise
546	* your settings might never get saved.
547	*/
548	struct AudioAdapter
549	{
550	AudioAdapter()
551	: fEnabled(true),
552	controllerType(AudioControllerType_AC97),
553	driverType(AudioDriverType_Null)
554	{}
555
556	bool operator==(const AudioAdapter &a) const
557	{
558	return (this == &a)
559	\|\| ( (fEnabled == a.fEnabled)
560	&& (controllerType == a.controllerType)
561	&& (driverType == a.driverType)
562	);
563	}
564
565	bool fEnabled;
566	AudioControllerType_T controllerType;
567	AudioDriverType_T driverType;
568	};
569
570	/**
571	* NOTE: If you add any fields in here, you must update a) the constructor and b)
572	* the operator== which is used by MachineConfigFile::operator==(), or otherwise
573	* your settings might never get saved.
574	*/
575	struct SharedFolder
576	{
577	SharedFolder()
578	: fWritable(false)
579	, fAutoMount(false)
580	{}
581
582	bool operator==(const SharedFolder &a) const;
583
584	com::Utf8Str strName,
585	strHostPath;
586	bool fWritable;
587	bool fAutoMount;
588	};
589	typedef std::list<SharedFolder> SharedFoldersList;
590
591	/**
592	* NOTE: If you add any fields in here, you must update a) the constructor and b)
593	* the operator== which is used by MachineConfigFile::operator==(), or otherwise
594	* your settings might never get saved.
595	*/
596	struct GuestProperty
597	{
598	GuestProperty()
599	: timestamp(0)
600	{};
601
602	bool operator==(const GuestProperty &g) const;
603
604	com::Utf8Str strName,
605	strValue;
606	uint64_t timestamp;
607	com::Utf8Str strFlags;
608	};
609	typedef std::list<GuestProperty> GuestPropertiesList;
610
611	typedef std::map<uint32_t, DeviceType_T> BootOrderMap;
612
613	/**
614	* NOTE: If you add any fields in here, you must update a) the constructor and b)
615	* the operator== which is used by MachineConfigFile::operator==(), or otherwise
616	* your settings might never get saved.
617	*/
618	struct CpuIdLeaf
619	{
620	CpuIdLeaf()
621	: ulId(UINT32_MAX),
622	ulEax(0),
623	ulEbx(0),
624	ulEcx(0),
625	ulEdx(0)
626	{}
627
628	bool operator==(const CpuIdLeaf &c) const
629	{
630	return ( (this == &c)
631	\|\| ( (ulId == c.ulId)
632	&& (ulEax == c.ulEax)
633	&& (ulEbx == c.ulEbx)
634	&& (ulEcx == c.ulEcx)
635	&& (ulEdx == c.ulEdx)
636	)
637	);
638	}
639
640	uint32_t ulId;
641	uint32_t ulEax;
642	uint32_t ulEbx;
643	uint32_t ulEcx;
644	uint32_t ulEdx;
645	};
646	typedef std::list<CpuIdLeaf> CpuIdLeafsList;
647
648	/**
649	* NOTE: If you add any fields in here, you must update a) the constructor and b)
650	* the operator== which is used by MachineConfigFile::operator==(), or otherwise
651	* your settings might never get saved.
652	*/
653	struct Cpu
654	{
655	Cpu()
656	: ulId(UINT32_MAX)
657	{}
658
659	bool operator==(const Cpu &c) const
660	{
661	return (ulId == c.ulId);
662	}
663
664	uint32_t ulId;
665	};
666	typedef std::list<Cpu> CpuList;
667
668	/**
669	* NOTE: If you add any fields in here, you must update a) the constructor and b)
670	* the operator== which is used by MachineConfigFile::operator==(), or otherwise
671	* your settings might never get saved.
672	*/
673	struct BandwidthGroup
674	{
675	BandwidthGroup()
676	: cMaxBytesPerSec(0),
677	enmType(BandwidthGroupType_Null)
678	{}
679
680	bool operator==(const BandwidthGroup &i) const
681	{
682	return ( (strName == i.strName)
683	&& (cMaxBytesPerSec == i.cMaxBytesPerSec)
684	&& (enmType == i.enmType));
685	}
686
687	com::Utf8Str strName;
688	uint64_t cMaxBytesPerSec;
689	BandwidthGroupType_T enmType;
690	};
691	typedef std::list<BandwidthGroup> BandwidthGroupList;
692
693	/**
694	* NOTE: If you add any fields in here, you must update a) the constructor and b)
695	* the operator== which is used by MachineConfigFile::operator==(), or otherwise
696	* your settings might never get saved.
697	*/
698	struct IOSettings
699	{
700	IOSettings();
701
702	bool operator==(const IOSettings &i) const
703	{
704	return ( (fIOCacheEnabled == i.fIOCacheEnabled)
705	&& (ulIOCacheSize == i.ulIOCacheSize)
706	&& (llBandwidthGroups == i.llBandwidthGroups));
707	}
708
709	bool fIOCacheEnabled;
710	uint32_t ulIOCacheSize;
711	BandwidthGroupList llBandwidthGroups;
712	};
713
714	/**
715	* NOTE: If you add any fields in here, you must update a) the constructor and b)
716	* the operator== which is used by MachineConfigFile::operator==(), or otherwise
717	* your settings might never get saved.
718	*/
719	struct HostPCIDeviceAttachment
720	{
721	HostPCIDeviceAttachment()
722	: uHostAddress(0),
723	uGuestAddress(0)
724	{}
725
726	bool operator==(const HostPCIDeviceAttachment &a) const
727	{
728	return ( (uHostAddress == a.uHostAddress)
729	&& (uGuestAddress == a.uGuestAddress)
730	&& (strDeviceName == a.strDeviceName)
731	);
732	}
733
734	com::Utf8Str strDeviceName;
735	uint32_t uHostAddress;
736	uint32_t uGuestAddress;
737	};
738	typedef std::list<HostPCIDeviceAttachment> HostPCIDeviceAttachmentList;
739
740	/**
741	* Representation of Machine hardware; this is used in the MachineConfigFile.hardwareMachine
742	* field.
743	*
744	* NOTE: If you add any fields in here, you must update a) the constructor and b)
745	* the operator== which is used by MachineConfigFile::operator==(), or otherwise
746	* your settings might never get saved.
747	*/
748	struct Hardware
749	{
750	Hardware();
751
752	bool operator==(const Hardware&) const;
753
754	com::Utf8Str strVersion; // hardware version, optional
755	com::Guid uuid; // hardware uuid, optional (null).
756
757	bool fHardwareVirt,
758	fHardwareVirtExclusive,
759	fNestedPaging,
760	fLargePages,
761	fVPID,
762	fHardwareVirtForce,
763	fSyntheticCpu,
764	fPAE;
765	uint32_t cCPUs;
766	bool fCpuHotPlug; // requires settings version 1.10 (VirtualBox 3.2)
767	CpuList llCpus; // requires settings version 1.10 (VirtualBox 3.2)
768	bool fHPETEnabled; // requires settings version 1.10 (VirtualBox 3.2)
769	uint32_t ulCpuExecutionCap; // requires settings version 1.11 (VirtualBox 3.3)
770
771	CpuIdLeafsList llCpuIdLeafs;
772
773	uint32_t ulMemorySizeMB;
774
775	BootOrderMap mapBootOrder; // item 0 has highest priority
776
777	uint32_t ulVRAMSizeMB;
778	uint32_t cMonitors;
779	bool fAccelerate3D,
780	fAccelerate2DVideo; // requires settings version 1.8 (VirtualBox 3.1)
781	uint32_t ulVideoCaptureHorzRes;
782	uint32_t ulVideoCaptureVertRes;
783	bool fVideoCaptureEnabled;
784	com::Utf8Str strVideoCaptureFile;
785	FirmwareType_T firmwareType; // requires settings version 1.9 (VirtualBox 3.1)
786
787	PointingHIDType_T pointingHIDType; // requires settings version 1.10 (VirtualBox 3.2)
788	KeyboardHIDType_T keyboardHIDType; // requires settings version 1.10 (VirtualBox 3.2)
789
790	ChipsetType_T chipsetType; // requires settings version 1.11 (VirtualBox 4.0)
791
792	bool fEmulatedUSBWebcam; // 1.13 (VirtualBox 4.2)
793	bool fEmulatedUSBCardReader; // 1.12 (VirtualBox 4.1)
794
795	VRDESettings vrdeSettings;
796
797	BIOSSettings biosSettings;
798	USBController usbController;
799	NetworkAdaptersList llNetworkAdapters;
800	SerialPortsList llSerialPorts;
801	ParallelPortsList llParallelPorts;
802	AudioAdapter audioAdapter;
803
804	// technically these two have no business in the hardware section, but for some
805	// clever reason <Hardware> is where they are in the XML....
806	SharedFoldersList llSharedFolders;
807	ClipboardMode_T clipboardMode;
808	DragAndDropMode_T dragAndDropMode;
809
810	uint32_t ulMemoryBalloonSize;
811	bool fPageFusionEnabled;
812
813	GuestPropertiesList llGuestProperties;
814	com::Utf8Str strNotificationPatterns;
815
816	IOSettings ioSettings; // requires settings version 1.10 (VirtualBox 3.2)
817	HostPCIDeviceAttachmentList pciAttachments; // requires settings version 1.12 (VirtualBox 4.1)
818
819	com::Utf8Str strDefaultFrontend; // requires settings version 1.14 (VirtualBox 4.3)
820	};
821
822	/**
823	* A device attached to a storage controller. This can either be a
824	* hard disk or a DVD drive or a floppy drive and also specifies
825	* which medium is "in" the drive; as a result, this is a combination
826	* of the Main IMedium and IMediumAttachment interfaces.
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 AttachedDevice
833	{
834	AttachedDevice()
835	: deviceType(DeviceType_Null),
836	fPassThrough(false),
837	fTempEject(false),
838	fNonRotational(false),
839	lPort(0),
840	lDevice(0)
841	{}
842
843	bool operator==(const AttachedDevice &a) const;
844
845	DeviceType_T deviceType; // only HardDisk, DVD or Floppy are allowed
846
847	// DVDs can be in pass-through mode:
848	bool fPassThrough;
849
850	// Whether guest-triggered eject of DVDs will keep the medium in the
851	// VM config or not:
852	bool fTempEject;
853
854	// Whether the medium is non-rotational:
855	bool fNonRotational;
856
857	// Whether the medium supports discarding unused blocks:
858	bool fDiscard;
859
860	int32_t lPort;
861	int32_t lDevice;
862
863	// if an image file is attached to the device (ISO, RAW, or hard disk image such as VDI),
864	// this is its UUID; it depends on deviceType which media registry this then needs to
865	// be looked up in. If no image file (only permitted for DVDs and floppies), then the UUID is NULL
866	com::Guid uuid;
867
868	// for DVDs and floppies, the attachment can also be a host device:
869	com::Utf8Str strHostDriveSrc; // if != NULL, value of <HostDrive>/@src
870
871	// Bandwidth group the device is attached to.
872	com::Utf8Str strBwGroup;
873	};
874	typedef std::list<AttachedDevice> AttachedDevicesList;
875
876	/**
877	* NOTE: If you add any fields in here, you must update a) the constructor and b)
878	* the operator== which is used by MachineConfigFile::operator==(), or otherwise
879	* your settings might never get saved.
880	*/
881	struct StorageController
882	{
883	StorageController()
884	: storageBus(StorageBus_IDE),
885	controllerType(StorageControllerType_PIIX3),
886	ulPortCount(2),
887	ulInstance(0),
888	fUseHostIOCache(true),
889	fBootable(true),
890	lIDE0MasterEmulationPort(0),
891	lIDE0SlaveEmulationPort(0),
892	lIDE1MasterEmulationPort(0),
893	lIDE1SlaveEmulationPort(0)
894	{}
895
896	bool operator==(const StorageController &s) const;
897
898	com::Utf8Str strName;
899	StorageBus_T storageBus; // _SATA, _SCSI, _IDE, _SAS
900	StorageControllerType_T controllerType;
901	uint32_t ulPortCount;
902	uint32_t ulInstance;
903	bool fUseHostIOCache;
904	bool fBootable;
905
906	// only for when controllerType == StorageControllerType_IntelAhci:
907	int32_t lIDE0MasterEmulationPort,
908	lIDE0SlaveEmulationPort,
909	lIDE1MasterEmulationPort,
910	lIDE1SlaveEmulationPort;
911
912	AttachedDevicesList llAttachedDevices;
913	};
914	typedef std::list<StorageController> StorageControllersList;
915
916	/**
917	* We wrap the storage controllers list into an extra struct so we can
918	* use an undefined struct without needing std::list<> in all the headers.
919	*
920	* NOTE: If you add any fields in here, you must update a) the constructor and b)
921	* the operator== which is used by MachineConfigFile::operator==(), or otherwise
922	* your settings might never get saved.
923	*/
924	struct Storage
925	{
926	bool operator==(const Storage &s) const;
927
928	StorageControllersList llStorageControllers;
929	};
930
931	/**
932	* Settings that has to do with debugging.
933	*/
934	struct Debugging
935	{
936	Debugging()
937	: fTracingEnabled(false),
938	fAllowTracingToAccessVM(false),
939	strTracingConfig()
940	{ }
941
942	bool operator==(const Debugging &rOther) const
943	{
944	return fTracingEnabled == rOther.fTracingEnabled
945	&& fAllowTracingToAccessVM == rOther.fAllowTracingToAccessVM
946	&& strTracingConfig == rOther.strTracingConfig;
947	}
948
949	bool areDefaultSettings() const
950	{
951	return !fTracingEnabled
952	&& !fAllowTracingToAccessVM
953	&& strTracingConfig.isEmpty();
954	}
955
956	bool fTracingEnabled;
957	bool fAllowTracingToAccessVM;
958	com::Utf8Str strTracingConfig;
959	};
960
961	/**
962	* Settings that has to do with autostart.
963	*/
964	struct Autostart
965	{
966	Autostart()
967	: fAutostartEnabled(false),
968	uAutostartDelay(0),
969	enmAutostopType(AutostopType_Disabled)
970	{ }
971
972	bool operator==(const Autostart &rOther) const
973	{
974	return fAutostartEnabled == rOther.fAutostartEnabled
975	&& uAutostartDelay == rOther.uAutostartDelay
976	&& enmAutostopType == rOther.enmAutostopType;
977	}
978
979	bool areDefaultSettings() const
980	{
981	return !fAutostartEnabled
982	&& !uAutostartDelay
983	&& enmAutostopType == AutostopType_Disabled;
984	}
985
986	bool fAutostartEnabled;
987	uint32_t uAutostartDelay;
988	AutostopType_T enmAutostopType;
989	};
990
991	struct Snapshot;
992	typedef std::list<Snapshot> SnapshotsList;
993
994	/**
995	* NOTE: If you add any fields in here, you must update a) the constructor and b)
996	* the operator== which is used by MachineConfigFile::operator==(), or otherwise
997	* your settings might never get saved.
998	*/
999	struct Snapshot
1000	{
1001	bool operator==(const Snapshot &s) const;
1002
1003	com::Guid uuid;
1004	com::Utf8Str strName,
1005	strDescription; // optional
1006	RTTIMESPEC timestamp;
1007
1008	com::Utf8Str strStateFile; // for online snapshots only
1009
1010	Hardware hardware;
1011	Storage storage;
1012
1013	Debugging debugging;
1014	Autostart autostart;
1015
1016	SnapshotsList llChildSnapshots;
1017	};
1018
1019	struct MachineUserData
1020	{
1021	MachineUserData()
1022	: fDirectoryIncludesUUID(false),
1023	fNameSync(true),
1024	fTeleporterEnabled(false),
1025	uTeleporterPort(0),
1026	enmFaultToleranceState(FaultToleranceState_Inactive),
1027	uFaultTolerancePort(0),
1028	uFaultToleranceInterval(0),
1029	fRTCUseUTC(false)
1030	{
1031	llGroups.push_back("/");
1032	}
1033
1034	bool operator==(const MachineUserData &c) const
1035	{
1036	return (strName == c.strName)
1037	&& (fDirectoryIncludesUUID == c.fDirectoryIncludesUUID)
1038	&& (fNameSync == c.fNameSync)
1039	&& (strDescription == c.strDescription)
1040	&& (llGroups == c.llGroups)
1041	&& (strOsType == c.strOsType)
1042	&& (strSnapshotFolder == c.strSnapshotFolder)
1043	&& (fTeleporterEnabled == c.fTeleporterEnabled)
1044	&& (uTeleporterPort == c.uTeleporterPort)
1045	&& (strTeleporterAddress == c.strTeleporterAddress)
1046	&& (strTeleporterPassword == c.strTeleporterPassword)
1047	&& (enmFaultToleranceState == c.enmFaultToleranceState)
1048	&& (uFaultTolerancePort == c.uFaultTolerancePort)
1049	&& (uFaultToleranceInterval == c.uFaultToleranceInterval)
1050	&& (strFaultToleranceAddress == c.strFaultToleranceAddress)
1051	&& (strFaultTolerancePassword == c.strFaultTolerancePassword)
1052	&& (fRTCUseUTC == c.fRTCUseUTC);
1053	}
1054
1055	com::Utf8Str strName;
1056	bool fDirectoryIncludesUUID;
1057	bool fNameSync;
1058	com::Utf8Str strDescription;
1059	StringsList llGroups;
1060	com::Utf8Str strOsType;
1061	com::Utf8Str strSnapshotFolder;
1062	bool fTeleporterEnabled;
1063	uint32_t uTeleporterPort;
1064	com::Utf8Str strTeleporterAddress;
1065	com::Utf8Str strTeleporterPassword;
1066	FaultToleranceState_T enmFaultToleranceState;
1067	uint32_t uFaultTolerancePort;
1068	com::Utf8Str strFaultToleranceAddress;
1069	com::Utf8Str strFaultTolerancePassword;
1070	uint32_t uFaultToleranceInterval;
1071	bool fRTCUseUTC;
1072	};
1073
1074	/**
1075	* MachineConfigFile represents an XML machine configuration. All the machine settings
1076	* that go out to the XML (or are read from it) are in here.
1077	*
1078	* NOTE: If you add any fields in here, you must update a) the constructor and b)
1079	* the operator== which is used by Machine::saveSettings(), or otherwise your settings
1080	* might never get saved.
1081	*/
1082	class MachineConfigFile : public ConfigFileBase
1083	{
1084	public:
1085	com::Guid uuid;
1086
1087	MachineUserData machineUserData;
1088
1089	com::Utf8Str strStateFile;
1090	bool fCurrentStateModified; // optional, default is true
1091	RTTIMESPEC timeLastStateChange; // optional, defaults to now
1092	bool fAborted; // optional, default is false
1093
1094	com::Guid uuidCurrentSnapshot;
1095
1096	Hardware hardwareMachine;
1097	Storage storageMachine;
1098	MediaRegistry mediaRegistry;
1099	Debugging debugging;
1100	Autostart autostart;
1101
1102	StringsMap mapExtraDataItems;
1103
1104	SnapshotsList llFirstSnapshot; // first snapshot or empty list if there's none
1105
1106	MachineConfigFile(const com::Utf8Str *pstrFilename);
1107
1108	bool operator==(const MachineConfigFile &m) const;
1109
1110	bool canHaveOwnMediaRegistry() const;
1111
1112	void importMachineXML(const xml::ElementNode &elmMachine);
1113
1114	void write(const com::Utf8Str &strFilename);
1115
1116	enum
1117	{
1118	BuildMachineXML_IncludeSnapshots = 0x01,
1119	BuildMachineXML_WriteVboxVersionAttribute = 0x02,
1120	BuildMachineXML_SkipRemovableMedia = 0x04,
1121	BuildMachineXML_MediaRegistry = 0x08,
1122	BuildMachineXML_SuppressSavedState = 0x10
1123	};
1124	void buildMachineXML(xml::ElementNode &elmMachine,
1125	uint32_t fl,
1126	std::list<xml::ElementNode> pllElementsWithUuidAttributes);
1127
1128	static bool isAudioDriverAllowedOnThisHost(AudioDriverType_T drv);
1129	static AudioDriverType_T getHostDefaultAudioDriver();
1130
1131	private:
1132	void readNetworkAdapters(const xml::ElementNode &elmHardware, NetworkAdaptersList &ll);
1133	void readAttachedNetworkMode(const xml::ElementNode &pelmMode, bool fEnabled, NetworkAdapter &nic);
1134	void readCpuIdTree(const xml::ElementNode &elmCpuid, CpuIdLeafsList &ll);
1135	void readCpuTree(const xml::ElementNode &elmCpu, CpuList &ll);
1136	void readSerialPorts(const xml::ElementNode &elmUART, SerialPortsList &ll);
1137	void readParallelPorts(const xml::ElementNode &elmLPT, ParallelPortsList &ll);
1138	void readAudioAdapter(const xml::ElementNode &elmAudioAdapter, AudioAdapter &aa);
1139	void readGuestProperties(const xml::ElementNode &elmGuestProperties, Hardware &hw);
1140	void readStorageControllerAttributes(const xml::ElementNode &elmStorageController, StorageController &sctl);
1141	void readHardware(const xml::ElementNode &elmHardware, Hardware &hw, Storage &strg);
1142	void readHardDiskAttachments_pre1_7(const xml::ElementNode &elmHardDiskAttachments, Storage &strg);
1143	void readStorageControllers(const xml::ElementNode &elmStorageControllers, Storage &strg);
1144	void readDVDAndFloppies_pre1_9(const xml::ElementNode &elmHardware, Storage &strg);
1145	void readTeleporter(const xml::ElementNode pElmTeleporter, MachineUserData pUserData);
1146	void readDebugging(const xml::ElementNode pElmDbg, Debugging pDbg);
1147	void readAutostart(const xml::ElementNode pElmAutostart, Autostart pAutostart);
1148	void readGroups(const xml::ElementNode elmGroups, StringsList pllGroups);
1149	void readSnapshot(const xml::ElementNode &elmSnapshot, Snapshot &snap);
1150	void convertOldOSType_pre1_5(com::Utf8Str &str);
1151	void readMachine(const xml::ElementNode &elmMachine);
1152
1153	void buildHardwareXML(xml::ElementNode &elmParent, const Hardware &hw, const Storage &strg);
1154	void buildNetworkXML(NetworkAttachmentType_T mode, xml::ElementNode &elmParent, bool fEnabled, const NetworkAdapter &nic);
1155	void buildStorageControllersXML(xml::ElementNode &elmParent,
1156	const Storage &st,
1157	bool fSkipRemovableMedia,
1158	std::list<xml::ElementNode> pllElementsWithUuidAttributes);
1159	void buildDebuggingXML(xml::ElementNode pElmParent, const Debugging pDbg);
1160	void buildAutostartXML(xml::ElementNode pElmParent, const Autostart pAutostart);
1161	void buildGroupsXML(xml::ElementNode pElmParent, const StringsList pllGroups);
1162	void buildSnapshotXML(xml::ElementNode &elmParent, const Snapshot &snap);
1163
1164	void bumpSettingsVersionIfNeeded();
1165	};
1166
1167	} // namespace settings
1168
1169
1170	#endif /* ___VBox_settings_h */

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

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

Download in other formats: