virtualbox 0.4.1 → 0.4.2

data/lib/virtualbox/vm.rb

@@ -1,6 +1,6 @@
 module VirtualBox
   # Represents a single VirtualBox virtual machine. All attributes which are
-  # not read-only can be modified and saved. 
+  # not read-only can be modified and saved.
   #
   # # Finding Virtual Machines
   #
@@ -21,10 +21,10 @@ module VirtualBox
   #     vm.save
   #
   # # Attributes and Relationships
-  # 
+  #
   # Properties of the virtual machine are exposed using standard ruby instance
   # methods which are generated on the fly. Because of this, they are not listed
-  # below as available instance methods. 
+  # below as available instance methods.
   #
   # These attributes can be accessed and modified via standard ruby-style
   # `instance.attribute` and `instance.attribute=` methods. The attributes are
@@ -33,7 +33,7 @@ module VirtualBox
   # Relationships are also accessed like attributes but can't be set. Instead,
   # they are typically references to other objects such as a {HardDrive} which
   # in turn have their own attributes which can be modified.
-  # 
+  #
   # ## Attributes
   #
   # This is copied directly from the class header, but lists all available
@@ -54,6 +54,7 @@ module VirtualBox
   #     attribute :nestedpaging
   #     attribute :vtxvpid
   #     attribute :accelerate3d
+  #     attribute :accelerate2dvideo
   #     attribute :biosbootmenu, :populate_key => :bootmenu
   #     attribute :boot1
   #     attribute :boot2
@@ -64,6 +65,7 @@ module VirtualBox
   #     attribute :usb
   #     attribute :audio
   #     attribute :vrdp
+  #     attribute :vrdpports
   #     attribute :state, :populate_key => :vmstate, :readonly => true
   #
   # ## Relationships
@@ -94,6 +96,7 @@ module VirtualBox
     attribute :nestedpaging
     attribute :vtxvpid
     attribute :accelerate3d
+    attribute :accelerate2dvideo
     attribute :biosbootmenu, :populate_key => :bootmenu
     attribute :boot1
     attribute :boot2
@@ -104,13 +107,14 @@ module VirtualBox
     attribute :usb
     attribute :audio
     attribute :vrdp
+    attribute :vrdpports
     attribute :state, :populate_key => :vmstate, :readonly => true
     relationship :nics, Nic
     relationship :storage_controllers, StorageController, :dependent => :destroy
     relationship :shared_folders, SharedFolder
     relationship :extra_data, ExtraData
     relationship :forwarded_ports, ForwardedPort
-    
+
     class <<self
       # Returns an array of all available VMs.
       #
@@ -119,16 +123,18 @@ module VirtualBox
         raw = Command.vboxmanage("list vms")
         parse_vm_list(raw)
       end
-      
+
       # Finds a VM by UUID or registered name and returns a
       # new VM object. If the VM doesn't exist, will return `nil`.
       #
       # @return [VM]
       def find(name)
         new(raw_info(name))
+      rescue Exceptions::CommandFailedException
+        nil
       end
-      
-      # Imports a VM, blocking the entire thread during this time. 
+
+      # Imports a VM, blocking the entire thread during this time.
       # When finished, on success, will return the VM object. This
       # VM object can be used to make any modifications necessary
       # (RAM, cpus, etc.).
@@ -137,10 +143,10 @@ module VirtualBox
       def import(source_path)
         raw = Command.vboxmanage("import #{Command.shell_escape(source_path)}")
         return nil unless raw
-        
+
         find(parse_vm_name(raw))
       end
-      
+
       # Gets the non-machine-readable info for a given VM and returns
       # it as a raw string.
       #
@@ -150,16 +156,16 @@ module VirtualBox
       def human_info(name)
         Command.vboxmanage("showvminfo #{Command.shell_escape(name)}")
       end
-      
+
       # Gets the VM info (machine readable) for a given VM and returns it
-      # as a hash. 
+      # as a hash.
       #
       # @return [Hash] Parsed VM info.
       def raw_info(name)
         raw = Command.vboxmanage("showvminfo #{Command.shell_escape(name)} --machinereadable")
         parse_vm_info(raw)
       end
-      
+
       # Parses the machine-readable format outputted by VBoxManage showvminfo
       # into a hash. Ignores lines which don't match the format.
       def parse_vm_info(raw)
@@ -172,7 +178,7 @@ module VirtualBox
 
         parsed
       end
-      
+
       # Parses the list of VMs returned by the "list vms" command used
       # in {VM.all}.
       #
@@ -185,10 +191,10 @@ module VirtualBox
           next unless line =~ /^"(.+?)"\s+\{(.+?)\}$/
           results.push(find($1.to_s))
         end
-        
+
         results
       end
-      
+
       # Parses the vm name from the import results.
       #
       # **This method typically won't be used except internally.**
@@ -199,7 +205,7 @@ module VirtualBox
         $1.to_s
       end
     end
-    
+
     # Creates a new instance of a virtual machine.
     #
     # **Currently can NOT be used to create a NEW virtual machine**.
@@ -208,11 +214,11 @@ module VirtualBox
     # initialize the VMs.
     def initialize(data)
       super()
-      
+
       populate_attributes(data)
       @original_name = data[:name]
     end
-    
+
     # State of the virtual machine. Returns the state of the virtual
     # machine. This state will represent the state that was assigned
     # when the VM was found unless `reload` is set to `true`.
@@ -225,10 +231,10 @@ module VirtualBox
         info = self.class.raw_info(@original_name)
         write_attribute(:state, info[:vmstate])
       end
-      
+
       read_attribute(:state)
     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.
@@ -239,24 +245,24 @@ module VirtualBox
         save_attribute(:name, name)
         @original_name = name
       end
-      
+
       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}.
     #
     # **This method typically won't be used except internally.**
     def save_attribute(key, value)
-      Command.vboxmanage("modifyvm #{@original_name} --#{key} #{Command.shell_escape(value.to_s)}")
+      Command.vboxmanage("modifyvm #{Command.shell_escape(@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
@@ -283,21 +289,21 @@ module VirtualBox
       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)
+
+      raw = Command.vboxmanage("export #{Command.shell_escape(@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 
+    # * **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.
@@ -308,16 +314,28 @@ module VirtualBox
     #   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}")
+      Command.vboxmanage("startvm #{Command.shell_escape(@original_name)} --type #{mode}")
       true
     rescue Exceptions::CommandFailedException
       raise if raise_errors
       false
     end
-    
+
+    # Shuts down the VM by directly calling "acpipowerbutton". Depending on the
+    # settings of the Virtual Machine, this may not work. For example, some linux
+    # installations don't respond to the ACPI power button at all. In such cases,
+    # {#stop} or {#save_state} may be used instead.
+    #
+    # @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 shutdown(raise_errors=false)
+      control(:acpipowerbutton, raise_errors)
+    end
+
     # Stops the VM by directly calling "poweroff." Immediately halts the
     # virtual machine without saving state. This could result in a loss
-    # of data.
+    # of data. To prevent data loss, see {#shutdown}
     #
     # @param [Boolean] raise_errors If true, {Exceptions::CommandFailedException}
     #   will be raised if the command failed.
@@ -325,7 +343,7 @@ module VirtualBox
     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}
     #
@@ -335,7 +353,7 @@ module VirtualBox
     def pause(raise_errors=false)
       control(:pause, raise_errors)
     end
-    
+
     # Resume a paused VM.
     #
     # @param [Boolean] raise_errors If true, {Exceptions::CommandFailedException}
@@ -344,7 +362,7 @@ module VirtualBox
     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.
     #
@@ -354,7 +372,7 @@ module VirtualBox
     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
@@ -365,13 +383,13 @@ module VirtualBox
     #   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}")
+      Command.vboxmanage("controlvm #{Command.shell_escape(@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
@@ -386,8 +404,43 @@ module VirtualBox
       # Call super first to destroy relationships, necessary before
       # unregistering a VM
       super
-      
-      Command.vboxmanage("unregistervm #{@original_name} --delete")
+
+      Command.vboxmanage("unregistervm #{Command.shell_escape(@original_name)} --delete")
+    end
+
+    # Returns true if the virtual machine state is running
+    #
+    # @return [Boolean] True if virtual machine state is running
+    def running?
+      state == 'running'
+    end
+
+    # Returns true if the virtual machine state is powered off
+    #
+    # @return [Boolean] True if virtual machine state is powered off
+    def powered_off?
+      state == 'poweroff'
+    end
+
+    # Returns true if the virtual machine state is paused
+    #
+    # @return [Boolean] True if virtual machine state is paused
+    def paused?
+      state == 'paused'
+    end
+
+    # Returns true if the virtual machine state is saved
+    #
+    # @return [Boolean] True if virtual machine state is saved
+    def saved?
+      state == 'saved'
+    end
+
+    # Returns true if the virtual machine state is aborted
+    #
+    # @return [Boolean] True if virtual machine state is aborted
+    def aborted?
+      state == 'aborted'
     end
   end
 end

data/test/virtualbox/abstract_model/attributable_test.rb

@@ -2,28 +2,28 @@ require File.join(File.dirname(__FILE__), '..', '..', 'test_helper')
 
 class AttributableTest < Test::Unit::TestCase
   class EmptyAttributeModel
-    include VirtualBox::AbstractModel::Attributable    
+    include VirtualBox::AbstractModel::Attributable
   end
-  
+
   class AttributeModel < EmptyAttributeModel
     attribute :foo
     attribute :bar
-    
+
     def initialize
       super
-      
+
       populate_attributes({
         :foo => "foo",
         :bar => "bar"
       })
     end
   end
-  
+
   context "subclasses" do
     class SubModel < AttributeModel
       attribute :baz
     end
-    
+
     should "have foo bar and baz" do
       attributes = SubModel.attributes
       assert attributes.has_key?(:foo)
@@ -31,118 +31,118 @@ class AttributableTest < Test::Unit::TestCase
       assert attributes.has_key?(:baz)
     end
   end
-  
+
   context "attribute options" do
     context "custom populate keys" do
       class CustomPopulateModel < AttributeModel
         attribute :foo, :populate_key => :foo_key
       end
-      
+
       setup do
         @model = CustomPopulateModel.new
       end
-      
+
       should "use the populate key instead of the attribute name" do
         @model.populate_attributes({
           :foo => "not me!",
           :foo_key => "bar"
         })
-        
+
         assert_equal "bar", @model.foo
       end
     end
-    
+
     context "readonly attributes" do
       class ReadonlyModel < AttributeModel
         attribute :foo, :readonly => :readonly
-        
+
         def initialize
           super
           populate_attributes({ :foo => "foo" })
         end
       end
-      
+
       setup do
         @model = ReadonlyModel.new
       end
-      
+
       should "be readonly" do
         assert @model.readonly_attribute?(:foo)
       end
-      
+
       should "allow reading" do
         assert_equal "foo", @model.foo
       end
-      
+
       should "not allow writing" do
         assert_raises(NoMethodError) { @model.foo = "YO" }
       end
     end
-    
+
     context "default values" do
       class DefaultModel < EmptyAttributeModel
         attribute :foo, :default => "FOO!"
         attribute :bar
       end
-      
+
       setup do
         @model = DefaultModel.new
       end
-      
+
       should "read default values" do
         assert_equal "FOO!", @model.foo
         assert_nil @model.bar
       end
     end
   end
-  
+
   context "populating attributes" do
     setup do
       @model = AttributeModel.new
     end
-    
+
     should "write all valid attributes" do
       new_attributes = {
         :foo => "zxcv",
         :bar => "qwerty"
       }
-      
+
       @model.populate_attributes(new_attributes)
       new_attributes.each do |k,v|
         assert_equal v, @model.send(k)
       end
     end
   end
-  
+
   context "reading and writing attributes" do
     setup do
       @model = AttributeModel.new
       @checkstring = "HEY"
     end
-    
+
     should "be able to read an entire hash of attributes" do
       atts = @model.attributes
       assert atts.is_a?(Hash)
       assert atts.has_key?(:foo)
       assert atts.has_key?(:bar)
     end
-    
+
     should "be able to write defined attributes" do
       assert_nothing_raised {
         @model.foo = @check_string
       }
     end
-    
+
     should "be able to read defined attributes" do
       assert_nothing_raised {
         assert_equal "foo", @model.foo
       }
     end
-    
+
     should "raise an error if attempting to write an undefined attribute" do
       assert_raises(NoMethodError) { @model.baz = @check_string }
     end
-    
+
     should "raise an error if attempting to read an undefined attribute" do
       assert_raises(NoMethodError) { @model.baz }
     end