settings.h@ 34801

Last change on this file since 34801 was 34587, checked in by vboxsync, 14 years ago

Main: Bandwidth groups for disks (and later network)

This introduces two new interfaces. The first one named IBandwidthGroup
represents one I/O limit and can be assigned to several mediums which
share this limit (which works only for harddisk images with the disabled
host cache).
The second one IBandwdithControl manages the groups and can create new ones
and destroy them if not required anymore.

VBoxManage: commands to access the bandwidth groups

Syntax:
VBoxManage storageattach <uuid|vmname>

...
--bandwidthgroup <name>

--bandwidthgroup assigns the specified device to the given group.

VBoxManage bandwidthctl <uuid|vmname>

--name <name>
--add disk|network
--limit <megabytes per second>
--delete

The --name parameter gives the name of the bandwidth group.
--add creates a new group of the given type (only disk is implemented so far)

with the given name.

--limit sets the limit to the given amount of MB/s

Note that limit can be changed while the VM is running. The VM
will immediately pick up the new limit for the given group name.

--delete deletes the group with the given name if it isn't used anymore.

Trying to delete a still used group will result in an error.

Example:

VBoxManage bandwidthctl "Test VM" --name Limit --add disk --limit 20
Creates a group named Test having a 20 MB/s limit.

VBoxManage storageattach "Test VM" --storagectl "SATA Controller" --port 0 --device 0 --type hdd --medium test.vdi --bandwidthgroup Limit
Adds a new disk to the SATA controller and assigns the bandwidth group Limit to it.

VBoxManage storageattach "Test VM" --storagectl "SATA Controller" --port 0 --device 0 --type hdd --medium test.vdi --bandwidthgroup none
Removes the bandwidth limit from the disk.

VBoxManage bandwidthctl "Test VM" --name Limit --add disk --limit 10
Changes the limit of bandwidth group Limit to 10 MB/s. If the VM is running the limit will be picked up
immediately.

Property svn:eol-style set to native
Property svn:keywords set to Date Revision Author Id

