VirtualBox

source: vbox/trunk/src/VBox/Main/include/ovfreader.h@ 46284

Last change on this file since 46284 was 46169, checked in by vboxsync, 12 years ago

Changes in parsing, extracting and processing an OVF version in/from a XML file in the OVF package.
  • Property svn:eol-style set to native
  • Property svn:keywords set to Author Date Id Revision
File size: 20.2 KB
Line 
1/* $Id: ovfreader.h 46169 2013-05-20 07:57:55Z vboxsync $ */
2/** @file
3 * VirtualBox Main - OVF reader declarations.
4 *
5 * Depends only on IPRT, including the RTCString and IPRT XML classes.
6 */
7
8/*
9 * Copyright (C) 2008-2011 Oracle Corporation
10 *
11 * This file is part of VirtualBox Open Source Edition (OSE), as
12 * available from http://www.virtualbox.org. This file is free software;
13 * you can redistribute it and/or modify it under the terms of the GNU
14 * General Public License (GPL) as published by the Free Software
15 * Foundation, in version 2 as it comes in the "COPYING" file of the
16 * VirtualBox OSE distribution. VirtualBox OSE is distributed in the
17 * hope that it will be useful, but WITHOUT ANY WARRANTY of any kind.
18 */
19
20#ifndef ____H_OVFREADER
21#define ____H_OVFREADER
22
23#include "iprt/cpp/xml.h"
24#include <map>
25
26namespace ovf
27{
28
29////////////////////////////////////////////////////////////////////////////////
30//
31// Enumerations
32//
33////////////////////////////////////////////////////////////////////////////////
34
35/**
36 * CIM OS values.
37 *
38 * The OVF 1.10 spec refers to some CIM_OperatingSystem.mof doc. Could this be it:
39 * http://cvs.opengroup.org/cgi-bin/cvsweb.cgi/pegasus/Schemas/CIM231/DMTF/System/CIM_OperatingSystem.mof
40 *
41 * @todo r=bird: Why are the values are repeating 'CIMOS'. CIMOSType_T is also
42 * repeating it self, 'Type' and '_T'. Why not call it kCIOMOpSys,
43 * easier to read as well.
44 * Then also apply: s/CIMOSType_CIMOS_/kCIMOpSys_/g
45 */
46enum CIMOSType_T
47{
48 CIMOSType_CIMOS_Unknown = 0,
49 CIMOSType_CIMOS_Other = 1,
50 CIMOSType_CIMOS_MACOS = 2,
51 CIMOSType_CIMOS_ATTUNIX = 3,
52 CIMOSType_CIMOS_DGUX = 4,
53 CIMOSType_CIMOS_DECNT = 5,
54 CIMOSType_CIMOS_Tru64UNIX = 6,
55 CIMOSType_CIMOS_OpenVMS = 7,
56 CIMOSType_CIMOS_HPUX = 8,
57 CIMOSType_CIMOS_AIX = 9,
58 CIMOSType_CIMOS_MVS = 10,
59 CIMOSType_CIMOS_OS400 = 11,
60 CIMOSType_CIMOS_OS2 = 12,
61 CIMOSType_CIMOS_JavaVM = 13,
62 CIMOSType_CIMOS_MSDOS = 14,
63 CIMOSType_CIMOS_WIN3x = 15,
64 CIMOSType_CIMOS_WIN95 = 16,
65 CIMOSType_CIMOS_WIN98 = 17,
66 CIMOSType_CIMOS_WINNT = 18,
67 CIMOSType_CIMOS_WINCE = 19,
68 CIMOSType_CIMOS_NCR3000 = 20,
69 CIMOSType_CIMOS_NetWare = 21,
70 CIMOSType_CIMOS_OSF = 22,
71 CIMOSType_CIMOS_DCOS = 23,
72 CIMOSType_CIMOS_ReliantUNIX = 24,
73 CIMOSType_CIMOS_SCOUnixWare = 25,
74 CIMOSType_CIMOS_SCOOpenServer = 26,
75 CIMOSType_CIMOS_Sequent = 27,
76 CIMOSType_CIMOS_IRIX = 28,
77 CIMOSType_CIMOS_Solaris = 29,
78 CIMOSType_CIMOS_SunOS = 30,
79 CIMOSType_CIMOS_U6000 = 31,
80 CIMOSType_CIMOS_ASERIES = 32,
81 CIMOSType_CIMOS_HPNonStopOS = 33,
82 CIMOSType_CIMOS_HPNonStopOSS = 34,
83 CIMOSType_CIMOS_BS2000 = 35,
84 CIMOSType_CIMOS_LINUX = 36,
85 CIMOSType_CIMOS_Lynx = 37,
86 CIMOSType_CIMOS_XENIX = 38,
87 CIMOSType_CIMOS_VM = 39,
88 CIMOSType_CIMOS_InteractiveUNIX = 40,
89 CIMOSType_CIMOS_BSDUNIX = 41,
90 CIMOSType_CIMOS_FreeBSD = 42,
91 CIMOSType_CIMOS_NetBSD = 43,
92 CIMOSType_CIMOS_GNUHurd = 44,
93 CIMOSType_CIMOS_OS9 = 45,
94 CIMOSType_CIMOS_MACHKernel = 46,
95 CIMOSType_CIMOS_Inferno = 47,
96 CIMOSType_CIMOS_QNX = 48,
97 CIMOSType_CIMOS_EPOC = 49,
98 CIMOSType_CIMOS_IxWorks = 50,
99 CIMOSType_CIMOS_VxWorks = 51,
100 CIMOSType_CIMOS_MiNT = 52,
101 CIMOSType_CIMOS_BeOS = 53,
102 CIMOSType_CIMOS_HPMPE = 54,
103 CIMOSType_CIMOS_NextStep = 55,
104 CIMOSType_CIMOS_PalmPilot = 56,
105 CIMOSType_CIMOS_Rhapsody = 57,
106 CIMOSType_CIMOS_Windows2000 = 58,
107 CIMOSType_CIMOS_Dedicated = 59,
108 CIMOSType_CIMOS_OS390 = 60,
109 CIMOSType_CIMOS_VSE = 61,
110 CIMOSType_CIMOS_TPF = 62,
111 CIMOSType_CIMOS_WindowsMe = 63,
112 CIMOSType_CIMOS_CalderaOpenUNIX = 64,
113 CIMOSType_CIMOS_OpenBSD = 65,
114 CIMOSType_CIMOS_NotApplicable = 66,
115 CIMOSType_CIMOS_WindowsXP = 67,
116 CIMOSType_CIMOS_zOS = 68,
117 CIMOSType_CIMOS_MicrosoftWindowsServer2003 = 69,
118 CIMOSType_CIMOS_MicrosoftWindowsServer2003_64 = 70,
119 CIMOSType_CIMOS_WindowsXP_64 = 71,
120 CIMOSType_CIMOS_WindowsXPEmbedded = 72,
121 CIMOSType_CIMOS_WindowsVista = 73,
122 CIMOSType_CIMOS_WindowsVista_64 = 74,
123 CIMOSType_CIMOS_WindowsEmbeddedforPointofService = 75,
124 CIMOSType_CIMOS_MicrosoftWindowsServer2008 = 76,
125 CIMOSType_CIMOS_MicrosoftWindowsServer2008_64 = 77,
126 CIMOSType_CIMOS_FreeBSD_64 = 78,
127 CIMOSType_CIMOS_RedHatEnterpriseLinux = 79,
128 CIMOSType_CIMOS_RedHatEnterpriseLinux_64 = 80,
129 CIMOSType_CIMOS_Solaris_64 = 81,
130 CIMOSType_CIMOS_SUSE = 82,
131 CIMOSType_CIMOS_SUSE_64 = 83,
132 CIMOSType_CIMOS_SLES = 84,
133 CIMOSType_CIMOS_SLES_64 = 85,
134 CIMOSType_CIMOS_NovellOES = 86,
135 CIMOSType_CIMOS_NovellLinuxDesktop = 87,
136 CIMOSType_CIMOS_SunJavaDesktopSystem = 88,
137 CIMOSType_CIMOS_Mandriva = 89,
138 CIMOSType_CIMOS_Mandriva_64 = 90,
139 CIMOSType_CIMOS_TurboLinux = 91,
140 CIMOSType_CIMOS_TurboLinux_64 = 92,
141 CIMOSType_CIMOS_Ubuntu = 93,
142 CIMOSType_CIMOS_Ubuntu_64 = 94,
143 CIMOSType_CIMOS_Debian = 95,
144 CIMOSType_CIMOS_Debian_64 = 96,
145 CIMOSType_CIMOS_Linux_2_4_x = 97,
146 CIMOSType_CIMOS_Linux_2_4_x_64 = 98,
147 CIMOSType_CIMOS_Linux_2_6_x = 99,
148 CIMOSType_CIMOS_Linux_2_6_x_64 = 100,
149 CIMOSType_CIMOS_Linux_64 = 101,
150 CIMOSType_CIMOS_Other_64 = 102,
151 // types added with CIM 2.25.0 follow:
152 CIMOSType_CIMOS_WindowsServer2008R2 = 103,
153 CIMOSType_CIMOS_VMwareESXi = 104,
154 CIMOSType_CIMOS_Windows7 = 105,
155 CIMOSType_CIMOS_CentOS = 106,
156 CIMOSType_CIMOS_CentOS_64 = 107,
157 CIMOSType_CIMOS_OracleEnterpriseLinux = 108,
158 CIMOSType_CIMOS_OracleEnterpriseLinux_64 = 109,
159 CIMOSType_CIMOS_eComStation = 110
160 // no new types added with CIM 2.26.0
161};
162
163enum OVFVersion_T
164{
165 OVFVersion_unknown,
166 OVFVersion_0_9,
167 OVFVersion_1_0,
168 OVFVersion_2_0
169};
170
171const char* const OVF09_URI_string = "http://www.vmware.com/schema/ovf/1/envelope";
172const char* const OVF10_URI_string = "http://schemas.dmtf.org/ovf/envelope/1";
173const char* const OVF20_URI_string = "http://schemas.dmtf.org/ovf/envelope/2";
174
175////////////////////////////////////////////////////////////////////////////////
176//
177// Envelope data
178//
179////////////////////////////////////////////////////////////////////////////////
180struct EnvelopeData
181{
182 OVFVersion_T version;//OVF standard version, it is used internally only by VirtualBox
183 RTCString lang;//language
184
185 OVFVersion_T getOVFVersion() const
186 {
187 return version;
188 }
189
190
191 RTCString getStringOVFVersion() const
192 {
193 if (version == OVFVersion_0_9)
194 return "0.9";
195 else if (version == OVFVersion_1_0)
196 return "1.0";
197 else if (version == OVFVersion_2_0)
198 return "2.0";
199 else
200 return "";
201 }
202
203 void setOVFVersion(OVFVersion_T v)
204 {
205 version = v;
206 }
207};
208
209////////////////////////////////////////////////////////////////////////////////
210//
211// Hardware definition structs
212//
213////////////////////////////////////////////////////////////////////////////////
214
215struct DiskImage
216{
217 // fields from /DiskSection/Disk
218 RTCString strDiskId; // value from DiskSection/Disk/@diskId
219 int64_t iCapacity; // value from DiskSection/Disk/@capacity;
220 // (maximum size for dynamic images, I guess; we always translate this to bytes)
221 int64_t iPopulatedSize; // optional value from DiskSection/Disk/@populatedSize
222 // (actual used size of disk, always in bytes; can be an estimate of used disk
223 // space, but cannot be larger than iCapacity; -1 if not set)
224 RTCString strFormat; // value from DiskSection/Disk/@format
225 // typically http://www.vmware.com/interfaces/specifications/vmdk.html#streamOptimized
226 RTCString uuidVbox; // optional; if the file was exported by VirtualBox >= 3.2,
227 // then this has the UUID with which the disk was registered
228
229 // fields from /References/File; the spec says the file reference from disk can be empty,
230 // so in that case, strFilename will be empty, then a new disk should be created
231 RTCString strHref; // value from /References/File/@href (filename); if empty, then the remaining fields are ignored
232 int64_t iSize; // value from /References/File/@size (optional according to spec; then we set -1 here)
233 int64_t iChunkSize; // value from /References/File/@chunkSize (optional, unsupported)
234 RTCString strCompression; // value from /References/File/@compression (optional, can be "gzip" according to spec)
235
236 // additional field which has a descriptive size in megabytes derived from the above; this can be used for progress reports
237 uint32_t ulSuggestedSizeMB;
238};
239
240enum ResourceType_T
241{ ResourceType_Other = 1,
242 ResourceType_ComputerSystem = 2,
243 ResourceType_Processor = 3,
244 ResourceType_Memory = 4,
245 ResourceType_IDEController = 5,
246 ResourceType_ParallelSCSIHBA = 6,
247 ResourceType_FCHBA = 7,
248 ResourceType_iSCSIHBA = 8,
249 ResourceType_IBHCA = 9,
250 ResourceType_EthernetAdapter = 10,
251 ResourceType_OtherNetworkAdapter = 11,
252 ResourceType_IOSlot = 12,
253 ResourceType_IODevice = 13,
254 ResourceType_FloppyDrive = 14,
255 ResourceType_CDDrive = 15,
256 ResourceType_DVDDrive = 16,
257 ResourceType_HardDisk = 17,
258 ResourceType_OtherStorageDevice = 20,
259 ResourceType_USBController = 23,
260 ResourceType_SoundCard = 35
261};
262
263struct VirtualHardwareItem
264{
265 RTCString strDescription;
266 RTCString strCaption;
267 RTCString strElementName;
268
269 uint32_t ulInstanceID;
270 uint32_t ulParent;
271
272 ResourceType_T resourceType;
273 RTCString strOtherResourceType;
274 RTCString strResourceSubType;
275 bool fResourceRequired;
276
277 RTCString strHostResource; // "Abstractly specifies how a device shall connect to a resource on the deployment platform.
278 // Not all devices need a backing." Used with disk items, for which this references a virtual
279 // disk from the Disks section.
280 bool fAutomaticAllocation;
281 bool fAutomaticDeallocation;
282 RTCString strConnection; // "All Ethernet adapters that specify the same abstract network connection name within an OVF
283 // package shall be deployed on the same network. The abstract network connection name shall be
284 // listed in the NetworkSection at the outermost envelope level." We ignore this and only set up
285 // a network adapter depending on the network name.
286 RTCString strAddress; // "Device-specific. For an Ethernet adapter, this specifies the MAC address."
287 int32_t lAddress; // strAddress as an integer, if applicable.
288 RTCString strAddressOnParent; // "For a device, this specifies its location on the controller."
289 RTCString strAllocationUnits; // "Specifies the units of allocation used. For example, “byte * 2^20”."
290 uint64_t ullVirtualQuantity; // "Specifies the quantity of resources presented. For example, “256”."
291 uint64_t ullReservation; // "Specifies the minimum quantity of resources guaranteed to be available."
292 uint64_t ullLimit; // "Specifies the maximum quantity of resources that will be granted."
293 uint64_t ullWeight; // "Specifies a relative priority for this allocation in relation to other allocations."
294
295 RTCString strConsumerVisibility;
296 RTCString strMappingBehavior;
297 RTCString strPoolID;
298 uint32_t ulBusNumber; // seen with IDE controllers, but not listed in OVF spec
299
300 uint32_t ulLineNumber; // line number of <Item> element in XML source; cached for error messages
301
302 VirtualHardwareItem()
303 : ulInstanceID(0),
304 fAutomaticAllocation(false),
305 fAutomaticDeallocation(false),
306 ullVirtualQuantity(0),
307 ullReservation(0),
308 ullLimit(0),
309 ullWeight(0),
310 ulBusNumber(0),
311 ulLineNumber(0)
312 {};
313};
314
315typedef std::map<RTCString, DiskImage> DiskImagesMap;
316
317struct VirtualSystem;
318
319typedef std::map<uint32_t, VirtualHardwareItem> HardwareItemsMap;
320
321struct HardDiskController
322{
323 uint32_t idController; // instance ID (Item/InstanceId); this gets referenced from VirtualDisk
324
325 enum ControllerSystemType { IDE, SATA, SCSI };
326 ControllerSystemType system; // one of IDE, SATA, SCSI
327
328 RTCString strControllerType;
329 // controller subtype (Item/ResourceSubType); e.g. "LsiLogic"; can be empty (esp. for IDE)
330 // note that we treat LsiLogicSAS as a SCSI controller (system == SCSI) even though VirtualBox
331 // treats it as a fourth class besides IDE, SATA, SCSI
332
333 int32_t lAddress; // value from OVF "Address" element
334 bool fPrimary; // controller index; this is determined heuristically by the OVF reader and will
335 // be true for the first controller of this type (e.g. IDE primary ctler) or
336 // false for the next (e.g. IDE secondary ctler)
337
338 HardDiskController()
339 : idController(0),
340 lAddress(0),
341 fPrimary(true)
342 { }
343};
344
345typedef std::map<uint32_t, HardDiskController> ControllersMap;
346
347struct VirtualDisk
348{
349 uint32_t idController;// SCSI (or IDE) controller this disk is connected to;
350 // this must match HardDiskController.idController and
351 // points into VirtualSystem.mapControllers
352 uint32_t ulAddressOnParent;// parsed strAddressOnParent of hardware item; will be 0 or 1 for IDE
353 // and possibly higher for disks attached to SCSI controllers (untested)
354 RTCString strDiskId;// if the hard disk has an ovf:/disk/<id> reference,
355 // this receives the <id> component; points to one of the
356 // references in Appliance::Data.mapDisks
357 bool fEmpty;//true - empty disk, e.g. the component <rasd:HostResource>...</rasd:HostResource> is absent.
358};
359
360typedef std::map<RTCString, VirtualDisk> VirtualDisksMap;
361
362/**
363 * A list of EthernetAdapters is contained in VirtualSystem, representing the
364 * ethernet adapters in the virtual system.
365 */
366struct EthernetAdapter
367{
368 RTCString strAdapterType; // "PCNet32" or "E1000" or whatever; from <rasd:ResourceSubType>
369 RTCString strNetworkName; // from <rasd:Connection>
370};
371
372typedef std::list<EthernetAdapter> EthernetAdaptersList;
373
374/**
375 * A list of VirtualSystem structs is created by OVFReader::read(). Each refers to
376 * a <VirtualSystem> block in the OVF file.
377 */
378struct VirtualSystem
379{
380 RTCString strName; // copy of VirtualSystem/@id
381
382 RTCString strDescription; // copy of VirtualSystem/AnnotationSection content, if any
383
384 CIMOSType_T cimos;
385 RTCString strCimosDesc; // readable description of the cimos type in the case of cimos = 0/1/102
386 RTCString strTypeVbox; // optional type from @vbox:ostype attribute (VirtualBox 4.0 or higher)
387
388 RTCString strVirtualSystemType; // generic hardware description; OVF says this can be something like "vmx-4" or "xen";
389 // VMware Workstation 6.5 is "vmx-07"
390
391 HardwareItemsMap mapHardwareItems; // map of virtual hardware items, sorted by unique instance ID
392
393 uint64_t ullMemorySize; // always in bytes, copied from llHardwareItems; default = 0 (unspecified)
394 uint16_t cCPUs; // no. of CPUs, copied from llHardwareItems; default = 1
395
396 EthernetAdaptersList llEthernetAdapters; // (one for each VirtualSystem/Item[@ResourceType=10]element)
397
398 ControllersMap mapControllers;
399 // list of hard disk controllers
400 // (one for each VirtualSystem/Item[@ResourceType=6] element with accumulated data from children)
401
402 VirtualDisksMap mapVirtualDisks;
403 // (one for each VirtualSystem/Item[@ResourceType=17] element with accumulated data from children)
404
405 bool fHasFloppyDrive; // true if there's a floppy item in mapHardwareItems
406 bool fHasCdromDrive; // true if there's a CD-ROM item in mapHardwareItems; ISO images are not yet supported by OVFtool
407 bool fHasUsbController; // true if there's a USB controller item in mapHardwareItems
408
409 RTCString strSoundCardType; // if not empty, then the system wants a soundcard; this then specifies the hardware;
410 // VMware Workstation 6.5 uses "ensoniq1371" for example
411
412 RTCString strLicenseText; // license info if any; receives contents of VirtualSystem/EulaSection/License
413
414 RTCString strProduct; // product info if any; receives contents of VirtualSystem/ProductSection/Product
415 RTCString strVendor; // product info if any; receives contents of VirtualSystem/ProductSection/Vendor
416 RTCString strVersion; // product info if any; receives contents of VirtualSystem/ProductSection/Version
417 RTCString strProductUrl; // product info if any; receives contents of VirtualSystem/ProductSection/ProductUrl
418 RTCString strVendorUrl; // product info if any; receives contents of VirtualSystem/ProductSection/VendorUrl
419
420 const xml::ElementNode // pointer to <vbox:Machine> element under <VirtualSystem> element or NULL if not present
421 *pelmVboxMachine;
422
423 VirtualSystem()
424 : cimos(CIMOSType_CIMOS_Unknown),
425 ullMemorySize(0),
426 cCPUs(1),
427 fHasFloppyDrive(false),
428 fHasCdromDrive(false),
429 fHasUsbController(false),
430 pelmVboxMachine(NULL)
431 {
432 }
433};
434
435////////////////////////////////////////////////////////////////////////////////
436//
437// Class OVFReader
438//
439////////////////////////////////////////////////////////////////////////////////
440
441/**
442 * OVFReader attempts to open, read in and parse an OVF XML file. This is all done
443 * in the constructor; if there is any kind of error in the file -- filesystem error
444 * from IPRT, XML parsing errors from libxml, or OVF logical errors --, exceptions
445 * are thrown. These are all based on xml::Error.
446 *
447 * Hence, use this class as follows:
448<code>
449 OVFReader *pReader = NULL;
450 try
451 {
452 pReader = new("/path/to/file.ovf");
453 }
454 catch (xml::Error &e)
455 {
456 printf("A terrible thing happened: %s", e.what());
457 }
458 // now go look at pReader->m_llVirtualSystem and what's in there
459 if (pReader)
460 delete pReader;
461</code>
462 */
463
464class OVFReader
465{
466public:
467 OVFReader(const void *pvBuf, size_t cbSize, const RTCString &path);
468 OVFReader(const RTCString &path);
469
470 // Data fields
471 EnvelopeData m_envelopeData; //data of root element "Envelope"
472 RTCString m_strPath; // file name given to constructor
473 DiskImagesMap m_mapDisks; // map of DiskImage structs, sorted by DiskImage.strDiskId
474 std::list<VirtualSystem> m_llVirtualSystems; // list of virtual systems, created by and valid after read()
475
476private:
477 xml::Document m_doc;
478
479 void parse();
480 void LoopThruSections(const xml::ElementNode *pReferencesElem, const xml::ElementNode *pCurElem);
481 void HandleDiskSection(const xml::ElementNode *pReferencesElem, const xml::ElementNode *pSectionElem);
482 void HandleNetworkSection(const xml::ElementNode *pSectionElem);
483 void HandleVirtualSystemContent(const xml::ElementNode *pContentElem);
484};
485
486////////////////////////////////////////////////////////////////////////////////
487//
488// Errors
489//
490////////////////////////////////////////////////////////////////////////////////
491
492/**
493 * Thrown by OVFReader for any kind of error that is not an XML error but
494 * still makes the OVF impossible to parse. Based on xml::LogicError so
495 * that one catch() for all xml::LogicError can handle all possible errors.
496 */
497
498class OVFLogicError : public xml::LogicError
499{
500public:
501 OVFLogicError(const char *aFormat, ...);
502};
503
504} // end namespace ovf
505
506#endif // !____H_OVFREADER
507
Note: See TracBrowser for help on using the repository browser.

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