Changeset 16237 in vbox

Timestamp:

Jan 26, 2009 3:06:34 PM (16 years ago)

Author:

vboxsync

Message:

OVF: add separate IAppliance::interpret() method, API docs

Location:

trunk/src/VBox/Main

Files:

• ApplianceImpl.cpp (modified) (2 diffs)
• idl/VirtualBox.xidl (modified) (2 diffs)
• include/ApplianceImpl.h (modified) (4 diffs)

trunk/src/VBox/Main/ApplianceImpl.cpp

@@ -808 +808 @@
     }
 
-    rc = construeAppliance();
-    if (FAILED(rc))
-        return rc;
-
     /* Confirm a successful initialization */
     autoInitSpan.setSucceeded();
@@ -1017 +1013 @@
 }
 
-HRESULT Appliance::construeAppliance()
+STDMETHODIMP Appliance::Interpret()
 {
     // @todo:

trunk/src/VBox/Main/idl/VirtualBox.xidl

@@ -2882 +2882 @@
         <link to="IVirtualBox::openAppliance" />.
 
-        Opening an appliance is a two-step process with VirtualBox: first
+        Opening an appliance is a three-step process with VirtualBox: first
         <link to="IVirtualBox::openAppliance" /> is called, which succeeds if the
         appliance file is syntactically valid, irrespective of whether VirtualBox
         can handle the appliance.
 
-        Once that method has returned an IAppliance instance, one can inspect the
-        member data of that instance to determine whether VirtualBox can handle
-        the requirements of that appliance and create local virtual machines
-        accordingly.
+        As a second step, the caller should then invoke <link to="IAppliance::interpret" />,
+        which analyzes the OVF data and sets up the contents of the IAppliance attributes
+        accordingly. These can be inspected by a VirtualBox front-end such as the GUI,
+        and the suggestions can be displayed to the user. For example, the virtual system
+        will contain the virtual hardware prescribed by the OVF (network and hardware
+        adapters, virtual disk images, memory size and so on), and the GUI can then give
+        the user the option to confirm and/or change these suggestions.
+
+        As a third step, the caller should invoke <link to="#Import" />, which will create
+        virtual machines in VirtualBox as instances of <link to="IMachine" /> that match the
+        information in the virtual system descriptions.
     </desc>
 
@@ -2899 +2906 @@
 
     <attribute name="virtualSystemDescriptions" type="IVirtualSystemDescription" readonly="yes" safearray="yes">
-      <desc></desc>
-    </attribute>
+      <desc>
+      Array of virtual system descriptions. One such description gets created by
+      <link to="#interpret" /> for each virtual system found in the OVF.
+      </desc>
+    </attribute>
+
+    <method name="interpret">
+      <desc>
+        Interprets the OVF data that was read when the appliance was constructed. After
+        calling this method, one can call
+        <link to="#getDisks" /> to retrieve disk information and also inspect the
+        <link to="#virtualSystemDescriptions" /> array attribute, which will then contain
+        one <link to="IVirtualSystemDescription" /> for each virtual machine found in
+        the appliance.
+      </desc>
+    </method>
 
     <method name="getDisks">

trunk/src/VBox/Main/include/ApplianceImpl.h

@@ -57 +57 @@
     void FinalRelease() { uninit(); }
 
-    HRESULT init (VirtualBox *aVirtualBox, IN_BSTR &path);
+    HRESULT init(VirtualBox *aVirtualBox, IN_BSTR &path);
     void uninit();
 
@@ -64 +64 @@
 
     /* IAppliance properties */
-    STDMETHOD(COMGETTER(Path)) (BSTR *aPath);
+    STDMETHOD(COMGETTER(Path))(BSTR *aPath);
+
+    STDMETHOD(COMGETTER(VirtualSystemDescriptions))(ComSafeArrayOut (IVirtualSystemDescription*, aVirtualSystemDescriptions));
 
     /* IAppliance methods */
+    /* void interpret (); */
+    STDMETHOD(Interpret)(void);
+
     /* void getDisks (out unsigned long aDisksSize, [array, size_is (aDisksSize)] out wstring aDisks, [retval] out unsigned long cDisks); */
-    STDMETHOD(GetDisks) (ComSafeArrayOut(BSTR, aDisks), ULONG *cDisks);
-
-    STDMETHOD (COMGETTER (VirtualSystemDescriptions)) (ComSafeArrayOut (IVirtualSystemDescription*, aVirtualSystemDescriptions));
+    STDMETHOD(GetDisks)(ComSafeArrayOut(BSTR, aDisks), ULONG *cDisks);
 
     /* public methods only for internal purposes */
-    STDMETHOD (ImportAppliance)();
+    STDMETHOD(ImportAppliance)();
 
     /* private instance data */
@@ -88 +91 @@
     HRESULT HandleVirtualSystemContent(const char *pcszPath, const xml::Node *pContentElem);
 
-    HRESULT construeAppliance();
     HRESULT searchUniqueVMName (std::string& aName);
 };
@@ -151 +153 @@
     /* private instance data */
 private:
-    void addEntry (VirtualSystemDescriptionType_T aType, ULONG aRef, std::string aOrigValue, std::string aAutoValue);
-    std::list<VirtualSystemDescriptionEntry> findByType (VirtualSystemDescriptionType_T aType);
+    void addEntry(VirtualSystemDescriptionType_T aType, ULONG aRef, std::string aOrigValue, std::string aAutoValue);
+    std::list<VirtualSystemDescriptionEntry> findByType(VirtualSystemDescriptionType_T aType);
 
     struct Data;