VirtualBox

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

Last change on this file since 75758 was 75396, checked in by vboxsync, 6 years ago

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

© 2024 Oracle Support Privacy / Do Not Sell My Info Terms of Use Trademark Policy Automated Access Etiquette