Changeset 17033 in vbox for trunk

Timestamp:

Feb 23, 2009 8:12:10 PM (16 years ago)

Author:

vboxsync

svn:sync-xref-src-repo-rev:

43246

Message:

OVF: prototypes for export.

Location:

trunk/src/VBox

Files:

• Frontends/VBoxManage/VBoxManage.cpp (modified) (2 diffs)
• Frontends/VBoxManage/VBoxManage.h (modified) (2 diffs)
• Frontends/VBoxManage/VBoxManageImport.cpp (modified) (5 diffs)
• Main/ApplianceImpl.cpp (modified) (4 diffs)
• Main/idl/VirtualBox.xidl (modified) (8 diffs)
• Main/include/ApplianceImpl.h (modified) (1 diff)
• Main/include/MachineImpl.h (modified) (2 diffs)

trunk/src/VBox/Frontends/VBoxManage/VBoxManage.cpp

@@ -315 +315 @@
     {
         RTPrintf("VBoxManage import           <ovf>\n"
+                 "\n"); // @todo
+    }
+
+    if (u64Cmd & USAGE_EXPORTAPPLIANCE)
+    {
+        RTPrintf("VBoxManage export           <machines> -o <ovf>\n"
                  "\n");
     }
@@ -3007 +3013 @@
         { "metrics",          handleMetrics },
         { "import",           handleImportAppliance },
+        { "export",           handleExportAppliance },
         { NULL,               NULL }
     };

trunk/src/VBox/Frontends/VBoxManage/VBoxManage.h

@@ -87 +87 @@
 #define USAGE_CONVERTHD             RT_BIT_64(43)
 #define USAGE_IMPORTAPPLIANCE       RT_BIT_64(44)
+#define USAGE_EXPORTAPPLIANCE       RT_BIT_64(45)
 #define USAGE_ALL                   (~(uint64_t)0)
 /** @} */
@@ -170 +171 @@
 // VBoxManageImport.cpp
 int handleImportAppliance(HandlerArg *a);
+int handleExportAppliance(HandlerArg *a);
 
 /* VBoxManageUSB.cpp */

trunk/src/VBox/Frontends/VBoxManage/VBoxManageImport.cpp

@@ -98 +98 @@
         Utf8Str strThisArg(a->argv[i]);
         if (    (strThisArg == "--dry-run")
+             || (strThisArg == "-dry-run")
              || (strThisArg == "-n")
            )