File size: 33.8 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-2010 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
103	// ExtraDataItem (used by both VirtualBox.xml and machines XML)
104	struct USBDeviceFilter;
105	typedef std::list<USBDeviceFilter> USBDeviceFiltersList;
106
107	struct Medium;
108	typedef std::list<Medium> MediaList;
109
110	/**
111	* NOTE: If you add any fields in here, you must update a) the constructor and b)
112	* the operator== which is used by MachineConfigFile::operator==(), or otherwise
113	* your settings might never get saved.
114	*/
115	struct Medium
116	{
117	com::Guid uuid;
118	com::Utf8Str strLocation;
119	com::Utf8Str strDescription;
120
121	// the following are for hard disks only:
122	com::Utf8Str strFormat;
123	bool fAutoReset; // optional, only for diffs, default is false
124	StringsMap properties;
125	MediumType_T hdType;
126
127	MediaList llChildren; // only used with hard disks
128
129	bool operator==(const Medium &m) const;
130	};
131
132	/**
133	* A media registry. Starting with VirtualBox 3.3, this can appear in both the
134	* VirtualBox.xml file as well as machine XML files with settings version 1.11
135	* or higher, so these lists are now in ConfigFileBase.
136	*
137	* NOTE: If you add any fields in here, you must update a) the constructor and b)
138	* the operator== which is used by MachineConfigFile::operator==(), or otherwise
139	* your settings might never get saved.
140	*/
141	struct MediaRegistry
142	{
143	MediaList llHardDisks,
144	llDvdImages,
145	llFloppyImages;
146
147	bool operator==(const MediaRegistry &m) const;
148	};
149
150	/**
151	* Common base class for both MainConfigFile and MachineConfigFile
152	* which contains some common logic for both.
153	*/
154	class ConfigFileBase
155	{
156	public:
157	bool fileExists();
158
159	void copyBaseFrom(const ConfigFileBase &b);
160
161	protected:
162	ConfigFileBase(const com::Utf8Str *pstrFilename);
163	~ConfigFileBase();
164
165	void parseUUID(com::Guid &guid,
166	const com::Utf8Str &strUUID) const;
167	void parseTimestamp(RTTIMESPEC &timestamp,
168	const com::Utf8Str &str) const;
169
170	com::Utf8Str makeString(const RTTIMESPEC &tm);
171
172	void readExtraData(const xml::ElementNode &elmExtraData,
173	StringsMap &map);
174	void readUSBDeviceFilters(const xml::ElementNode &elmDeviceFilters,
175	USBDeviceFiltersList &ll);
176	typedef enum {Error, HardDisk, DVDImage, FloppyImage} MediaType;
177	void readMedium(MediaType t, const xml::ElementNode &elmMedium, MediaList &llMedia);
178	void readMediaRegistry(const xml::ElementNode &elmMediaRegistry, MediaRegistry &mr);
179
180	void setVersionAttribute(xml::ElementNode &elm);
181	void createStubDocument();
182
183	void buildExtraData(xml::ElementNode &elmParent, const StringsMap &me);
184	void buildUSBDeviceFilters(xml::ElementNode &elmParent,
185	const USBDeviceFiltersList &ll,
186	bool fHostMode);
187	void buildMedium(xml::ElementNode &elmMedium,
188	DeviceType_T devType,
189	const Medium &m,
190	uint32_t level);
191	void buildMediaRegistry(xml::ElementNode &elmParent,
192	const MediaRegistry &mr);
193	void clearDocument();
194
195	struct Data;
196	Data *m;
197
198	private:
199	// prohibit copying (Data contains pointers to XML which cannot be copied)
200	ConfigFileBase(const ConfigFileBase&);
201
202	friend class ConfigFileError;
203	};
204
205	////////////////////////////////////////////////////////////////////////////////
206	//
207	// VirtualBox.xml structures
208	//
209	////////////////////////////////////////////////////////////////////////////////
210
211	struct Host
212	{
213	USBDeviceFiltersList llUSBDeviceFilters;
214	};
215
216	struct SystemProperties
217	{
218	SystemProperties()
219	: ulLogHistoryCount(3)
220	{}
221
222	com::Utf8Str strDefaultMachineFolder;
223	com::Utf8Str strDefaultHardDiskFolder;
224	com::Utf8Str strDefaultHardDiskFormat;
225	com::Utf8Str strVRDEAuthLibrary;
226	com::Utf8Str strWebServiceAuthLibrary;
227	com::Utf8Str strDefaultVRDEExtPack;
228	uint32_t ulLogHistoryCount;
229	};
230
231	struct MachineRegistryEntry
232	{
233	com::Guid uuid;
234	com::Utf8Str strSettingsFile;
235	};
236	typedef std::list<MachineRegistryEntry> MachinesRegistry;
237
238	struct DHCPServer
239	{
240	com::Utf8Str strNetworkName,
241	strIPAddress,
242	strIPNetworkMask,
243	strIPLower,
244	strIPUpper;
245	bool fEnabled;
246	};
247	typedef std::list<DHCPServer> DHCPServersList;
248
249	class MainConfigFile : public ConfigFileBase
250	{
251	public:
252	MainConfigFile(const com::Utf8Str *pstrFilename);
253
254	void readMachineRegistry(const xml::ElementNode &elmMachineRegistry);
255	void readDHCPServers(const xml::ElementNode &elmDHCPServers);
256
257	void write(const com::Utf8Str strFilename);
258
259	Host host;
260	SystemProperties systemProperties;
261	MediaRegistry mediaRegistry;
262	MachinesRegistry llMachines;
263	DHCPServersList llDhcpServers;
264	StringsMap mapExtraDataItems;
265	};
266
267	////////////////////////////////////////////////////////////////////////////////
268	//
269	// Machine XML structures
270	//
271	////////////////////////////////////////////////////////////////////////////////
272
273	/**
274	* NOTE: If you add any fields in here, you must update a) the constructor and b)
275	* the operator== which is used by MachineConfigFile::operator==(), or otherwise
276	* your settings might never get saved.
277	*/
278	struct VRDESettings
279	{
280	VRDESettings()
281	: fEnabled(true),
282	authType(AuthType_Null),
283	ulAuthTimeout(5000),
284	fAllowMultiConnection(false),
285	fReuseSingleConnection(false),
286	fVideoChannel(false),
287	ulVideoChannelQuality(75)
288	{}
289
290	bool operator==(const VRDESettings& v) const;
291
292	bool fEnabled;
293	AuthType_T authType;
294	uint32_t ulAuthTimeout;
295	com::Utf8Str strAuthLibrary;
296	bool fAllowMultiConnection,
297	fReuseSingleConnection,
298	fVideoChannel;
299	uint32_t ulVideoChannelQuality;
300	com::Utf8Str strVrdeExtPack;
301	StringsMap mapProperties;
302	};
303
304	/**
305	* NOTE: If you add any fields in here, you must update a) the constructor and b)
306	* the operator== which is used by MachineConfigFile::operator==(), or otherwise
307	* your settings might never get saved.
308	*/
309	struct BIOSSettings
310	{
311	BIOSSettings()
312	: fACPIEnabled(true),
313	fIOAPICEnabled(false),
314	fLogoFadeIn(true),
315	fLogoFadeOut(true),
316	ulLogoDisplayTime(0),
317	biosBootMenuMode(BIOSBootMenuMode_MessageAndMenu),
318	fPXEDebugEnabled(false),
319	llTimeOffset(0)
320	{}
321
322	bool operator==(const BIOSSettings &d) const;
323
324	bool fACPIEnabled,
325	fIOAPICEnabled,
326	fLogoFadeIn,
327	fLogoFadeOut;
328	uint32_t ulLogoDisplayTime;
329	com::Utf8Str strLogoImagePath;
330	BIOSBootMenuMode_T biosBootMenuMode;
331	bool fPXEDebugEnabled;
332	int64_t llTimeOffset;
333	};
334
335	/**
336	* NOTE: If you add any fields in here, you must update a) the constructor and b)
337	* the operator== which is used by MachineConfigFile::operator==(), or otherwise
338	* your settings might never get saved.
339	*/
340	struct USBController
341	{
342	USBController()
343	: fEnabled(false),
344	fEnabledEHCI(false)
345	{}
346
347	bool operator==(const USBController &u) const;
348
349	bool fEnabled;
350	bool fEnabledEHCI;
351	USBDeviceFiltersList llDeviceFilters;
352	};
353
354	struct NATRule
355	{
356	NATRule(): proto(NATProtocol_TCP),
357	u16HostPort(0),
358	u16GuestPort(0){}
359	com::Utf8Str strName;
360	NATProtocol_T proto;
361	uint16_t u16HostPort;
362	com::Utf8Str strHostIP;
363	uint16_t u16GuestPort;
364	com::Utf8Str strGuestIP;
365	bool operator==(const NATRule &r) const
366	{
367	return strName == r.strName
368	&& proto == r.proto
369	&& u16HostPort == r.u16HostPort
370	&& strHostIP == r.strHostIP
371	&& u16GuestPort == r.u16GuestPort
372	&& strGuestIP == r.strGuestIP;
373	}
374	};
375	typedef std::list<NATRule> NATRuleList;
376
377	struct NAT
378	{
379	NAT() : u32Mtu(0),
380	u32SockRcv(0),
381	u32SockSnd(0),
382	u32TcpRcv(0),
383	u32TcpSnd(0),
384	fDnsPassDomain(true), /* historically this value is true */
385	fDnsProxy(false),
386	fDnsUseHostResolver(false),
387	fAliasLog(false),
388	fAliasProxyOnly(false),
389	fAliasUseSamePorts(false) {}
390	com::Utf8Str strNetwork;
391	com::Utf8Str strBindIP;
392	uint32_t u32Mtu;
393	uint32_t u32SockRcv;
394	uint32_t u32SockSnd;
395	uint32_t u32TcpRcv;
396	uint32_t u32TcpSnd;
397	com::Utf8Str strTftpPrefix;
398	com::Utf8Str strTftpBootFile;
399	com::Utf8Str strTftpNextServer;
400	bool fDnsPassDomain;
401	bool fDnsProxy;
402	bool fDnsUseHostResolver;
403	bool fAliasLog;
404	bool fAliasProxyOnly;
405	bool fAliasUseSamePorts;
406	NATRuleList llRules;
407	bool operator==(const NAT &n) const
408	{
409	return strNetwork == n.strNetwork
410	&& strBindIP == n.strBindIP
411	&& u32Mtu == n.u32Mtu
412	&& u32SockRcv == n.u32SockRcv
413	&& u32SockSnd == n.u32SockSnd
414	&& u32TcpSnd == n.u32TcpSnd
415	&& u32TcpRcv == n.u32TcpRcv
416	&& strTftpPrefix == n.strTftpPrefix
417	&& strTftpBootFile == n.strTftpBootFile
418	&& strTftpNextServer == n.strTftpNextServer
419	&& fDnsPassDomain == n.fDnsPassDomain
420	&& fDnsProxy == n.fDnsProxy
421	&& fDnsUseHostResolver == n.fDnsUseHostResolver
422	&& fAliasLog == n.fAliasLog
423	&& fAliasProxyOnly == n.fAliasProxyOnly
424	&& fAliasUseSamePorts == n.fAliasUseSamePorts
425	&& llRules == n.llRules;
426	}
427	};
428	/**
429	* NOTE: If you add any fields in here, you must update a) the constructor and b)
430	* the operator== which is used by MachineConfigFile::operator==(), or otherwise
431	* your settings might never get saved.
432	*/
433	struct NetworkAdapter
434	{
435	NetworkAdapter()
436	: ulSlot(0),
437	type(NetworkAdapterType_Am79C970A),
438	fEnabled(false),
439	fCableConnected(false),
440	ulLineSpeed(0),
441	fTraceEnabled(false),
442	mode(NetworkAttachmentType_Null),
443	ulBootPriority(0),
444	fHasDisabledNAT(false),
445	ulBandwidthLimit(0)
446	{}
447
448	bool operator==(const NetworkAdapter &n) const;
449
450	uint32_t ulSlot;
451
452	NetworkAdapterType_T type;
453	bool fEnabled;
454	com::Utf8Str strMACAddress;
455	bool fCableConnected;
456	uint32_t ulLineSpeed;
457	bool fTraceEnabled;
458	com::Utf8Str strTraceFile;
459
460	NetworkAttachmentType_T mode;
461	NAT nat;
462	com::Utf8Str strName; // NAT has own attribute
463	// with bridged: host interface or empty;
464	// otherwise: network name (required)
465	uint32_t ulBootPriority;
466	bool fHasDisabledNAT;
467	uint32_t ulBandwidthLimit;
468	};
469	typedef std::list<NetworkAdapter> NetworkAdaptersList;
470
471	/**
472	* NOTE: If you add any fields in here, you must update a) the constructor and b)
473	* the operator== which is used by MachineConfigFile::operator==(), or otherwise
474	* your settings might never get saved.
475	*/
476	struct SerialPort
477	{
478	SerialPort()
479	: ulSlot(0),
480	fEnabled(false),
481	ulIOBase(0x3f8),
482	ulIRQ(4),
483	portMode(PortMode_Disconnected),
484	fServer(false)
485	{}
486
487	bool operator==(const SerialPort &n) const;
488
489	uint32_t ulSlot;
490
491	bool fEnabled;
492	uint32_t ulIOBase;
493	uint32_t ulIRQ;
494	PortMode_T portMode;
495	com::Utf8Str strPath;
496	bool fServer;
497	};
498	typedef std::list<SerialPort> SerialPortsList;
499
500	/**
501	* NOTE: If you add any fields in here, you must update a) the constructor and b)
502	* the operator== which is used by MachineConfigFile::operator==(), or otherwise
503	* your settings might never get saved.
504	*/
505	struct ParallelPort
506	{
507	ParallelPort()
508	: ulSlot(0),
509	fEnabled(false),
510	ulIOBase(0x378),
511	ulIRQ(4)
512	{}
513
514	bool operator==(const ParallelPort &d) const;
515
516	uint32_t ulSlot;
517
518	bool fEnabled;
519	uint32_t ulIOBase;
520	uint32_t ulIRQ;
521	com::Utf8Str strPath;
522	};
523	typedef std::list<ParallelPort> ParallelPortsList;
524
525	/**
526	* NOTE: If you add any fields in here, you must update a) the constructor and b)
527	* the operator== which is used by MachineConfigFile::operator==(), or otherwise
528	* your settings might never get saved.
529	*/
530	struct AudioAdapter
531	{
532	AudioAdapter()
533	: fEnabled(true),
534	controllerType(AudioControllerType_AC97),
535	driverType(AudioDriverType_Null)
536	{}
537
538	bool operator==(const AudioAdapter &a) const
539	{
540	return (this == &a)
541	\|\| ( (fEnabled == a.fEnabled)
542	&& (controllerType == a.controllerType)
543	&& (driverType == a.driverType)
544	);
545	}
546
547	bool fEnabled;
548	AudioControllerType_T controllerType;
549	AudioDriverType_T driverType;
550	};
551
552	/**
553	* NOTE: If you add any fields in here, you must update a) the constructor and b)
554	* the operator== which is used by MachineConfigFile::operator==(), or otherwise
555	* your settings might never get saved.
556	*/
557	struct SharedFolder
558	{
559	SharedFolder()
560	: fWritable(false)
561	, fAutoMount(false)
562	{}
563
564	bool operator==(const SharedFolder &a) const;
565
566	com::Utf8Str strName,
567	strHostPath;
568	bool fWritable;
569	bool fAutoMount;
570	};
571	typedef std::list<SharedFolder> SharedFoldersList;
572
573	/**
574	* NOTE: If you add any fields in here, you must update a) the constructor and b)
575	* the operator== which is used by MachineConfigFile::operator==(), or otherwise
576	* your settings might never get saved.
577	*/
578	struct GuestProperty
579	{
580	GuestProperty()
581	: timestamp(0)
582	{};
583
584	bool operator==(const GuestProperty &g) const;
585
586	com::Utf8Str strName,
587	strValue;
588	uint64_t timestamp;
589	com::Utf8Str strFlags;
590	};
591	typedef std::list<GuestProperty> GuestPropertiesList;
592
593	typedef std::map<uint32_t, DeviceType_T> BootOrderMap;
594
595	/**
596	* NOTE: If you add any fields in here, you must update a) the constructor and b)
597	* the operator== which is used by MachineConfigFile::operator==(), or otherwise
598	* your settings might never get saved.
599	*/
600	struct CpuIdLeaf
601	{
602	CpuIdLeaf()
603	: ulId(UINT32_MAX),
604	ulEax(0),
605	ulEbx(0),
606	ulEcx(0),
607	ulEdx(0)
608	{}
609
610	bool operator==(const CpuIdLeaf &c) const
611	{
612	return ( (this == &c)
613	\|\| ( (ulId == c.ulId)
614	&& (ulEax == c.ulEax)
615	&& (ulEbx == c.ulEbx)
616	&& (ulEcx == c.ulEcx)
617	&& (ulEdx == c.ulEdx)
618	)
619	);
620	}
621
622	uint32_t ulId;
623	uint32_t ulEax;
624	uint32_t ulEbx;
625	uint32_t ulEcx;
626	uint32_t ulEdx;
627	};
628	typedef std::list<CpuIdLeaf> CpuIdLeafsList;
629
630	/**
631	* NOTE: If you add any fields in here, you must update a) the constructor and b)
632	* the operator== which is used by MachineConfigFile::operator==(), or otherwise
633	* your settings might never get saved.
634	*/
635	struct Cpu
636	{
637	Cpu()
638	: ulId(UINT32_MAX)
639	{}
640
641	bool operator==(const Cpu &c) const
642	{
643	return (ulId == c.ulId);
644	}
645
646	uint32_t ulId;
647	};
648	typedef std::list<Cpu> CpuList;
649
650	/**
651	* NOTE: If you add any fields in here, you must update a) the constructor and b)
652	* the operator== which is used by MachineConfigFile::operator==(), or otherwise
653	* your settings might never get saved.
654	*/
655	struct BandwidthGroup
656	{
657	BandwidthGroup()
658	: cMaxMbPerSec(0),
659	enmType(BandwidthGroupType_Null)
660	{}
661
662	bool operator==(const BandwidthGroup &i) const
663	{
664	return ( (strName == i.strName)
665	&& (cMaxMbPerSec == i.cMaxMbPerSec)
666	&& (enmType == i.enmType));
667	}
668
669	com::Utf8Str strName;
670	uint32_t cMaxMbPerSec;
671	BandwidthGroupType_T enmType;
672	};
673	typedef std::list<BandwidthGroup> BandwidthGroupList;
674
675	/**
676	* NOTE: If you add any fields in here, you must update a) the constructor and b)
677	* the operator== which is used by MachineConfigFile::operator==(), or otherwise
678	* your settings might never get saved.
679	*/
680	struct IoSettings
681	{
682	IoSettings();
683
684	bool operator==(const IoSettings &i) const
685	{
686	return ( (fIoCacheEnabled == i.fIoCacheEnabled)
687	&& (ulIoCacheSize == i.ulIoCacheSize)
688	&& (llBandwidthGroups == i.llBandwidthGroups));
689	}
690
691	bool fIoCacheEnabled;
692	uint32_t ulIoCacheSize;
693	BandwidthGroupList llBandwidthGroups;
694	};
695
696	/**
697	* Representation of Machine hardware; this is used in the MachineConfigFile.hardwareMachine
698	* field.
699	*
700	* NOTE: If you add any fields in here, you must update a) the constructor and b)
701	* the operator== which is used by MachineConfigFile::operator==(), or otherwise
702	* your settings might never get saved.
703	*/
704	struct Hardware
705	{
706	Hardware();
707
708	bool operator==(const Hardware&) const;
709
710	com::Utf8Str strVersion; // hardware version, optional
711	com::Guid uuid; // hardware uuid, optional (null).
712
713	bool fHardwareVirt,
714	fHardwareVirtExclusive,
715	fNestedPaging,
716	fLargePages,
717	fVPID,
718	fHardwareVirtForce,
719	fSyntheticCpu,
720	fPAE;
721	uint32_t cCPUs;
722	bool fCpuHotPlug; // requires settings version 1.10 (VirtualBox 3.2)
723	CpuList llCpus; // requires settings version 1.10 (VirtualBox 3.2)
724	bool fHpetEnabled; // requires settings version 1.10 (VirtualBox 3.2)
725	uint32_t ulCpuExecutionCap; // requires settings version 1.11 (VirtualBox 3.3)
726
727	CpuIdLeafsList llCpuIdLeafs;
728
729	uint32_t ulMemorySizeMB;
730
731	BootOrderMap mapBootOrder; // item 0 has highest priority
732
733	uint32_t ulVRAMSizeMB;
734	uint32_t cMonitors;
735	bool fAccelerate3D,
736	fAccelerate2DVideo; // requires settings version 1.8 (VirtualBox 3.1)
737	FirmwareType_T firmwareType; // requires settings version 1.9 (VirtualBox 3.1)
738
739	PointingHidType_T pointingHidType; // requires settings version 1.10 (VirtualBox 3.2)
740	KeyboardHidType_T keyboardHidType; // requires settings version 1.10 (VirtualBox 3.2)
741
742	ChipsetType_T chipsetType; // requires settings version 1.11 (VirtualBox 4.0)
743
744	VRDESettings vrdeSettings;
745
746	BIOSSettings biosSettings;
747	USBController usbController;
748	NetworkAdaptersList llNetworkAdapters;
749	SerialPortsList llSerialPorts;
750	ParallelPortsList llParallelPorts;
751	AudioAdapter audioAdapter;
752
753	// technically these two have no business in the hardware section, but for some
754	// clever reason <Hardware> is where they are in the XML....
755	SharedFoldersList llSharedFolders;
756	ClipboardMode_T clipboardMode;
757
758	uint32_t ulMemoryBalloonSize;
759	bool fPageFusionEnabled;
760
761	GuestPropertiesList llGuestProperties;
762	com::Utf8Str strNotificationPatterns;
763
764	IoSettings ioSettings; // requires settings version 1.10 (VirtualBox 3.2)
765	};
766
767	/**
768	* A device attached to a storage controller. This can either be a
769	* hard disk or a DVD drive or a floppy drive and also specifies
770	* which medium is "in" the drive; as a result, this is a combination
771	* of the Main IMedium and IMediumAttachment interfaces.
772	*
773	* NOTE: If you add any fields in here, you must update a) the constructor and b)
774	* the operator== which is used by MachineConfigFile::operator==(), or otherwise
775	* your settings might never get saved.
776	*/
777	struct AttachedDevice
778	{
779	AttachedDevice()
780	: deviceType(DeviceType_Null),
781	fPassThrough(false),
782	lPort(0),
783	lDevice(0)
784	{}
785
786	bool operator==(const AttachedDevice &a) const;
787
788	DeviceType_T deviceType; // only HardDisk, DVD or Floppy are allowed
789
790	// DVDs can be in pass-through mode:
791	bool fPassThrough;
792
793	int32_t lPort;
794	int32_t lDevice;
795
796	// if an image file is attached to the device (ISO, RAW, or hard disk image such as VDI),
797	// this is its UUID; it depends on deviceType which media registry this then needs to
798	// be looked up in. If no image file (only permitted for DVDs and floppies), then the UUID is NULL
799	com::Guid uuid;
800
801	// for DVDs and floppies, the attachment can also be a host device:
802	com::Utf8Str strHostDriveSrc; // if != NULL, value of <HostDrive>/@src
803
804	// Bandwidth group the device is attached to.
805	com::Utf8Str strBwGroup;
806	};
807	typedef std::list<AttachedDevice> AttachedDevicesList;
808
809	/**
810	* NOTE: If you add any fields in here, you must update a) the constructor and b)
811	* the operator== which is used by MachineConfigFile::operator==(), or otherwise
812	* your settings might never get saved.
813	*/
814	struct StorageController
815	{
816	StorageController()
817	: storageBus(StorageBus_IDE),
818	controllerType(StorageControllerType_PIIX3),
819	ulPortCount(2),
820	ulInstance(0),
821	fUseHostIOCache(true),
822	fBootable(true),
823	lIDE0MasterEmulationPort(0),
824	lIDE0SlaveEmulationPort(0),
825	lIDE1MasterEmulationPort(0),
826	lIDE1SlaveEmulationPort(0)
827	{}
828
829	bool operator==(const StorageController &s) const;
830
831	com::Utf8Str strName;
832	StorageBus_T storageBus; // _SATA, _SCSI, _IDE, _SAS
833	StorageControllerType_T controllerType;
834	uint32_t ulPortCount;
835	uint32_t ulInstance;
836	bool fUseHostIOCache;
837	bool fBootable;
838
839	// only for when controllerType == StorageControllerType_IntelAhci:
840	int32_t lIDE0MasterEmulationPort,
841	lIDE0SlaveEmulationPort,
842	lIDE1MasterEmulationPort,
843	lIDE1SlaveEmulationPort;
844
845	AttachedDevicesList llAttachedDevices;
846	};
847	typedef std::list<StorageController> StorageControllersList;
848
849	/**
850	* We wrap the storage controllers list into an extra struct so we can
851	* use an undefined struct without needing std::list<> in all the headers.
852	*
853	* NOTE: If you add any fields in here, you must update a) the constructor and b)
854	* the operator== which is used by MachineConfigFile::operator==(), or otherwise
855	* your settings might never get saved.
856	*/
857	struct Storage
858	{
859	bool operator==(const Storage &s) const;
860
861	StorageControllersList llStorageControllers;
862	};
863
864	struct Snapshot;
865	typedef std::list<Snapshot> SnapshotsList;
866
867	/**
868	* NOTE: If you add any fields in here, you must update a) the constructor and b)
869	* the operator== which is used by MachineConfigFile::operator==(), or otherwise
870	* your settings might never get saved.
871	*/
872	struct Snapshot
873	{
874	bool operator==(const Snapshot &s) const;
875
876	com::Guid uuid;
877	com::Utf8Str strName,
878	strDescription; // optional
879	RTTIMESPEC timestamp;
880
881	com::Utf8Str strStateFile; // for online snapshots only
882
883	Hardware hardware;
884	Storage storage;
885
886	SnapshotsList llChildSnapshots;
887	};
888
889	struct MachineUserData
890	{
891	MachineUserData()
892	: fNameSync(true),
893	fTeleporterEnabled(false),
894	uTeleporterPort(0),
895	enmFaultToleranceState(FaultToleranceState_Inactive),
896	uFaultTolerancePort(0),
897	uFaultToleranceInterval(0),
898	fRTCUseUTC(false)
899	{ }
900
901	bool operator==(const MachineUserData &c) const
902	{
903	return (strName == c.strName)
904	&& (fNameSync == c.fNameSync)
905	&& (strDescription == c.strDescription)
906	&& (strOsType == c.strOsType)
907	&& (strSnapshotFolder == c.strSnapshotFolder)
908	&& (fTeleporterEnabled == c.fTeleporterEnabled)
909	&& (uTeleporterPort == c.uTeleporterPort)
910	&& (strTeleporterAddress == c.strTeleporterAddress)
911	&& (strTeleporterPassword == c.strTeleporterPassword)
912	&& (enmFaultToleranceState == c.enmFaultToleranceState)
913	&& (uFaultTolerancePort == c.uFaultTolerancePort)
914	&& (uFaultToleranceInterval == c.uFaultToleranceInterval)
915	&& (strFaultToleranceAddress == c.strFaultToleranceAddress)
916	&& (strFaultTolerancePassword == c.strFaultTolerancePassword)
917	&& (fRTCUseUTC == c.fRTCUseUTC);
918	}
919
920	com::Utf8Str strName;
921	bool fNameSync;
922	com::Utf8Str strDescription;
923	com::Utf8Str strOsType;
924	com::Utf8Str strSnapshotFolder;
925	bool fTeleporterEnabled;
926	uint32_t uTeleporterPort;
927	com::Utf8Str strTeleporterAddress;
928	com::Utf8Str strTeleporterPassword;
929	FaultToleranceState_T enmFaultToleranceState;
930	uint32_t uFaultTolerancePort;
931	com::Utf8Str strFaultToleranceAddress;
932	com::Utf8Str strFaultTolerancePassword;
933	uint32_t uFaultToleranceInterval;
934	bool fRTCUseUTC;
935	};
936
937	/**
938	* MachineConfigFile represents an XML machine configuration. All the machine settings
939	* that go out to the XML (or are read from it) are in here.
940	*
941	* NOTE: If you add any fields in here, you must update a) the constructor and b)
942	* the operator== which is used by Machine::saveSettings(), or otherwise your settings
943	* might never get saved.
944	*/
945	class MachineConfigFile : public ConfigFileBase
946	{
947	public:
948	com::Guid uuid;
949
950	MachineUserData machineUserData;
951
952	com::Utf8Str strStateFile;
953	bool fCurrentStateModified; // optional, default is true
954	RTTIMESPEC timeLastStateChange; // optional, defaults to now
955	bool fAborted; // optional, default is false
956
957	com::Guid uuidCurrentSnapshot;
958
959	Hardware hardwareMachine;
960	Storage storageMachine;
961	MediaRegistry mediaRegistry;
962
963	StringsMap mapExtraDataItems;
964
965	SnapshotsList llFirstSnapshot; // first snapshot or empty list if there's none
966
967	MachineConfigFile(const com::Utf8Str *pstrFilename);
968
969	bool operator==(const MachineConfigFile &m) const;
970
971	bool canHaveOwnMediaRegistry() const;
972
973	void importMachineXML(const xml::ElementNode &elmMachine);
974
975	void write(const com::Utf8Str &strFilename);
976
977	enum
978	{
979	BuildMachineXML_IncludeSnapshots = 0x01,
980	BuildMachineXML_WriteVboxVersionAttribute = 0x02,
981	BuildMachineXML_SkipRemovableMedia = 0x04,
982	BuildMachineXML_MediaRegistry = 0x08,
983	BuildMachineXML_SuppressSavedState = 0x10
984	};
985	void buildMachineXML(xml::ElementNode &elmMachine,
986	uint32_t fl,
987	std::list<xml::ElementNode> pllElementsWithUuidAttributes);
988
989	static bool isAudioDriverAllowedOnThisHost(AudioDriverType_T drv);
990	static AudioDriverType_T getHostDefaultAudioDriver();
991
992	private:
993	void readNetworkAdapters(const xml::ElementNode &elmHardware, NetworkAdaptersList &ll);
994	void readAttachedNetworkMode(const xml::ElementNode &pelmMode, bool fEnabled, NetworkAdapter &nic);
995	void readCpuIdTree(const xml::ElementNode &elmCpuid, CpuIdLeafsList &ll);
996	void readCpuTree(const xml::ElementNode &elmCpu, CpuList &ll);
997	void readSerialPorts(const xml::ElementNode &elmUART, SerialPortsList &ll);
998	void readParallelPorts(const xml::ElementNode &elmLPT, ParallelPortsList &ll);
999	void readAudioAdapter(const xml::ElementNode &elmAudioAdapter, AudioAdapter &aa);
1000	void readGuestProperties(const xml::ElementNode &elmGuestProperties, Hardware &hw);
1001	void readStorageControllerAttributes(const xml::ElementNode &elmStorageController, StorageController &sctl);
1002	void readHardware(const xml::ElementNode &elmHardware, Hardware &hw, Storage &strg);
1003	void readHardDiskAttachments_pre1_7(const xml::ElementNode &elmHardDiskAttachments, Storage &strg);
1004	void readStorageControllers(const xml::ElementNode &elmStorageControllers, Storage &strg);
1005	void readDVDAndFloppies_pre1_9(const xml::ElementNode &elmHardware, Storage &strg);
1006	void readSnapshot(const xml::ElementNode &elmSnapshot, Snapshot &snap);
1007	void convertOldOSType_pre1_5(com::Utf8Str &str);
1008	void readMachine(const xml::ElementNode &elmMachine);
1009
1010	void buildHardwareXML(xml::ElementNode &elmParent, const Hardware &hw, const Storage &strg);
1011	void buildNetworkXML(NetworkAttachmentType_T mode, xml::ElementNode &elmParent, const NetworkAdapter &nic);
1012	void buildStorageControllersXML(xml::ElementNode &elmParent,
1013	const Storage &st,
1014	bool fSkipRemovableMedia,
1015	std::list<xml::ElementNode> pllElementsWithUuidAttributes);
1016	void buildSnapshotXML(xml::ElementNode &elmParent, const Snapshot &snap);
1017
1018	void bumpSettingsVersionIfNeeded();
1019	};
1020
1021	} // namespace settings
1022
1023
1024	#endif /* ___VBox_settings_h */

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

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

Download in other formats: