vm.rb in virtualbox-0.2.0

- old
+ new

@@ -224,19 +224,24 @@
     end
     
     # Saves the virtual machine if modified. This method saves any modified
     # attributes of the virtual machine. If any related attributes were saved
     # as well (such as storage controllers), those will be saved, too.
-    def save
+    def save(raise_errors=false)
       # Make sure we save the new name first if that was changed, or
       # we'll get some inconsistencies later
       if name_changed?
         save_attribute(:name, name)
         @original_name = name
       end
       
-      super
+      super()
+      
+      true
+    rescue Exceptions::CommandFailedException
+      raise if raise_errors
+      return false
     end
     
     # Saves a single attribute of the virtual machine. This should **not**
     # be called except interally. Instead, you're probably looking for {#save}.
     #
@@ -244,27 +249,122 @@
     def save_attribute(key, value)
       Command.vboxmanage("modifyvm #{@original_name} --#{key} #{Command.shell_escape(value.to_s)}")
       super
     end
     
+    # Exports a virtual machine. The virtual machine will be exported
+    # to the specified OVF file name. This directory will also have the
+    # `mf` file which contains the file checksums and also the virtual
+    # drives of the machine.
+    #
+    # Export also supports an additional options hash which can contain
+    # information that will be embedded with the virtual machine. View
+    # below for more information on the available options.
+    #
+    # This method will block until the export is complete, which takes about
+    # 60 to 90 seconds on my 2.2 GHz 2009 model MacBook Pro.
+    #
+    # @param [String] filename The file (not directory) to save the exported
+    #   OVF file. This directory will also receive the checksum file and
+    #   virtual disks.
+    # @option options [String] :product (nil) The name of the product
+    # @option options [String] :producturl (nil) The URL of the product
+    # @option options [String] :vendor (nil) The name of the vendor
+    # @option options [String] :vendorurl (nil) The URL for the vendor
+    # @option options [String] :version (nil) The version information
+    # @option options [String] :eula (nil) License text
+    # @option options [String] :eulafile (nil) License file
+    def export(filename, options={}, raise_error=false)
+      options = options.inject([]) do |acc, kv|
+        acc.push("--#{kv[0]} #{Command.shell_escape(kv[1])}")
+      end
+      
+      options.unshift("--vsys 0") unless options.empty?
+      
+      raw = Command.vboxmanage("export #{@original_name} -o #{Command.shell_escape(filename)} #{options.join(" ")}".strip)
+      true
+    rescue Exceptions::CommandFailedException
+      raise if raise_error
+      false
+    end
+    
     # Starts the virtual machine. The virtual machine can be started in a
     # variety of modes:
     #
     # * **gui** -- The VirtualBox GUI will open with the screen of the VM.
     # * **headless** -- The VM will run in the background. No GUI will be 
     #   present at all.
     #
     # All modes will start their processes and return almost immediately.
     # Both the GUI and headless mode will not block the ruby process.
-    def start(mode=:gui)
+    #
+    # @param [Symbol] mode Described above.
+    # @param [Boolean] raise_errors If true, {Exceptions::CommandFailedException}
+    #   will be raised if the command failed.
+    # @return [Boolean] True if command was successful, false otherwise.
+    def start(mode=:gui, raise_errors=false)
       Command.vboxmanage("startvm #{@original_name} --type #{mode}")
+      true
+    rescue Exceptions::CommandFailedException
+      raise if raise_errors
+      false
     end
     
     # Stops the VM by directly calling "poweroff." Immediately halts the
     # virtual machine without saving state. This could result in a loss
     # of data.
-    def stop
-      Command.vboxmanage("controlvm #{@original_name} poweroff")
+    #
+    # @param [Boolean] raise_errors If true, {Exceptions::CommandFailedException}
+    #   will be raised if the command failed.
+    # @return [Boolean] True if command was successful, false otherwise.
+    def stop(raise_errors=false)
+      control(:poweroff, raise_errors)
+    end
+    
+    # Pauses the VM, putting it on hold temporarily. The VM can be resumed
+    # again by calling {#resume}
+    #
+    # @param [Boolean] raise_errors If true, {Exceptions::CommandFailedException}
+    #   will be raised if the command failed.
+    # @return [Boolean] True if command was successful, false otherwise.
+    def pause(raise_errors=false)
+      control(:pause, raise_errors)
+    end
+    
+    # Resume a paused VM.
+    #
+    # @param [Boolean] raise_errors If true, {Exceptions::CommandFailedException}
+    #   will be raised if the command failed.
+    # @return [Boolean] True if command was successful, false otherwise.
+    def resume(raise_errors=false)
+      control(:resume, raise_errors)
+    end
+    
+    # Saves the state of a VM and stops it. The VM can be resumed
+    # again by calling "start" again.
+    #
+    # @param [Boolean] raise_errors If true, {Exceptions::CommandFailedException}
+    #   will be raised if the command failed.
+    # @return [Boolean] True if command was successful, false otherwise.
+    def save_state(raise_errors=false)
+      control(:savestate, raise_errors)
+    end
+    
+    # Controls the virtual machine. This method is used by {#stop},
+    # {#pause}, {#resume}, and {#save_state} to control the virtual machine.
+    # Typically, you won't ever have to call this method and should
+    # instead call those.
+    #
+    # @param [String] command The command to run on controlvm
+    # @param [Boolean] raise_errors If true, {Exceptions::CommandFailedException}
+    #   will be raised if the command failed.
+    # @return [Boolean] True if command was successful, false otherwise.
+    def control(command, raise_errors=false)
+      Command.vboxmanage("controlvm #{@original_name} #{command}")
+      true
+    rescue Exceptions::CommandFailedException
+      raise if raise_errors
+      false
     end
     
     # Destroys the virtual machine. This method also removes all attached
     # media (required by VirtualBox to destroy a VM). By default,
     # this **will not** destroy attached hard drives, but will if given
\ No newline at end of file