@@ -156 +157 @@
     {
         Bstr bstrOvfFilename(strOvfFilename);
-        ComPtr<IAppliance> appliance;
-        CHECK_ERROR_BREAK(a->virtualBox, CreateAppliance(appliance.asOutParam()));
-
-        CHECK_ERROR_BREAK(appliance, Read(bstrOvfFilename));
+        ComPtr<IAppliance> pAppliance;
+        CHECK_ERROR_BREAK(a->virtualBox, CreateAppliance(pAppliance.asOutParam()));
+
+        CHECK_ERROR_BREAK(pAppliance, Read(bstrOvfFilename));
 
         RTPrintf("Interpreting %s... ", strOvfFilename.c_str());
-        CHECK_ERROR_BREAK(appliance, Interpret());
+        CHECK_ERROR_BREAK(pAppliance, Interpret());
         RTPrintf("OK.\n");
 
         // fetch all disks
         com::SafeArray<BSTR> retDisks;
-        CHECK_ERROR_BREAK(appliance,
+        CHECK_ERROR_BREAK(pAppliance,
                           COMGETTER(Disks)(ComSafeArrayAsOutParam(retDisks)));
         if (retDisks.size() > 0)
@@ -179 +180 @@
         // fetch virtual system descriptions
         com::SafeIfaceArray<IVirtualSystemDescription> aVirtualSystemDescriptions;
-        CHECK_ERROR_BREAK(appliance,
+        CHECK_ERROR_BREAK(pAppliance,
                           COMGETTER(VirtualSystemDescriptions)(ComSafeArrayAsOutParam(aVirtualSystemDescriptions)));
 
@@ -469 +470 @@
             {
                 ComPtr<IProgress> progress;
-                CHECK_ERROR_BREAK(appliance,
+                CHECK_ERROR_BREAK(pAppliance,
                                   ImportMachines(progress.asOutParam()));
 
@@ -492 +493 @@
 }
 
+int handleExportAppliance(HandlerArg *a)
+{
+    HRESULT rc = S_OK;
+
+    Utf8Str strOutputFile;
+    std::list< ComPtr<IMachine> > llMachines;
+
+    do
+    {
+        for (int i = 0;
+            i < a->argc;
+            ++i)
+        {
+            Utf8Str strThisArg(a->argv[i]);
+
+            if (    strThisArg == "--output"
+                || strThisArg == "-output"
+                || strThisArg == "-o"
+            )
+            {
+                if (++i < a->argc)
+                {
+                    if (strOutputFile.length())
+                        return errorSyntax(USAGE_EXPORTAPPLIANCE, "You can only specify --output once.");
+                    else
+                        strOutputFile = strThisArg;
+                }
+                else
+                    return errorSyntax(USAGE_EXPORTAPPLIANCE, "Missing argument to --output option.");
+            }
+            else
+            {
+                // must be machine: try UUID or name
+                ComPtr<IMachine> machine;
+                /* assume it's a UUID */
+                rc = a->virtualBox->GetMachine(Guid(strThisArg), machine.asOutParam());
+                if (FAILED(rc) || !machine)
+                {
+                    /* must be a name */
+                    CHECK_ERROR_BREAK(a->virtualBox, FindMachine(Bstr(strThisArg), machine.asOutParam()));
+                }
+
+                if (machine)
+                    llMachines.push_back(machine);
+            }
+        }
+
+        if (llMachines.size() == 0)
+            return errorSyntax(USAGE_EXPORTAPPLIANCE, "Missing arguments to export command.");
+
+        ComPtr<IAppliance> pAppliance;
+        CHECK_ERROR_BREAK(a->virtualBox, CreateAppliance(pAppliance.asOutParam()));
+
+        std::list< ComPtr<IMachine> >::iterator itM;
+        for (itM = llMachines.begin();
+             itM != llMachines.end();
+             ++itM)
+        {
+            ComPtr<IMachine> pMachine = *itM;
+            CHECK_ERROR_BREAK(pMachine, Export(pAppliance));
+        }
+
+        if (FAILED(rc))
+            break;
+
+        CHECK_ERROR_BREAK(pAppliance, Write(Bstr(strOutputFile)));
+
+    } while (0);
+
+    return SUCCEEDED(rc) ? 0 : 1;
+}
+
 #endif /* !VBOX_ONLY_DOCS */

trunk/src/VBox/Main/ApplianceImpl.cpp

@@ -2 +2 @@
 /** @file
  *
- * IAppliance and IVirtualSystem COM class implementations
+ * IAppliance and IVirtualSystem COM class implementations.
  */
 
@@ -30 +30 @@
 #include "GuestOSTypeImpl.h"
 #include "ProgressImpl.h"
+#include "MachineImpl.h"
 
 #include "Logging.h"
@@ -1609 +1610 @@
 }
 
+STDMETHODIMP Appliance::Write(IN_BSTR path)
+{
+    HRESULT rc = S_OK;
+    return rc;
+}
+
 HRESULT Appliance::searchUniqueVMName(Utf8Str& aName) const
 {
@@ -2498 +2505 @@
 }
 
+STDMETHODIMP Machine::Export(IAppliance *appliance)
+{
+    HRESULT rc = S_OK;
+    return rc;
+}

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

@@ -1731 +1731 @@
       <desc>
         Creates a new appliance object, which represents an appliance in the Open Virtual Machine
-        Format (OVF). This can then be used to import an OVF appliance into VirtualBox; see the
-        documentation for <link to="IAppliance" /> for details.
+        Format (OVF). This can then be used to import an OVF appliance into VirtualBox or to export
+        machines as an OVF appliance; see the documentation for <link to="IAppliance" /> for details.
       </desc>
       <param name="appliance" type="IAppliance" dir="return">
@@ -2854 +2854 @@
      >
     <desc>
-        Represents an appliance in OVF format. An instance of this is returned by
-        <link to="IVirtualBox::createAppliance" />.
-
-        Importing an OVF appliance into VirtualBox involves the following sequence
-        of API calls:
+        Represents a platform-independent appliance in OVF format. An instance of this is returned
+        by <link to="IVirtualBox::createAppliance" />, which can then be used to import and export
+        appliances with VirtualBox.
+
+        The OVF standard suggests two different physical file formats:
 
         <ol>
-          <li>
-          Call <link to="IVirtualBox::createAppliance" />. This will create an empty IAppliance object.
+            <li>If the OVF is distributed as a set of files, then @a file must be a fully qualified
+                path name to an existing OVF descriptor file with an <tt>.ovf</tt> file extension. If
+                this descriptor file references other files, as OVF appliances distributed as a set of
+                files most likely do, those files must be in the same directory as the descriptor file.</li>
+
+            <li>If the OVF is distributed as a single file, it must be in TAR format and have the
+                <tt>.ova</tt> file extension. This TAR file must then contain at least the OVF descriptor
+                files and optionally other files.
+
+                At this time, VirtualBox does not not yet support the packed (TAR) variant; support will
+                be added with a later version.</li>
+        </ol>
+
+        <b>Importing</b> an OVF appliance into VirtualBox as instances of
+        <link to="IMachine" /> involves the following sequence of API calls:
+
+        <ol>
+          <li>Call <link to="IVirtualBox::createAppliance" />. This will create an empty IAppliance object.
           </li>
 
-          <li>
-          On the new object, call <link to="#read" /> with the full path of the OVF file you
-          would like to import. So long as this file is syntactically valid, this will succeed
-          and return an instance of IAppliance that contains the parsed data from the OVF file.
+          <li>On the new object, call <link to="#read" /> with the full path of the OVF file you
+              would like to import. So long as this file is syntactically valid, this will succeed
+              and return an instance of IAppliance that contains the parsed data from the OVF file.
           </li>
 
           <li>Next, call <link to="#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. In particular, the <link to="#virtualSystemDescriptions" /> array contains
-          instances of <link to="IVirtualSystemDescription" /> which represent the virtual
-          systems in the OVF, which in turn describe the virtual hardware prescribed
-          by the OVF (network and hardware adapters, virtual disk images, memory size and so on).
-          The GUI can then give the user the option to confirm and/or change these suggestions.
+              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. In particular, the <link to="#virtualSystemDescriptions" /> array contains
+              instances of <link to="IVirtualSystemDescription" /> which represent the virtual
+              systems in the OVF, which in turn describe the virtual hardware prescribed by the
+              OVF (network and hardware adapters, virtual disk images, memory size and so on).
+              The GUI can then give the user the option to confirm and/or change these suggestions.
           </li>
 
-          <li>If desired, call <link to="IVirtualSystemDescription::setFinalValues" /> for
-          each virtual system to override the suggestions made by VirtualBox.
+          <li>If desired, call <link to="IVirtualSystemDescription::setFinalValues" /> for each
+              virtual system to override the suggestions made by VirtualBox.
           </li>
 
           <li>Finally, call <link to="#importMachines" /> to  create virtual machines in
-          VirtualBox as instances of <link to="IMachine" /> that match the information in the
-          virtual system descriptions.
+              VirtualBox as instances of <link to="IMachine" /> that match the information in the
+              virtual system descriptions.
           </li>
         </ol>
 
+        <b>Exporting</b> VirtualBox machines into an OVF appliance involves the following steps:
+
+        <ol>
+            <li>As with importing, first call <link to="IVirtualBox::createAppliance" /> to create
+                an empty IAppliance object.
+            </li>
+
+            <li>For each machine you would like to export, call <link to="IMachine::export" />
+                with the IAppliance object you just created. This creates an instance of
+                <link to="IVirtualSystemDescription" /> inside the appliance.
+            </li>
+
+            <li>Finally, call <link to="#write" /> with a path specification to have the OVF
+                file written.</li>
+        </ol>
+
     </desc>
 
     <attribute name="path" type="wstring" readonly="yes">
       <desc>Path to the main file of the OVF appliance, which is either the <tt>.ovf</tt> or
-      the <tt>.ova</tt> file passed to <link to="IAppliance::read" />.</desc>
+          the <tt>.ova</tt> file passed to <link to="IAppliance::read" />.</desc>
     </attribute>
 
@@ -2913 +2944 @@
         <ol>
             <li>Disk ID (unique string identifier given to disk)</li>
+
             <li>Capacity (unsigned integer indicating the maximum capacity of the disk)</li>
+
             <li>Populated size (optional unsigned integer indicating the current size of the
             disk; can be approximate; -1 if unspecified)</li>
+
             <li>Format (string identifying the disk format, typically
             "http://www.vmware.com/specifications/vmdk.html#sparse")</li>
+
             <li>Reference (where to find the disk image, typically a file name; if empty,
             then the disk should be created on import)</li>
+
             <li>Image size (optional unsigned integer indicating the size of the image,
             which need not necessarily be the same as the values specified above, since
             the image may be compressed or sparse; -1 if not specified)</li>
+
             <li>Chunk size (optional unsigned integer if the image is split into chunks;
             presently unsupported and always -1)</li>
+
             <li>Compression (optional string equalling "gzip" if the image is gzip-compressed)</li>
         </ol>
@@ -2931 +2969 @@
 
     <attribute name="virtualSystemDescriptions" type="IVirtualSystemDescription" readonly="yes" safearray="yes">
-      <desc>
-      Array of virtual system descriptions. One such description is created
+      <desc> Array of virtual system descriptions. One such description is created
       for each virtual system found in the OVF. The array is empty until after <link to="#interpret" />
       has been called.
@@ -2942 +2979 @@
         Reads an OVF file into the appliance object.
 
-        The OVF standard suggests two different file formats:
-
-        <ol>
-          <li>If the OVF is distributed as a set of files, then @a file must be a fully qualified
-          path name to an existing OVF descriptor file with an <tt>.ovf</tt> file extension. If
-          this descriptor file references other files, as OVF appliances distributed as a set of
-          files most likely do, those files must be in the same directory as the descriptor file.</li>
-
-          <li>If the OVF is distributed as a single file, it must be in TAR format and have the
-          <tt>.ova</tt> file extension. This TAR file must then contain at least the OVF descriptor
-          files and optionally other files. This variant is not yet supported by VirtualBox;
-          support will be added in a later version.</li>
-        </ol>
-
         This method succeeds if the OVF is syntactically valid and, by itself, without errors. The
         mere fact that this method returns successfully does not mean that VirtualBox supports all
-        features requested by the appliance; this can be examined after a call to <link to="#interpret" />.
+        features requested by the appliance; this can only be examined after a call to <link to="#interpret" />.
       </desc>
       <param name="file" type="wstring" dir="in">
@@ -2998 +3021 @@
       <param name="aProgress" type="IProgress" dir="return">
         <desc></desc>
+      </param>
+    </method>
+
+    <method name="write">
+      <desc>
+          Writes the contents of the appliance exports into a new OVF file.
+
+          Calling this method is the final step of exporting an appliance from VirtualBox;
+          see <link to="IAppliance" /> for an overview.
+      </desc>
+      <param name="path" type="wstring" dir="in">
+        <desc>
+          Name of appliance file to open (either with an <tt>.ovf</tt> or <tt>.ova</tt> extension, depending
+          on whether the appliance is distributed as a set of files or as a single file, respectively).
+        </desc>
       </param>
     </method>
@@ -4685 +4723 @@
     </method>
 
+    <method name="export">
+        <desc>Exports the machine to an OVF appliance. See <link to="IAppliance" /> for the
+              steps required to export VirtualBox machines to OVF.
+        </desc>
+
+        <param name="appliance" type="IAppliance" dir="in">
+            <desc>Appliance to export this machine to.</desc>
+        </param>
+    </method >
+
     <method name="getSnapshot">
       <desc>
@@ -6485 +6533 @@
       <desc>Status of the interface.</desc>
     </attribute>
-    
+
     <attribute name="real" type="boolean" readonly="yes">
-      <desc>True if this is a real interface false 
+      <desc>True if this is a real interface false
       if this is a Virtualbox Host Adapter interface.</desc>
     </attribute>

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

@@ -77 +77 @@
     STDMETHOD(Interpret)(void);
     STDMETHOD(ImportMachines)(IProgress **aProgress);
-
+    STDMETHOD(Write)(IN_BSTR path);
     /* public methods only for internal purposes */
 

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

@@ -60 +60 @@
 ////////////////////////////////////////////////////////////////////////////////
 
+class IAppliance;
 class VirtualBox;
 class Progress;
@@ -547 +548 @@
     STDMETHOD(DiscardSettings)();
     STDMETHOD(DeleteSettings)();
+    STDMETHOD(Export)(IAppliance *appliance);
     STDMETHOD(GetSnapshot) (IN_GUID aId, ISnapshot **aSnapshot);
     STDMETHOD(FindSnapshot) (IN_BSTR aName, ISnapshot **aSnapshot);