VirtualBox

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

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

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

© 2023 Oracle
Contact – Privacy policy – Terms of Use