VirtualBox

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

最後變更 在這個檔案是 108046,由 vboxsync 提交於 6 週 前

doc/manual,include/VBox,Frontends/{VBoxManage,VirtualBox/src},Main/{include,SharedFolder,Console,Machine,VirtualBox,VirtualBox.xidl}: Added global shared folders and adjusted fetching and handling of folders between shared folder types bugref:3544
  • 屬性 svn:eol-style 設為 native
  • 屬性 svn:keywords 設為 Date Revision Author Id
檔案大小: 56.3 KB
行 
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-2024 Oracle and/or its affiliates.
21 *
22 * This file is part of VirtualBox base platform packages, as
23 * available from https://www.alldomusa.eu.org.
24 *
25 * This program is free software; you can redistribute it and/or
26 * modify it under the terms of the GNU General Public License
27 * as published by the Free Software Foundation, in version 3 of the
28 * License.
29 *
30 * This program is distributed in the hope that it will be useful, but
31 * WITHOUT ANY WARRANTY; without even the implied warranty of
32 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
33 * General Public License for more details.
34 *
35 * You should have received a copy of the GNU General Public License
36 * along with this program; if not, see <https://www.gnu.org/licenses>.
37 *
38 * The contents of this file may alternatively be used under the terms
39 * of the Common Development and Distribution License Version 1.0
40 * (CDDL), a copy of it is provided in the "COPYING.CDDL" file included
41 * in the VirtualBox distribution, in which case the provisions of the
42 * CDDL are applicable instead of those of the GPL.
43 *
44 * You may elect to license modified versions of this file under the
45 * terms and conditions of either the GPL or the CDDL or both.
46 *
47 * SPDX-License-Identifier: GPL-3.0-only OR CDDL-1.0
48 */
49
50#ifndef VBOX_INCLUDED_settings_h
51#define VBOX_INCLUDED_settings_h
52#ifndef RT_WITHOUT_PRAGMA_ONCE
53# pragma once
54#endif
55
56#include <iprt/time.h>
57
58#include "VBox/com/VirtualBox.h"
59
60#include <VBox/com/Guid.h>
61#include <VBox/com/string.h>
62#include <VBox/VBoxCryptoIf.h>
63
64#include <list>
65#include <map>
66#include <vector>
67
68/**
69 * Maximum depth of a medium tree, to prevent stack overflows.
70 * XPCOM has a relatively low stack size for its workers, and we have
71 * to avoid crashes due to exceeding the limit both on reading and
72 * writing config files. The bottleneck is in libxml2.
73 * Data point: a release and asan build could both handle 3800 on Debian 10.
74 */
75#define SETTINGS_MEDIUM_DEPTH_MAX 300
76
77/**
78 * Maximum depth of the snapshot tree, to prevent stack overflows.
79 * XPCOM has a relatively low stack size for its workers, and we have
80 * to avoid crashes due to exceeding the limit both on reading and
81 * writing config files. The bottleneck is reading config files with
82 * deep snapshot nesting, as libxml2 needs quite some stack space.
83 * Data point: a release and asan build could both handle 1300 on Debian 10.
84 */
85#define SETTINGS_SNAPSHOT_DEPTH_MAX 250
86
87namespace xml
88{
89 class ElementNode;
90}
91
92namespace settings
93{
94
95class ConfigFileError;
96
97////////////////////////////////////////////////////////////////////////////////
98//
99// Structures shared between Machine XML and VirtualBox.xml
100//
101////////////////////////////////////////////////////////////////////////////////
102
103typedef std::map<com::Utf8Str, com::Utf8Str> StringsMap;
104typedef std::list<com::Utf8Str> StringsList;
105
106/**
107 * USB device filter definition. This struct is used both in MainConfigFile
108 * (for global USB filters) and MachineConfigFile (for machine filters).
109 *
110 * NOTE: If you add any fields in here, you must update a) the constructor and b)
111 * the operator== which is used by MachineConfigFile::operator==(), or otherwise
112 * your settings might never get saved.
113 */
114struct USBDeviceFilter
115{
116 USBDeviceFilter();
117
118 bool operator==(const USBDeviceFilter&u) const;
119
120 com::Utf8Str strName;
121 bool fActive;
122 com::Utf8Str strVendorId,
123 strProductId,
124 strRevision,
125 strManufacturer,
126 strProduct,
127 strSerialNumber,
128 strPort;
129 USBDeviceFilterAction_T action; // only used with host USB filters
130 com::Utf8Str strRemote; // irrelevant for host USB objects
131 uint32_t ulMaskedInterfaces; // irrelevant for host USB objects
132};
133
134typedef std::list<USBDeviceFilter> USBDeviceFiltersList;
135
136struct Medium;
137typedef std::list<Medium> MediaList;
138
139/**
140 * NOTE: If you add any fields in here, you must update a) the constructor and b)
141 * the operator== which is used by MachineConfigFile::operator==(), or otherwise
142 * your settings might never get saved.
143 */
144struct Medium
145{
146 Medium();
147
148 bool operator==(const Medium &m) const;
149
150 com::Guid uuid;
151 com::Utf8Str strLocation;
152 com::Utf8Str strDescription;
153
154 // the following are for hard disks only:
155 com::Utf8Str strFormat;
156 bool fAutoReset; // optional, only for diffs, default is false
157 StringsMap properties;
158 MediumType_T hdType;
159
160 MediaList llChildren; // only used with hard disks
161
162 static const struct Medium Empty;
163};
164
165/**
166 * A media registry. Starting with VirtualBox 3.3, this can appear in both the
167 * VirtualBox.xml file as well as machine XML files with settings version 1.11
168 * or higher, so these lists are now in ConfigFileBase.
169 *
170 * NOTE: If you add any fields in here, you must update a) the constructor and b)
171 * the operator== which is used by MachineConfigFile::operator==(), or otherwise
172 * your settings might never get saved.
173 */
174struct MediaRegistry
175{
176 bool operator==(const MediaRegistry &m) const;
177
178 MediaList llHardDisks,
179 llDvdImages,
180 llFloppyImages;
181};
182
183/**
184 * NOTE: If you add any fields in here, you must update a) the constructor and b)
185 * the operator== which is used by MachineConfigFile::operator==(), or otherwise
186 * your settings might never get saved.
187 */
188struct NATRule
189{
190 NATRule();
191
192 bool operator==(const NATRule &r) const;
193
194 com::Utf8Str strName;
195 NATProtocol_T proto;
196 uint16_t u16HostPort;
197 com::Utf8Str strHostIP;
198 uint16_t u16GuestPort;
199 com::Utf8Str strGuestIP;
200};
201typedef std::map<com::Utf8Str, NATRule> NATRulesMap;
202
203struct NATHostLoopbackOffset
204{
205 NATHostLoopbackOffset();
206
207 bool operator==(const NATHostLoopbackOffset &o) const;
208
209 bool operator==(const com::Utf8Str& strAddr)
210 {
211 return strLoopbackHostAddress == strAddr;
212 }
213
214 bool operator==(uint32_t off)
215 {
216 return u32Offset == off;
217 }
218
219 /** Note: 128/8 is only acceptable */
220 com::Utf8Str strLoopbackHostAddress;
221 uint32_t u32Offset;
222};
223
224typedef std::list<NATHostLoopbackOffset> NATLoopbackOffsetList;
225
226/**
227 * NOTE: If you add any fields in here, you must update a) the constructor and b)
228 * the operator== which is used by MachineConfigFile::operator==(), or otherwise
229 * your settings might never get saved.
230 */
231struct SharedFolder
232{
233 SharedFolder();
234
235 bool operator==(const SharedFolder &a) const;
236
237 com::Utf8Str strName,
238 strHostPath;
239 bool fWritable;
240 bool fAutoMount;
241 com::Utf8Str strAutoMountPoint;
242 SymlinkPolicy_T enmSymlinkPolicy;
243};
244
245typedef std::list<SharedFolder> SharedFoldersList;
246
247typedef std::vector<uint8_t> IconBlob;
248
249/**
250 * Common base class for both MainConfigFile and MachineConfigFile
251 * which contains some common logic for both.
252 */
253class ConfigFileBase
254{
255public:
256 bool fileExists();
257 SettingsVersion_T getSettingsVersion();
258
259 void copyBaseFrom(const ConfigFileBase &b);
260
261protected:
262 ConfigFileBase(const com::Utf8Str *pstrFilename);
263 /* Note: this copy constructor doesn't create a full copy of other, cause
264 * the file based stuff (xml doc) could not be copied. */
265 ConfigFileBase(const ConfigFileBase &other);
266
267 ~ConfigFileBase();
268
269 typedef enum {Error, HardDisk, DVDImage, FloppyImage} MediaType;
270
271 static const char *stringifyMediaType(MediaType t);
272 SettingsVersion_T parseVersion(const com::Utf8Str &strVersion,
273 const xml::ElementNode *pElm);
274 void parseUUID(com::Guid &guid,
275 const com::Utf8Str &strUUID,
276 const xml::ElementNode *pElm) const;
277 void parseTimestamp(RTTIMESPEC &timestamp,
278 const com::Utf8Str &str,
279 const xml::ElementNode *pElm) const;
280 void parseBase64(IconBlob &binary,
281 const com::Utf8Str &str,
282 const xml::ElementNode *pElm) const;
283 com::Utf8Str stringifyTimestamp(const RTTIMESPEC &tm) const;
284 void toBase64(com::Utf8Str &str,
285 const IconBlob &binary) const;
286
287 void readExtraData(const xml::ElementNode &elmExtraData,
288 StringsMap &map);
289 void readUSBDeviceFilters(const xml::ElementNode &elmDeviceFilters,
290 USBDeviceFiltersList &ll);
291 void readMediumOne(MediaType t, const xml::ElementNode &elmMedium, Medium &med);
292 void readMedium(MediaType t, const xml::ElementNode &elmMedium, Medium &med);
293 void readMediaRegistry(const xml::ElementNode &elmMediaRegistry, MediaRegistry &mr);
294 void readNATForwardRulesMap(const xml::ElementNode &elmParent, NATRulesMap &mapRules);
295 void readNATLoopbacks(const xml::ElementNode &elmParent, NATLoopbackOffsetList &llLoopBacks);
296
297 void setVersionAttribute(xml::ElementNode &elm);
298 void specialBackupIfFirstBump();
299 void createStubDocument();
300
301 void buildExtraData(xml::ElementNode &elmParent, const StringsMap &me);
302 void buildUSBDeviceFilters(xml::ElementNode &elmParent,
303 const USBDeviceFiltersList &ll,
304 bool fHostMode);
305 void buildMedium(MediaType t,
306 xml::ElementNode &elmMedium,
307 const Medium &med);
308 void buildMediaRegistry(xml::ElementNode &elmParent,
309 const MediaRegistry &mr);
310 void buildNATForwardRulesMap(xml::ElementNode &elmParent, const NATRulesMap &mapRules);
311 void buildNATLoopbacks(xml::ElementNode &elmParent, const NATLoopbackOffsetList &natLoopbackList);
312 void clearDocument();
313
314 struct Data;
315 Data *m;
316
317 friend class ConfigFileError;
318};
319
320////////////////////////////////////////////////////////////////////////////////
321//
322// VirtualBox.xml structures
323//
324////////////////////////////////////////////////////////////////////////////////
325
326struct USBDeviceSource
327{
328 com::Utf8Str strName;
329 com::Utf8Str strBackend;
330 com::Utf8Str strAddress;
331 StringsMap properties;
332};
333
334typedef std::list<USBDeviceSource> USBDeviceSourcesList;
335
336#ifdef VBOX_WITH_UPDATE_AGENT
337struct UpdateAgent
338{
339 UpdateAgent();
340
341 bool fEnabled;
342 UpdateChannel_T enmChannel;
343 uint32_t uCheckFreqSeconds;
344 com::Utf8Str strRepoUrl;
345 com::Utf8Str strLastCheckDate;
346 uint32_t uCheckCount;
347};
348#endif /* VBOX_WITH_UPDATE_AGENT */
349
350struct Host
351{
352 USBDeviceFiltersList llUSBDeviceFilters;
353 USBDeviceSourcesList llUSBDeviceSources;
354#ifdef VBOX_WITH_UPDATE_AGENT
355 UpdateAgent updateHost;
356 /** @todo Add handling for ExtPack and Guest Additions updates here later. See @bugref{7983}. */
357#endif /* VBOX_WITH_UPDATE_AGENT */
358};
359
360struct SystemProperties
361{
362 SystemProperties();
363
364 com::Utf8Str strDefaultMachineFolder;
365 com::Utf8Str strDefaultHardDiskFolder;
366 com::Utf8Str strDefaultHardDiskFormat;
367 com::Utf8Str strVRDEAuthLibrary;
368 com::Utf8Str strWebServiceAuthLibrary;
369 com::Utf8Str strDefaultVRDEExtPack;
370 com::Utf8Str strDefaultCryptoExtPack;
371 com::Utf8Str strAutostartDatabasePath;
372 com::Utf8Str strDefaultAdditionsISO;
373 com::Utf8Str strDefaultFrontend;
374 com::Utf8Str strLoggingLevel;
375 com::Utf8Str strProxyUrl;
376 uint32_t uProxyMode; /**< ProxyMode_T */
377 uint32_t uLogHistoryCount;
378 com::Utf8Str strLanguageId;
379};
380
381struct PlatformProperties
382{
383 PlatformProperties();
384
385 bool fExclusiveHwVirt;
386};
387
388struct MachineRegistryEntry
389{
390 com::Guid uuid;
391 com::Utf8Str strSettingsFile;
392};
393
394typedef std::list<MachineRegistryEntry> MachinesRegistry;
395
396struct DhcpOptValue
397{
398 DhcpOptValue();
399 DhcpOptValue(const com::Utf8Str &aText, DHCPOptionEncoding_T aEncoding = DHCPOptionEncoding_Normal);
400
401 com::Utf8Str strValue;
402 DHCPOptionEncoding_T enmEncoding;
403};
404
405typedef std::map<DHCPOption_T, DhcpOptValue> DhcpOptionMap;
406typedef DhcpOptionMap::value_type DhcpOptValuePair;
407typedef DhcpOptionMap::iterator DhcpOptIterator;
408typedef DhcpOptionMap::const_iterator DhcpOptConstIterator;
409
410struct DHCPGroupCondition
411{
412 DHCPGroupCondition();
413
414 bool fInclusive;
415 DHCPGroupConditionType_T enmType;
416 com::Utf8Str strValue;
417};
418typedef std::vector<DHCPGroupCondition> DHCPGroupConditionVec;
419
420
421struct DHCPConfig
422{
423 DHCPConfig();
424
425 DhcpOptionMap mapOptions;
426 uint32_t secMinLeaseTime;
427 uint32_t secDefaultLeaseTime;
428 uint32_t secMaxLeaseTime;
429 com::Utf8Str strForcedOptions;
430 com::Utf8Str strSuppressedOptions;
431};
432
433struct DHCPGroupConfig : DHCPConfig
434{
435 DHCPGroupConfig();
436
437 com::Utf8Str strName;
438 DHCPGroupConditionVec vecConditions;
439};
440typedef std::vector<DHCPGroupConfig> DHCPGroupConfigVec;
441
442struct DHCPIndividualConfig : DHCPConfig
443{
444 DHCPIndividualConfig();
445
446 com::Utf8Str strMACAddress;
447 com::Utf8Str strVMName;
448 uint32_t uSlot;
449 com::Utf8Str strFixedAddress;
450};
451typedef std::map<com::Utf8Str, DHCPIndividualConfig> DHCPIndividualConfigMap;
452
453struct DHCPServer
454{
455 DHCPServer();
456
457 com::Utf8Str strNetworkName;
458 com::Utf8Str strIPAddress;
459 com::Utf8Str strIPLower;
460 com::Utf8Str strIPUpper;
461 bool fEnabled;
462 DHCPConfig globalConfig;
463 DHCPGroupConfigVec vecGroupConfigs;
464 DHCPIndividualConfigMap mapIndividualConfigs;
465};
466typedef std::list<DHCPServer> DHCPServersList;
467
468
469/**
470 * NAT Networking settings (NAT service).
471 */
472struct NATNetwork
473{
474 NATNetwork();
475
476 com::Utf8Str strNetworkName;
477 com::Utf8Str strIPv4NetworkCidr;
478 com::Utf8Str strIPv6Prefix;
479 bool fEnabled;
480 bool fIPv6Enabled;
481 bool fAdvertiseDefaultIPv6Route;
482 bool fNeedDhcpServer;
483 uint32_t u32HostLoopback6Offset;
484 NATLoopbackOffsetList llHostLoopbackOffsetList;
485 NATRulesMap mapPortForwardRules4;
486 NATRulesMap mapPortForwardRules6;
487};
488
489typedef std::list<NATNetwork> NATNetworksList;
490
491#ifdef VBOX_WITH_VMNET
492/**
493 * HostOnly Networking settings.
494 */
495struct HostOnlyNetwork
496{
497 HostOnlyNetwork();
498
499 com::Guid uuid;
500 com::Utf8Str strNetworkName;
501 com::Utf8Str strNetworkMask;
502 com::Utf8Str strIPLower;
503 com::Utf8Str strIPUpper;
504 bool fEnabled;
505};
506
507typedef std::list<HostOnlyNetwork> HostOnlyNetworksList;
508#endif /* VBOX_WITH_VMNET */
509
510#ifdef VBOX_WITH_CLOUD_NET
511/**
512 * Cloud Networking settings.
513 */
514struct CloudNetwork
515{
516 CloudNetwork();
517
518 com::Utf8Str strNetworkName;
519 com::Utf8Str strProviderShortName;
520 com::Utf8Str strProfileName;
521 com::Utf8Str strNetworkId;
522 bool fEnabled;
523};
524
525typedef std::list<CloudNetwork> CloudNetworksList;
526#endif /* VBOX_WITH_CLOUD_NET */
527
528
529class MainConfigFile : public ConfigFileBase
530{
531public:
532 MainConfigFile(const com::Utf8Str *pstrFilename);
533
534 void readMachineRegistry(const xml::ElementNode &elmMachineRegistry);
535 void readNATNetworks(const xml::ElementNode &elmNATNetworks);
536 void readSharedFolders(const xml::ElementNode &elmSharedFolders);
537#ifdef VBOX_WITH_VMNET
538 void readHostOnlyNetworks(const xml::ElementNode &elmHostOnlyNetworks);
539#endif /* VBOX_WITH_VMNET */
540#ifdef VBOX_WITH_CLOUD_NET
541 void readCloudNetworks(const xml::ElementNode &elmCloudNetworks);
542#endif /* VBOX_WITH_CLOUD_NET */
543
544 void write(const com::Utf8Str strFilename);
545
546 Host host;
547 SystemProperties systemProperties;
548 PlatformProperties platformProperties;
549 MediaRegistry mediaRegistry;
550 MachinesRegistry llMachines;
551 DHCPServersList llDhcpServers;
552 NATNetworksList llNATNetworks;
553 SharedFoldersList llGlobalSharedFolders;
554#ifdef VBOX_WITH_VMNET
555 HostOnlyNetworksList llHostOnlyNetworks;
556#endif /* VBOX_WITH_VMNET */
557#ifdef VBOX_WITH_CLOUD_NET
558 CloudNetworksList llCloudNetworks;
559#endif /* VBOX_WITH_CLOUD_NET */
560 StringsMap mapExtraDataItems;
561
562private:
563 void bumpSettingsVersionIfNeeded();
564 void buildUSBDeviceSources(xml::ElementNode &elmParent, const USBDeviceSourcesList &ll);
565 void readUSBDeviceSources(const xml::ElementNode &elmDeviceSources, USBDeviceSourcesList &ll);
566 void buildDHCPServers(xml::ElementNode &elmDHCPServers, DHCPServersList const &ll);
567 void buildDHCPOptions(xml::ElementNode &elmOptions, DHCPConfig const &rConfig, bool fIgnoreSubnetMask);
568 void readDHCPServers(const xml::ElementNode &elmDHCPServers);
569 void readDHCPOptions(DHCPConfig &rConfig, const xml::ElementNode &elmOptions, bool fIgnoreSubnetMask);
570 bool convertGuiProxySettings(const com::Utf8Str &strUIProxySettings);
571};
572
573////////////////////////////////////////////////////////////////////////////////
574//
575// Machine XML structures
576//
577////////////////////////////////////////////////////////////////////////////////
578
579/**
580 * NOTE: If you add any fields in here, you must update a) the constructor and b)
581 * the operator== which is used by MachineConfigFile::operator==(), or otherwise
582 * your settings might never get saved.
583 */
584struct VRDESettings
585{
586 VRDESettings();
587
588 bool areDefaultSettings(SettingsVersion_T sv) const;
589
590 bool operator==(const VRDESettings& v) const;
591
592 bool fEnabled;
593 AuthType_T authType;
594 uint32_t ulAuthTimeout;
595 com::Utf8Str strAuthLibrary;
596 bool fAllowMultiConnection,
597 fReuseSingleConnection;
598 com::Utf8Str strVrdeExtPack;
599 StringsMap mapProperties;
600};
601
602/**
603 * NOTE: If you add any fields in here, you must update a) the constructor and b)
604 * the operator== which is used by MachineConfigFile::operator==(), or otherwise
605 * your settings might never get saved.
606 */
607struct FirmwareSettings
608{
609 FirmwareSettings();
610
611 bool areDefaultSettings(CPUArchitecture_T enmCPUArch) const;
612
613 bool operator==(const FirmwareSettings &d) const;
614
615 FirmwareType_T firmwareType; // requires settings version 1.9 (VirtualBox 3.1)
616 bool fACPIEnabled,
617 fIOAPICEnabled,
618 fLogoFadeIn,
619 fLogoFadeOut,
620 fPXEDebugEnabled,
621 fSmbiosUuidLittleEndian,
622 fAutoSerialNumGen;
623 uint32_t ulLogoDisplayTime;
624 FirmwareBootMenuMode_T enmBootMenuMode;
625 APICMode_T apicMode; // requires settings version 1.16 (VirtualBox 5.1)
626 int64_t llTimeOffset;
627 com::Utf8Str strLogoImagePath;
628};
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 */
635struct TpmSettings
636{
637 TpmSettings();
638
639 bool areDefaultSettings() const;
640
641 bool operator==(const TpmSettings &d) const;
642
643 TpmType_T tpmType;
644 com::Utf8Str strLocation;
645};
646
647/**
648 * NOTE: If you add any fields in here, you must update a) the constructor and b)
649 * the operator== which is used by MachineConfigFile::operator==(), or otherwise
650 * your settings might never get saved.
651 */
652struct NvramSettings
653{
654 NvramSettings();
655
656 bool areDefaultSettings() const;
657
658 bool operator==(const NvramSettings &d) const;
659
660 com::Utf8Str strNvramPath;
661 com::Utf8Str strKeyId;
662 com::Utf8Str strKeyStore;
663};
664
665/** List for keeping a recording feature list. */
666typedef std::map<RecordingFeature_T, bool> RecordingFeatureMap;
667
668/**
669 * Recording settings for a single screen (e.g. virtual monitor).
670 *
671 * NOTE: If you add any fields in here, you must update a) the constructor and b)
672 * the operator== which is used by MachineConfigFile::operator==(), or otherwise
673 * your settings might never get saved.
674 */
675struct RecordingScreen
676{
677 RecordingScreen(uint32_t idScreen = UINT32_MAX);
678 virtual ~RecordingScreen();
679
680#if RT_CPLUSPLUS_PREREQ(201100) /* VC2022: Excplit default copy constructor and copy assignment operator to avoid warnings. */
681 RecordingScreen(RecordingScreen const &) = default;
682 RecordingScreen &operator=(RecordingScreen const &) = default;
683#endif
684
685 void applyDefaults(void);
686
687 bool areDefaultSettings(void) const;
688
689 bool isFeatureEnabled(RecordingFeature_T enmFeature) const;
690
691 static const char *getDefaultOptions(void);
692
693 static int featuresFromString(const com::Utf8Str &strFeatures, RecordingFeatureMap &featureMap);
694
695 static void featuresToString(const RecordingFeatureMap &featureMap, com::Utf8Str &strFeatures);
696
697 static int audioCodecFromString(const com::Utf8Str &strCodec, RecordingAudioCodec_T &enmCodec);
698
699 static void audioCodecToString(const RecordingAudioCodec_T &enmCodec, com::Utf8Str &strCodec);
700
701 static int videoCodecFromString(const com::Utf8Str &strCodec, RecordingVideoCodec_T &enmCodec);
702
703 static void videoCodecToString(const RecordingVideoCodec_T &enmCodec, com::Utf8Str &strCodec);
704
705 bool operator==(const RecordingScreen &d) const;
706
707 /** Screen ID.
708 * UINT32_MAX if not set. */
709 uint32_t idScreen;
710 /** Whether to record this screen or not. */
711 bool fEnabled; // requires settings version 1.14 (VirtualBox 4.3)
712 /** Destination to record to. */
713 RecordingDestination_T enmDest;
714 /** Which features are enable or not. */
715 RecordingFeatureMap featureMap; // requires settings version 1.19 (VirtualBox 7.0)
716 /** Maximum time (in s) to record. If set to 0, no time limit is set. */
717 uint32_t ulMaxTimeS; // requires settings version 1.14 (VirtualBox 4.3)
718 /** Options string for hidden / advanced / experimental features.
719 * Use RecordingScreenSettings::getDefaultOptions(). */
720 com::Utf8Str strOptions; // new since VirtualBox 5.2.
721
722 /**
723 * Structure holding settings for audio recording.
724 */
725 struct Audio
726 {
727 /** The audio codec type to use. */
728 RecordingAudioCodec_T enmCodec; // requires settings version 1.19 (VirtualBox 7.0)
729 /** Codec deadline to use. */
730 RecordingCodecDeadline_T enmDeadline; // requires settings version 1.19 (VirtualBox 7.0)
731 /** Rate control mode to use. */
732 RecordingRateControlMode_T
733 enmRateCtlMode;// requires settings version 1.19 (VirtualBox 7.0)
734 /** Hz rate. */
735 uint16_t uHz; // requires settings version 1.19 (VirtualBox 7.0)
736 /** Bits per sample. */
737 uint8_t cBits; // requires settings version 1.19 (VirtualBox 7.0)
738 /** Number of audio channels. */
739 uint8_t cChannels; // requires settings version 1.19 (VirtualBox 7.0)
740 } Audio;
741
742 /**
743 * Structure holding settings for video recording.
744 */
745 struct Video
746 {
747 /** The codec to use. */
748 RecordingVideoCodec_T enmCodec; // requires settings version 1.19 (VirtualBox 7.0)
749 /** Codec deadline to use. */
750 RecordingCodecDeadline_T enmDeadline; // requires settings version 1.19 (VirtualBox 7.0)
751 /** Rate control mode to use. */
752 RecordingRateControlMode_T
753 enmRateCtlMode; // requires settings version 1.19 (VirtualBox 7.0)
754 /** Rate control mode to use. */
755 RecordingVideoScalingMode_T
756 enmScalingMode; // requires settings version 1.19 (VirtualBox 7.0)
757 /** Target frame width in pixels (X). */
758 uint32_t ulWidth; // requires settings version 1.14 (VirtualBox 4.3)
759 /** Target frame height in pixels (Y). */
760 uint32_t ulHeight; // requires settings version 1.14 (VirtualBox 4.3)
761 /** Encoding rate. */
762 uint32_t ulRate; // requires settings version 1.14 (VirtualBox 4.3)
763 /** Frames per second (FPS). */
764 uint32_t ulFPS; // requires settings version 1.14 (VirtualBox 4.3)
765 } Video;
766
767 /**
768 * Structure holding settings if the destination is a file.
769 */
770 struct File
771 {
772 /** Maximum size (in MB) the file is allowed to have.
773 * When reaching the limit, recording will stop. 0 means no limit. */
774 uint32_t ulMaxSizeMB; // requires settings version 1.14 (VirtualBox 4.3)
775 /** Absolute file name path to use for recording.
776 * When empty, this is considered as being the default setting. */
777 com::Utf8Str strName; // requires settings version 1.14 (VirtualBox 4.3)
778 } File;
779};
780
781/** Map for keeping settings per virtual screen.
782 * The key specifies the screen ID. */
783typedef std::map<uint32_t, RecordingScreen> RecordingScreenSettingsMap;
784
785/**
786 * Common recording settings, shared among all per-screen recording settings.
787 *
788 * NOTE: If you add any fields in here, you must update a) the constructor and b)
789 * the operator== which is used by MachineConfigFile::operator==(), or otherwise
790 * your settings might never get saved.
791 */
792struct RecordingCommon
793{
794 RecordingCommon();
795
796 void applyDefaults(void);
797
798 bool areDefaultSettings(void) const;
799
800 bool operator==(const RecordingCommon &d) const;
801
802 /** Whether recording as a whole is enabled or disabled. */
803 bool fEnabled; // requires settings version 1.14 (VirtualBox 4.3)
804};
805
806/**
807 * NOTE: If you add any fields in here, you must update a) the constructor and b)
808 * the operator== which is used by MachineConfigFile::operator==(), or otherwise
809 * your settings might never get saved.
810 */
811struct Recording
812{
813 Recording();
814
815 void applyDefaults(void);
816
817 bool areDefaultSettings(void) const;
818
819 bool operator==(const Recording &that) const;
820
821 /** Common settings for all per-screen recording settings. */
822 RecordingCommon common;
823 /** Map of handled recording screen settings.
824 * The key specifies the screen ID. */
825 RecordingScreenSettingsMap mapScreens;
826};
827
828/**
829 * NOTE: If you add any fields in here, you must update a) the constructor and b)
830 * the operator== which is used by MachineConfigFile::operator==(), or otherwise
831 * your settings might never get saved.
832 */
833struct GraphicsAdapter
834{
835 GraphicsAdapter();
836
837 bool areDefaultSettings() const;
838
839 bool operator==(const GraphicsAdapter &g) const;
840
841 GraphicsControllerType_T graphicsControllerType;
842 uint32_t ulVRAMSizeMB;
843 uint32_t cMonitors;
844 bool fAccelerate3D,
845 fAccelerate2DVideo; // requires settings version 1.8 (VirtualBox 3.1)
846};
847
848/**
849 * NOTE: If you add any fields in here, you must update a) the constructor and b)
850 * the operator== which is used by MachineConfigFile::operator==(), or otherwise
851 * your settings might never get saved.
852 */
853struct USBController
854{
855 USBController();
856
857 bool operator==(const USBController &u) const;
858
859 com::Utf8Str strName;
860 USBControllerType_T enmType;
861};
862
863typedef std::list<USBController> USBControllerList;
864
865struct USB
866{
867 USB();
868
869 bool operator==(const USB &u) const;
870
871 /** List of USB controllers present. */
872 USBControllerList llUSBControllers;
873 /** List of USB device filters. */
874 USBDeviceFiltersList llDeviceFilters;
875};
876
877struct NAT
878{
879 NAT();
880
881 bool areDNSDefaultSettings() const;
882 bool areAliasDefaultSettings() const;
883 bool areTFTPDefaultSettings() const;
884 bool areLocalhostReachableDefaultSettings(SettingsVersion_T sv) const;
885 bool areDefaultSettings(SettingsVersion_T sv) const;
886
887 bool operator==(const NAT &n) const;
888
889 com::Utf8Str strNetwork;
890 com::Utf8Str strBindIP;
891 uint32_t u32Mtu;
892 uint32_t u32SockRcv;
893 uint32_t u32SockSnd;
894 uint32_t u32TcpRcv;
895 uint32_t u32TcpSnd;
896 com::Utf8Str strTFTPPrefix;
897 com::Utf8Str strTFTPBootFile;
898 com::Utf8Str strTFTPNextServer;
899 bool fDNSPassDomain;
900 bool fDNSProxy;
901 bool fDNSUseHostResolver;
902 bool fAliasLog;
903 bool fAliasProxyOnly;
904 bool fAliasUseSamePorts;
905 bool fLocalhostReachable;
906 bool fForwardBroadcast;
907 NATRulesMap mapRules;
908};
909
910/**
911 * NOTE: If you add any fields in here, you must update a) the constructor and b)
912 * the operator== which is used by MachineConfigFile::operator==(), or otherwise
913 * your settings might never get saved.
914 */
915struct NetworkAdapter
916{
917 NetworkAdapter();
918
919 bool areGenericDriverDefaultSettings() const;
920 bool areDefaultSettings(SettingsVersion_T sv) const;
921 bool areDisabledDefaultSettings(SettingsVersion_T sv) const;
922
923 bool operator==(const NetworkAdapter &n) const;
924
925 uint32_t ulSlot;
926
927 NetworkAdapterType_T type;
928 bool fEnabled;
929 com::Utf8Str strMACAddress;
930 bool fCableConnected;
931 uint32_t ulLineSpeed;
932 NetworkAdapterPromiscModePolicy_T enmPromiscModePolicy;
933 bool fTraceEnabled;
934 com::Utf8Str strTraceFile;
935
936 NetworkAttachmentType_T mode;
937 NAT nat;
938 com::Utf8Str strBridgedName;
939 com::Utf8Str strHostOnlyName;
940#ifdef VBOX_WITH_VMNET
941 com::Utf8Str strHostOnlyNetworkName;
942#endif /* VBOX_WITH_VMNET */
943 com::Utf8Str strInternalNetworkName;
944 com::Utf8Str strGenericDriver;
945 StringsMap genericProperties;
946 com::Utf8Str strNATNetworkName;
947#ifdef VBOX_WITH_CLOUD_NET
948 com::Utf8Str strCloudNetworkName;
949#endif /* VBOX_WITH_CLOUD_NET */
950 uint32_t ulBootPriority;
951 com::Utf8Str strBandwidthGroup; // requires settings version 1.13 (VirtualBox 4.2)
952};
953
954typedef std::list<NetworkAdapter> NetworkAdaptersList;
955
956/**
957 * NOTE: If you add any fields in here, you must update a) the constructor and b)
958 * the operator== which is used by MachineConfigFile::operator==(), or otherwise
959 * your settings might never get saved.
960 */
961struct SerialPort
962{
963 SerialPort();
964
965 bool operator==(const SerialPort &n) const;
966
967 uint32_t ulSlot;
968
969 bool fEnabled;
970 uint32_t ulIOAddress;
971 uint32_t ulIRQ;
972 PortMode_T portMode;
973 com::Utf8Str strPath;
974 bool fServer;
975 UartType_T uartType;
976};
977
978typedef std::list<SerialPort> SerialPortsList;
979
980/**
981 * NOTE: If you add any fields in here, you must update a) the constructor and b)
982 * the operator== which is used by MachineConfigFile::operator==(), or otherwise
983 * your settings might never get saved.
984 */
985struct ParallelPort
986{
987 ParallelPort();
988
989 bool operator==(const ParallelPort &d) const;
990
991 uint32_t ulSlot;
992
993 bool fEnabled;
994 uint32_t ulIOBase;
995 uint32_t ulIRQ;
996 com::Utf8Str strPath;
997};
998
999typedef std::list<ParallelPort> ParallelPortsList;
1000
1001/**
1002 * NOTE: If you add any fields in here, you must update a) the constructor and b)
1003 * the operator== which is used by MachineConfigFile::operator==(), or otherwise
1004 * your settings might never get saved.
1005 */
1006struct AudioAdapter
1007{
1008 AudioAdapter();
1009
1010 bool areDefaultSettings(SettingsVersion_T sv) const;
1011
1012 bool operator==(const AudioAdapter &a) const;
1013
1014 bool fEnabled;
1015 bool fEnabledIn;
1016 bool fEnabledOut;
1017 AudioControllerType_T controllerType;
1018 AudioCodecType_T codecType;
1019 AudioDriverType_T driverType;
1020 settings::StringsMap properties;
1021};
1022
1023/**
1024 * NOTE: If you add any fields in here, you must update a) the constructor and b)
1025 * the operator== which is used by MachineConfigFile::operator==(), or otherwise
1026 * your settings might never get saved.
1027 */
1028struct GuestProperty
1029{
1030 GuestProperty();
1031
1032 bool operator==(const GuestProperty &g) const;
1033
1034 com::Utf8Str strName,
1035 strValue;
1036 uint64_t timestamp;
1037 com::Utf8Str strFlags;
1038};
1039
1040typedef std::list<GuestProperty> GuestPropertiesList;
1041
1042typedef std::map<uint32_t, DeviceType_T> BootOrderMap;
1043
1044/**
1045 * NOTE: If you add any fields in here, you must update a) the constructor and b)
1046 * the operator== which is used by MachineConfigFile::operator==(), or otherwise
1047 * your settings might never get saved.
1048 */
1049struct CpuIdLeafX86
1050{
1051 CpuIdLeafX86();
1052
1053 bool operator==(const CpuIdLeafX86 &c) const;
1054
1055 uint32_t idx;
1056 uint32_t idxSub;
1057 uint32_t uEax;
1058 uint32_t uEbx;
1059 uint32_t uEcx;
1060 uint32_t uEdx;
1061};
1062
1063typedef std::list<CpuIdLeafX86> CpuIdLeafsX86List;
1064
1065/**
1066 * NOTE: If you add any fields in here, you must update a) the constructor and b)
1067 * the operator== which is used by MachineConfigFile::operator==(), or otherwise
1068 * your settings might never get saved.
1069 */
1070struct Cpu
1071{
1072 Cpu();
1073
1074 bool operator==(const Cpu &c) const;
1075
1076 uint32_t ulId;
1077};
1078
1079typedef std::list<Cpu> CpuList;
1080
1081/**
1082 * NOTE: If you add any fields in here, you must update a) the constructor and b)
1083 * the operator== which is used by MachineConfigFile::operator==(), or otherwise
1084 * your settings might never get saved.
1085 */
1086struct BandwidthGroup
1087{
1088 BandwidthGroup();
1089
1090 bool operator==(const BandwidthGroup &i) const;
1091
1092 com::Utf8Str strName;
1093 uint64_t cMaxBytesPerSec;
1094 BandwidthGroupType_T enmType;
1095};
1096
1097typedef std::list<BandwidthGroup> BandwidthGroupList;
1098
1099/**
1100 * NOTE: If you add any fields in here, you must update a) the constructor and b)
1101 * the operator== which is used by MachineConfigFile::operator==(), or otherwise
1102 * your settings might never get saved.
1103 */
1104struct IOSettings
1105{
1106 IOSettings();
1107
1108 bool areIOCacheDefaultSettings() const;
1109 bool areDefaultSettings() const;
1110
1111 bool operator==(const IOSettings &i) const;
1112
1113 bool fIOCacheEnabled;
1114 uint32_t ulIOCacheSize;
1115 BandwidthGroupList llBandwidthGroups;
1116};
1117
1118/**
1119 * NOTE: If you add any fields in here, you must update a) the constructor and b)
1120 * the operator== which is used by MachineConfigFile::operator==(), or otherwise
1121 * your settings might never get saved.
1122 */
1123struct HostPCIDeviceAttachment
1124{
1125 HostPCIDeviceAttachment();
1126
1127 bool operator==(const HostPCIDeviceAttachment &a) const;
1128
1129 com::Utf8Str strDeviceName;
1130 uint32_t uHostAddress;
1131 uint32_t uGuestAddress;
1132};
1133
1134typedef std::list<HostPCIDeviceAttachment> HostPCIDeviceAttachmentList;
1135
1136/**
1137 * A device attached to a storage controller. This can either be a
1138 * hard disk or a DVD drive or a floppy drive and also specifies
1139 * which medium is "in" the drive; as a result, this is a combination
1140 * of the Main IMedium and IMediumAttachment interfaces.
1141 *
1142 * NOTE: If you add any fields in here, you must update a) the constructor and b)
1143 * the operator== which is used by MachineConfigFile::operator==(), or otherwise
1144 * your settings might never get saved.
1145 */
1146struct AttachedDevice
1147{
1148 AttachedDevice();
1149
1150 bool operator==(const AttachedDevice &a) const;
1151
1152 DeviceType_T deviceType; // only HardDisk, DVD or Floppy are allowed
1153
1154 // DVDs can be in pass-through mode:
1155 bool fPassThrough;
1156
1157 // Whether guest-triggered eject of DVDs will keep the medium in the
1158 // VM config or not:
1159 bool fTempEject;
1160
1161 // Whether the medium is non-rotational:
1162 bool fNonRotational;
1163
1164 // Whether the medium supports discarding unused blocks:
1165 bool fDiscard;
1166
1167 // Whether the medium is hot-pluggable:
1168 bool fHotPluggable;
1169
1170 int32_t lPort;
1171 int32_t lDevice;
1172
1173 // if an image file is attached to the device (ISO, RAW, or hard disk image such as VDI),
1174 // this is its UUID; it depends on deviceType which media registry this then needs to
1175 // be looked up in. If no image file (only permitted for DVDs and floppies), then the UUID is NULL
1176 com::Guid uuid;
1177
1178 // for DVDs and floppies, the attachment can also be a host device:
1179 com::Utf8Str strHostDriveSrc; // if != NULL, value of <HostDrive>/@src
1180
1181 // Bandwidth group the device is attached to.
1182 com::Utf8Str strBwGroup;
1183};
1184
1185typedef std::list<AttachedDevice> AttachedDevicesList;
1186
1187/**
1188 * NOTE: If you add any fields in here, you must update a) the constructor and b)
1189 * the operator== which is used by MachineConfigFile::operator==(), or otherwise
1190 * your settings might never get saved.
1191 */
1192struct StorageController
1193{
1194 StorageController();
1195
1196 bool operator==(const StorageController &s) const;
1197
1198 com::Utf8Str strName;
1199 StorageBus_T storageBus; // _SATA, _SCSI, _IDE, _SAS
1200 StorageControllerType_T controllerType;
1201 uint32_t ulPortCount;
1202 uint32_t ulInstance;
1203 bool fUseHostIOCache;
1204 bool fBootable;
1205
1206 AttachedDevicesList llAttachedDevices;
1207};
1208
1209typedef std::list<StorageController> StorageControllersList;
1210
1211/**
1212 * We wrap the storage controllers list into an extra struct so we can
1213 * use an undefined struct without needing std::list<> in all the headers.
1214 *
1215 * NOTE: If you add any fields in here, you must update a) the constructor and b)
1216 * the operator== which is used by MachineConfigFile::operator==(), or otherwise
1217 * your settings might never get saved.
1218 */
1219struct Storage
1220{
1221 bool operator==(const Storage &s) const;
1222
1223 StorageControllersList llStorageControllers;
1224};
1225
1226#ifdef VBOX_WITH_VIRT_ARMV8
1227struct PlatformARM
1228{
1229 PlatformARM();
1230
1231 bool operator==(const PlatformARM&) const;
1232
1233 /** Nested hardware virtualization. */
1234 bool fNestedHWVirt; //< requires settings version 1.20 (VirtualBox 7.1)
1235};
1236#endif /* VBOX_WITH_VIRT_ARMV8 */
1237
1238/**
1239 * Covers x86-specific platform attributes.
1240 *
1241 * New since settings v1.20 (VirtualBox 7.1).
1242 * Contains attributes which were in the Hardware settings before.
1243 */
1244struct PlatformX86
1245{
1246 PlatformX86();
1247
1248 bool operator==(const PlatformX86&) const;
1249
1250 /** Note: Lived in Hardware for settings < version 1.20 (requires settings version 1.10 (VirtualBox 3.2). */
1251 bool fPAE;
1252 /** Note: Lived in Hardware for settings < version 1.20 (requires settings version 1.10 (VirtualBox 3.2). */
1253 bool fAPIC; // requires settings version 1.16 (VirtualBox 5.1)
1254 /** Note: Lived in Hardware for settings < version 1.20 (requires settings version 1.10 (VirtualBox 3.2). */
1255 bool fX2APIC; // requires settings version 1.16 (VirtualBox 5.1)
1256 /** Note: Lived in Hardware for settings < version 1.20 (requires settings version 1.10 (VirtualBox 3.2). */
1257 bool fHPETEnabled;
1258 /** Note: Lived in Hardware for settings < version 1.20. */
1259 typedef enum LongModeType { LongMode_Enabled, LongMode_Disabled, LongMode_Legacy } LongModeType;
1260 /** Note: Lived in Hardware for settings < version 1.20. */
1261 LongModeType enmLongMode;
1262 /** Custom x86 CPUID leafs list.
1263 * Note: Lived in Hardware for settings < version 1.20. */
1264 CpuIdLeafsX86List llCpuIdLeafs;
1265 /** Note: Lived in Hardware for settings < version 1.20. */
1266 bool fTripleFaultReset;
1267 /** Note: Lived in Hardware for settings < version 1.20. */
1268 bool fIBPBOnVMExit; //< added out of cycle, after settings version 1.16 was out.
1269 /** Note: Lived in Hardware for settings < version 1.20. */
1270 bool fIBPBOnVMEntry; //< added out of cycle, after settings version 1.16 was out.
1271 /** Note: Lived in Hardware for settings < version 1.20. */
1272 bool fSpecCtrl; //< added out of cycle, after settings version 1.16 was out.
1273 /** Note: Lived in Hardware for settings < version 1.20. */
1274 bool fSpecCtrlByHost; //< added out of cycle, after settings version 1.16 was out.
1275 /** Note: Lived in Hardware for settings < version 1.20. */
1276 bool fL1DFlushOnSched; //< added out of cycle, after settings version 1.16 was out.
1277 /** Note: Lived in Hardware for settings < version 1.20. */
1278 bool fL1DFlushOnVMEntry; //< added out of cycle, after settings version 1.16 was out.
1279 /** Note: Lived in Hardware for settings < version 1.20. */
1280 bool fMDSClearOnSched; //< added out of cycle, after settings version 1.16 was out.
1281 /** Note: Lived in Hardware for settings < version 1.20. */
1282 bool fMDSClearOnVMEntry; //< added out of cycle, after settings version 1.16 was out.
1283 bool fHWVirtEx;
1284 bool fHWVirtExNestedPaging;
1285 bool fHWVirtExLargePages;
1286 bool fHWVirtExVPID;
1287 /** Unrestricted execution. */
1288 bool fHWVirtExUX;
1289 bool fHWVirtExForce;
1290 bool fHWVirtExUseNativeApi;
1291 /** AMD-V VMSAVE/VMLOAD. */
1292 bool fHWVirtExVirtVmsaveVmload;
1293 /** Nested VT-x / AMD-V.
1294 * Note: Lived in Hardware for settings < version 1.20. */
1295 bool fNestedHWVirt; //< requires settings version 1.17 (VirtualBox 6.0)
1296};
1297
1298/**
1299 * Covers common platform attributes.
1300 *
1301 * New since settings v1.20 (VirtualBox 7.1).
1302 * Contains attributes which were in the Hardware settings before.
1303 */
1304struct Platform
1305{
1306 Platform();
1307
1308 bool operator==(const Platform&) const;
1309
1310 /** Requires settings version 1.20 (VirtualBox 7.1). */
1311 PlatformArchitecture_T architectureType;
1312 /** Note: Lived in Hardware for settings < version 1.20 (requires settings version 1.11 (VirtualBox 4.0). */
1313 ChipsetType_T chipsetType;
1314 /** Note: Lived in Hardware for settings < version 1.20 (requires settings version 1.19 (VirtualBox 6.2). */
1315 IommuType_T iommuType;
1316 /** Note: Lived in Hardware for settings < version 1.20. */
1317 bool fRTCUseUTC;
1318 /** Note: Is a class, so we can't use a union here. */
1319 PlatformX86 x86;
1320#ifdef VBOX_WITH_VIRT_ARMV8
1321 /** Note: Is a class, so we can't use a union here. */
1322 PlatformARM arm;
1323#endif
1324};
1325
1326/**
1327 * Representation of Machine hardware; this is used in the MachineConfigFile.hardwareMachine
1328 * field.
1329 *
1330 * NOTE: If you add any fields in here, you must update a) the constructor and b)
1331 * the operator== which is used by MachineConfigFile::operator==(), or otherwise
1332 * your settings might never get saved.
1333 */
1334struct Hardware
1335{
1336 Hardware();
1337
1338 bool areParavirtDefaultSettings(SettingsVersion_T sv) const;
1339 bool areBootOrderDefaultSettings() const;
1340 bool areDisplayDefaultSettings() const;
1341 bool areAllNetworkAdaptersDefaultSettings(SettingsVersion_T sv) const;
1342
1343 bool operator==(const Hardware&) const;
1344
1345 com::Utf8Str strVersion; // hardware version, optional
1346 com::Guid uuid; // hardware uuid, optional (null).
1347 uint32_t cCPUs;
1348 bool fCpuHotPlug; // requires settings version 1.10 (VirtualBox 3.2)
1349 CpuList llCpus; // requires settings version 1.10 (VirtualBox 3.2)
1350 uint32_t ulCpuExecutionCap; // requires settings version 1.11 (VirtualBox 3.3)
1351 uint32_t uCpuIdPortabilityLevel; // requires settings version 1.15 (VirtualBox 5.0)
1352 com::Utf8Str strCpuProfile; // requires settings version 1.16 (VirtualBox 5.1)
1353
1354 uint32_t ulMemorySizeMB;
1355
1356 BootOrderMap mapBootOrder; // item 0 has highest priority
1357
1358 PointingHIDType_T pointingHIDType; // requires settings version 1.10 (VirtualBox 3.2)
1359 KeyboardHIDType_T keyboardHIDType; // requires settings version 1.10 (VirtualBox 3.2)
1360
1361 ParavirtProvider_T paravirtProvider; // requires settings version 1.15 (VirtualBox 4.4)
1362 com::Utf8Str strParavirtDebug; // requires settings version 1.16 (VirtualBox 5.1)
1363
1364 bool fEmulatedUSBCardReader; // 1.12 (VirtualBox 4.1)
1365
1366 VRDESettings vrdeSettings;
1367
1368 Platform platformSettings; // new since 1.20 (VirtualBox 7.1)
1369 FirmwareSettings firmwareSettings;
1370 NvramSettings nvramSettings;
1371 GraphicsAdapter graphicsAdapter;
1372 USB usbSettings;
1373 TpmSettings tpmSettings; // requires settings version 1.19 (VirtualBox 6.2)
1374 NetworkAdaptersList llNetworkAdapters;
1375 SerialPortsList llSerialPorts;
1376 ParallelPortsList llParallelPorts;
1377 AudioAdapter audioAdapter;
1378 Storage storage;
1379
1380 // technically these two have no business in the hardware section, but for some
1381 // clever reason <Hardware> is where they are in the XML....
1382 SharedFoldersList llSharedFolders;
1383
1384 ClipboardMode_T clipboardMode;
1385 bool fClipboardFileTransfersEnabled;
1386
1387 DnDMode_T dndMode;
1388
1389 uint32_t ulMemoryBalloonSize;
1390 bool fPageFusionEnabled;
1391
1392 GuestPropertiesList llGuestProperties;
1393
1394 IOSettings ioSettings; // requires settings version 1.10 (VirtualBox 3.2)
1395 HostPCIDeviceAttachmentList pciAttachments; // requires settings version 1.12 (VirtualBox 4.1)
1396
1397 com::Utf8Str strDefaultFrontend; // requires settings version 1.14 (VirtualBox 4.3)
1398};
1399
1400/**
1401 * Settings that has to do with debugging.
1402 */
1403struct Debugging
1404{
1405 Debugging();
1406
1407 bool areDefaultSettings() const;
1408
1409 bool operator==(const Debugging &rOther) const;
1410
1411 bool fTracingEnabled;
1412 bool fAllowTracingToAccessVM;
1413 com::Utf8Str strTracingConfig;
1414 GuestDebugProvider_T enmDbgProvider;
1415 GuestDebugIoProvider_T enmIoProvider;
1416 com::Utf8Str strAddress;
1417 uint32_t ulPort;
1418};
1419
1420/**
1421 * Settings that has to do with autostart.
1422 */
1423struct Autostart
1424{
1425 Autostart();
1426
1427 bool areDefaultSettings() const;
1428
1429 bool operator==(const Autostart &rOther) const;
1430
1431 bool fAutostartEnabled;
1432 uint32_t uAutostartDelay;
1433 AutostopType_T enmAutostopType;
1434};
1435
1436struct Snapshot;
1437typedef std::list<Snapshot> SnapshotsList;
1438
1439/**
1440 * NOTE: If you add any fields in here, you must update a) the constructor and b)
1441 * the operator== which is used by MachineConfigFile::operator==(), or otherwise
1442 * your settings might never get saved.
1443 */
1444struct Snapshot
1445{
1446 Snapshot();
1447
1448 bool operator==(const Snapshot &s) const;
1449
1450 com::Guid uuid;
1451 com::Utf8Str strName,
1452 strDescription; // optional
1453 RTTIMESPEC timestamp;
1454
1455 com::Utf8Str strStateFile; // for online snapshots only
1456
1457 Hardware hardware;
1458
1459 Debugging debugging;
1460 Autostart autostart;
1461 Recording recordingSettings;
1462
1463 SnapshotsList llChildSnapshots;
1464
1465 static const struct Snapshot Empty;
1466};
1467
1468/**
1469 * NOTE: If you add any fields in here, you must update a) the constructor and b)
1470 * the operator== which is used by MachineConfigFile::operator==(), or otherwise
1471 * your settings might never get saved.
1472 */
1473struct MachineUserData
1474{
1475 MachineUserData();
1476
1477 bool operator==(const MachineUserData &c) const;
1478
1479 com::Utf8Str strName;
1480 bool fDirectoryIncludesUUID;
1481 bool fNameSync;
1482 com::Utf8Str strDescription;
1483 StringsList llGroups;
1484 com::Utf8Str strOsType;
1485 com::Utf8Str strSnapshotFolder;
1486 bool fTeleporterEnabled;
1487 uint32_t uTeleporterPort;
1488 com::Utf8Str strTeleporterAddress;
1489 com::Utf8Str strTeleporterPassword;
1490 IconBlob ovIcon;
1491 VMProcPriority_T enmVMPriority;
1492 VMExecutionEngine_T enmExecEngine;
1493};
1494
1495
1496/**
1497 * MachineConfigFile represents an XML machine configuration. All the machine settings
1498 * that go out to the XML (or are read from it) are in here.
1499 *
1500 * NOTE: If you add any fields in here, you must update a) the constructor and b)
1501 * the operator== which is used by Machine::saveSettings(), or otherwise your settings
1502 * might never get saved.
1503 */
1504class MachineConfigFile : public ConfigFileBase
1505{
1506public:
1507 com::Guid uuid;
1508
1509 enum
1510 {
1511 ParseState_NotParsed,
1512 ParseState_PasswordError,
1513 ParseState_Parsed
1514 } enmParseState;
1515
1516 MachineUserData machineUserData;
1517
1518 com::Utf8Str strStateKeyId;
1519 com::Utf8Str strStateKeyStore;
1520 com::Utf8Str strStateFile;
1521 bool fCurrentStateModified; // optional, default is true
1522 RTTIMESPEC timeLastStateChange; // optional, defaults to now
1523 bool fAborted; // optional, default is false
1524
1525 com::Guid uuidCurrentSnapshot;
1526
1527 Hardware hardwareMachine;
1528 MediaRegistry mediaRegistry;
1529 Debugging debugging;
1530 Autostart autostart;
1531 Recording recordingSettings;
1532
1533 StringsMap mapExtraDataItems;
1534
1535 SnapshotsList llFirstSnapshot; // first snapshot or empty list if there's none
1536
1537 com::Utf8Str strKeyId;
1538 com::Utf8Str strKeyStore; // if not empty, the encryption is used
1539 com::Utf8Str strLogKeyId;
1540 com::Utf8Str strLogKeyStore;
1541
1542 MachineConfigFile(const com::Utf8Str *pstrFilename,
1543 PCVBOXCRYPTOIF pCryptoIf = NULL,
1544 const char *pszPassword = NULL);
1545
1546 bool operator==(const MachineConfigFile &m) const;
1547
1548 bool canHaveOwnMediaRegistry() const;
1549
1550 void importMachineXML(const xml::ElementNode &elmMachine);
1551
1552 void write(const com::Utf8Str &strFilename, PCVBOXCRYPTOIF pCryptoIf = NULL, const char *pszPassword = NULL);
1553
1554 enum
1555 {
1556 BuildMachineXML_IncludeSnapshots = 0x01,
1557 BuildMachineXML_WriteVBoxVersionAttribute = 0x02,
1558 BuildMachineXML_SkipRemovableMedia = 0x04,
1559 BuildMachineXML_MediaRegistry = 0x08,
1560 BuildMachineXML_SuppressSavedState = 0x10
1561 };
1562
1563 void copyEncryptionSettingsFrom(const MachineConfigFile &other);
1564 void buildMachineXML(xml::ElementNode &elmMachine,
1565 uint32_t fl,
1566 std::list<xml::ElementNode*> *pllElementsWithUuidAttributes);
1567
1568 static bool isAudioDriverAllowedOnThisHost(AudioDriverType_T enmDrvType);
1569 static AudioDriverType_T getHostDefaultAudioDriver();
1570
1571private:
1572 void readNetworkAdapters(const xml::ElementNode &elmHardware, NetworkAdaptersList &ll);
1573 void readAttachedNetworkMode(const xml::ElementNode &pelmMode, bool fEnabled, NetworkAdapter &nic);
1574 void readCpuIdTreeX86(const xml::ElementNode &elmCpuid, CpuIdLeafsX86List &ll);
1575 void readCpuTree(const xml::ElementNode &elmCpu, CpuList &ll);
1576 void readSerialPorts(const xml::ElementNode &elmUART, SerialPortsList &ll);
1577 void readParallelPorts(const xml::ElementNode &elmLPT, ParallelPortsList &ll);
1578 void readAudioAdapter(const xml::ElementNode &elmAudioAdapter, AudioAdapter &aa);
1579 void readGuestProperties(const xml::ElementNode &elmGuestProperties, Hardware &hw);
1580 void readStorageControllerAttributes(const xml::ElementNode &elmStorageController, StorageController &sctl);
1581 void readPlatformCPUIDTreeX86(const xml::ElementNode &elmChild, PlatformX86 &platX86);
1582 void readPlatformX86(const xml::ElementNode &elmPlatformX86OrHardware, PlatformX86 &platX86);
1583#ifdef VBOX_WITH_VIRT_ARMV8
1584 void readPlatformARM(const xml::ElementNode &elmPlatformARM, PlatformARM &platARM);
1585#endif
1586 void readPlatform(const xml::ElementNode &elmPlatformOrHardware, Hardware &hw, Platform &plat);
1587 void readHardware(const xml::ElementNode &elmHardware, Hardware &hw);
1588 void readHardDiskAttachments_pre1_7(const xml::ElementNode &elmHardDiskAttachments, Storage &strg);
1589 void readStorageControllers(const xml::ElementNode &elmStorageControllers, Storage &strg);
1590 void readDVDAndFloppies_pre1_9(const xml::ElementNode &elmHardware, Storage &strg);
1591 void readTeleporter(const xml::ElementNode &elmTeleporter, MachineUserData &userData);
1592 void readDebugging(const xml::ElementNode &elmDbg, Debugging &dbg);
1593 void readAutostart(const xml::ElementNode &elmAutostart, Autostart &autostrt);
1594 void readRecordingSettings(const xml::ElementNode &elmRecording, uint32_t cMonitors, Recording &recording);
1595 void readGroups(const xml::ElementNode &elmGroups, StringsList &llGroups);
1596 bool readSnapshot(const com::Guid &curSnapshotUuid, const xml::ElementNode &elmSnapshot, Snapshot &snap);
1597 static void convertGuestOSTypeFromPre1_5(com::Utf8Str &str);
1598#ifdef GUEST_OS_ID_STYLE_PARTIAL_CLEANUP
1599 static void convertGuestOSTypeFromPre1_20(com::Utf8Str &str);
1600 static void convertGuestOSTypeToPre1_20(com::Utf8Str &str);
1601#else
1602 static void convertGuestOSTypeFromDev1_20(com::Utf8Str &a_rstrOsType);
1603#endif
1604 static void convertGuestOSTypeSuffix(com::Utf8Str &a_rstrOsType, const char *a_pszToReplace, const char *a_pszReplacement);
1605 void readMachine(const xml::ElementNode &elmMachine);
1606 void readMachineEncrypted(const xml::ElementNode &elmMachine, PCVBOXCRYPTOIF pCryptoIf, const char *pszPassword);
1607
1608 void buildPlatformX86XML(xml::ElementNode &elmParent, xml::ElementNode &elmCPU, const PlatformX86 &plat);
1609#ifdef VBOX_WITH_VIRT_ARMV8
1610 void buildPlatformARMXML(xml::ElementNode &elmParent, const PlatformARM &plat);
1611#endif
1612 void buildPlatformXML(xml::ElementNode &elmParent, const Hardware &h, const Platform &plat);
1613 void buildHardwareXML(xml::ElementNode &elmParent, const Hardware &hw, uint32_t fl, std::list<xml::ElementNode*> *pllElementsWithUuidAttributes);
1614 void buildNetworkXML(NetworkAttachmentType_T mode, bool fEnabled, xml::ElementNode &elmParent, const NetworkAdapter &nic);
1615 void buildStorageControllersXML(xml::ElementNode &elmParent,
1616 const Storage &st,
1617 bool fSkipRemovableMedia,
1618 std::list<xml::ElementNode*> *pllElementsWithUuidAttributes);
1619 void buildDebuggingXML(xml::ElementNode &elmParent, const Debugging &dbg);
1620 void buildAutostartXML(xml::ElementNode &elmParent, const Autostart &autostrt);
1621 void buildRecordingXML(xml::ElementNode &elmParent, const Recording &recording);
1622 void buildGroupsXML(xml::ElementNode &elmParent, const StringsList &llGroups);
1623 void buildSnapshotXML(xml::ElementNode &elmParent, const Snapshot &snap);
1624
1625 void buildMachineEncryptedXML(xml::ElementNode &elmMachine,
1626 uint32_t fl,
1627 std::list<xml::ElementNode*> *pllElementsWithUuidAttributes,
1628 PCVBOXCRYPTOIF pCryptoIf,
1629 const char *pszPassword);
1630
1631 void bumpSettingsVersionIfNeeded();
1632};
1633
1634} // namespace settings
1635
1636
1637#endif /* !VBOX_INCLUDED_settings_h */
注意: 瀏覽 TracBrowser 來幫助您使用儲存庫瀏覽器

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