virtualbox 0.6.1 → 0.7.0

data/lib/virtualbox/vm.rb

@@ -16,10 +16,49 @@ module VirtualBox
   # objects. This is best shown through example:
   #
   #     vm = VirtualBox::VM.find("MyWindowsXP")
-  #     vm.memory = 256
+  #     vm.memory_size = 256
   #     vm.name = "WindowsXP"
   #     vm.save
   #
+  # # Controlling Virtual Machines
+  #
+  # Virtual machines can be controlled using the basic {#start}, {#stop}, etc.
+  # methods. The current state of the VM can also be retrieved via the {#state}
+  # method. An example of this use is shown below:
+  #
+  #     if vm.powered_off?
+  #       vm.start
+  #     end
+  #
+  # # Taking a Snapshot
+  #
+  # Snapshots allow virtual machine states to be saved at a given point in time
+  # without having to stop the machine. This state can then be restored later.
+  # VirtualBox handles this by creating a differencing image which allows the hard
+  # drive to even retain its exact state. Taking a snapshot is extremely simple:
+  #
+  #     vm = VirtualBox::VM.find("MyWindowsXP")
+  #     vm.take_snapshot("My Snapshot", "A description of my snapshot")
+  #
+  # # Traversing Snapshots
+  #
+  # Snapshots are represented by a tree-like structure. There is a root snapshot
+  # and that snapshot has many children which may in turn have their own children.
+  # The easiest way to traverse this structure is to use the {#root_snapshot}
+  # VM method and traverse the structure like any tree structure:
+  #
+  #     vm = VirtualBox::VM.find("MyWindowsXP")
+  #     p vm.root_snapshot.children.length
+  #
+  # # Finding Snapshots
+  #
+  # While traversing the entire snapshot tree can be useful, it is often more
+  # useful to be able to simply find a snapshot by name. For this, use the
+  # {#find_snapshot} method:
+  #
+  #     vm = VirtualBox::VM.find("MyWindowsXP")
+  #     p vm.find_snapshot("PreSP3")
+  #
   # # Attributes and Relationships
   #
   # Properties of the virtual machine are exposed using standard ruby instance
@@ -39,40 +78,36 @@ module VirtualBox
   # This is copied directly from the class header, but lists all available
   # attributes. If you don't understand what this means, read {Attributable}.
   #
-  #     attribute :uuid, :readonly => true
+  #     attribute :uuid, :readonly => true, :property => :id
   #     attribute :name
-  #     attribute :ostype
-  #     attribute :description, :readonly => true
-  #     attribute :memory
-  #     attribute :vram
-  #     attribute :acpi
-  #     attribute :ioapic
-  #     attribute :cpus
-  #     attribute :synthcpu
-  #     attribute :pae
-  #     attribute :hwvirtex
-  #     attribute :hwvirtexexcl
-  #     attribute :nestedpaging
-  #     attribute :vtxvpid
-  #     attribute :accelerate3d
-  #     attribute :accelerate2dvideo
-  #     attribute :biosbootmenu, :populate_key => :bootmenu
-  #     attribute :boot1
-  #     attribute :boot2
-  #     attribute :boot3
-  #     attribute :boot4
-  #     attribute :clipboard
-  #     attribute :monitorcount
-  #     attribute :usb
-  #     attribute :ehci
-  #     attribute :audio
-  #     attribute :audiocontroller
-  #     attribute :audiodriver
-  #     attribute :vrdp
-  #     attribute :vrdpport
-  #     attribute :vrdpauthtype
-  #     attribute :vrdpauthtimeout
-  #     attribute :state, :populate_key => :vmstate, :readonly => true
+  #     attribute :os_type_id
+  #     attribute :description
+  #     attribute :memory_size
+  #     attribute :memory_balloon_size
+  #     attribute :vram_size
+  #     attribute :cpu_count
+  #     attribute :accelerate_3d_enabled, :boolean => true
+  #     attribute :accelerate_2d_video_enabled, :boolean => true
+  #     attribute :clipboard_mode
+  #     attribute :monitor_count
+  #     attribute :state, :readonly => true
+  #     attribute :accessible, :readonly => true, :boolean => true
+  #     attribute :hardware_version
+  #     attribute :hardware_uuid
+  #     attribute :firmware_type
+  #     attribute :snapshot_folder
+  #     attribute :settings_file_path, :readonly => true
+  #     attribute :last_state_change, :readonly => true
+  #     attribute :state_file_path, :readonly => true
+  #     attribute :log_folder, :readonly => true
+  #     attribute :snapshot_count, :readonly => true
+  #     attribute :current_state_modified, :readonly => true
+  #     attribute :guest_property_notification_patterns
+  #     attribute :teleporter_enabled, :boolean => true
+  #     attribute :teleporter_port
+  #     attribute :teleporter_address
+  #     attribute :teleporter_password
+  #     attribute :interface, :readonly => true, :property => false
   #
   # ## Relationships
   #
@@ -80,31 +115,39 @@ module VirtualBox
   # to other things. The relationships are listed below. If you don't
   # understand this, read {Relatable}.
   #
-  #     relationship :nics, Nic
-  #     relationship :usbs, USB
-  #     relationship :storage_controllers, StorageController, :dependent => :destroy
-  #     relationship :shared_folders, SharedFolder
-  #     relationship :extra_data, ExtraData
-  #     relationship :forwarded_ports, ForwardedPort
+  #     relationship :audio_adapter, :AudioAdapter
+  #     relationship :bios, :BIOS
+  #     relationship :hw_virt, :HWVirtualization
+  #     relationship :cpu, :CPU
+  #     relationship :vrdp_server, :VRDPServer
+  #     relationship :storage_controllers, :StorageController, :dependent => :destroy
+  #     relationship :medium_attachments, :MediumAttachment
+  #     relationship :shared_folders, :SharedFolder
+  #     relationship :extra_data, :ExtraData
+  #     relationship :forwarded_ports, :ForwardedPort
+  #     relationship :network_adapters, :NetworkAdapter
+  #     relationship :usb_controller, :USBController
+  #     relationship :current_snapshot, :Snapshot
   #
   class VM < AbstractModel
     attribute :uuid, :readonly => true, :property => :id
     attribute :name
     attribute :os_type_id
-    attribute :description, :readonly => true
+    attribute :description
     attribute :memory_size
     attribute :memory_balloon_size
     attribute :vram_size
     attribute :cpu_count
-    attribute :accelerate_3d_enabled
-    attribute :accelerate_2d_video_enabled
+    attribute :accelerate_3d_enabled, :boolean => true
+    attribute :accelerate_2d_video_enabled, :boolean => true
     attribute :clipboard_mode
     attribute :monitor_count
     attribute :state, :readonly => true
-    attribute :accessible, :readonly => true
+    attribute :accessible, :readonly => true, :boolean => true
     attribute :hardware_version
     attribute :hardware_uuid
-    attribute :statistics_update_interval
+    # TODO: Removed in 3.2.x, how should we handle this?
+    # attribute :statistics_update_interval
     attribute :firmware_type
     attribute :snapshot_folder
     attribute :settings_file_path, :readonly => true
@@ -114,14 +157,19 @@ module VirtualBox
     attribute :snapshot_count, :readonly => true
     attribute :current_state_modified, :readonly => true
     attribute :guest_property_notification_patterns
-    attribute :teleporter_enabled
+    attribute :teleporter_enabled, :boolean => true
     attribute :teleporter_port
     attribute :teleporter_address
     attribute :teleporter_password
+    attribute :boot_order,
+      :property_getter => Proc.new { |instance, *args| instance.get_boot_order(*args) },
+      :property_setter => Proc.new { |instance, *args| instance.set_boot_order(*args) }
     attribute :interface, :readonly => true, :property => false
     relationship :audio_adapter, :AudioAdapter
     relationship :bios, :BIOS
     relationship :hw_virt, :HWVirtualization
+    relationship :cpu, :CPU
+    relationship :vrdp_server, :VRDPServer
     relationship :storage_controllers, :StorageController, :dependent => :destroy
     relationship :medium_attachments, :MediumAttachment
     relationship :shared_folders, :SharedFolder
@@ -129,8 +177,9 @@ module VirtualBox
     relationship :forwarded_ports, :ForwardedPort
     relationship :network_adapters, :NetworkAdapter
     relationship :usb_controller, :USBController
+    relationship :current_snapshot, :Snapshot
 
-    class <<self
+    class << self
       # Returns an array of all available VMs.
       #
       # @return [Array<VM>]
@@ -155,7 +204,7 @@ module VirtualBox
       # the first virtual machine will be returned, although all will
       # be imported.
       #
-      # If a block is given, it will be yielded with the percent of the
+      # If a block is given, it will be yielded with the progress of the
       # import operation, so that the progress of the import can be
       # tracked.
       #
@@ -168,6 +217,14 @@ module VirtualBox
       end
 
       def populate_relationship(caller, machines)
+        machines.is_a?(Array) ? populate_array_relationship(caller, machines) : populate_single_relationship(caller, machines)
+      end
+
+      def populate_single_relationship(caller, machine)
+        new(machine)
+      end
+
+      def populate_array_relationship(caller, machines)
         result = Proxies::Collection.new(caller)
 
         machines.each do |machine|
@@ -206,6 +263,14 @@ module VirtualBox
       existing_record!
     end
 
+    # Reload the model so that all the attributes and relationships are
+    # up to date. This method will automatically discard any changes to
+    # the VM and any of its relationships.
+    def reload
+      initialize_attributes(interface)
+      self
+    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`.
@@ -213,30 +278,101 @@ module VirtualBox
     # @param [Boolean] reload If true, will reload the state to current
     #   value.
     # @return [String] Virtual machine state.
-    def state(reload=false)
-      if reload
-        load_interface_attribute(:state)
+    def state(suppress_state_reload=false)
+      if !suppress_state_reload
+        load_interface_attribute(:state, interface)
         clear_dirty!(:state)
       end
 
       read_attribute(:state)
     end
 
+    # Validates the virtual machine
+    def validate
+      super
+
+      validates_presence_of :name, :os_type_id, :memory_size, :vram_size, :cpu_count
+      validates_numericality_of :memory_balloon_size, :monitor_count
+      validates_inclusion_of :accelerate_3d_enabled, :accelerate_2d_video_enabled, :teleporter_enabled, :in => [true, false]
+
+      validates_format_of :name, :with => /^[\w\d\s-]+$/, :message => 'must only contain letters, numbers, spaces, underscores, and dashes.'
+
+      if !errors_on(:name)
+        # Only validate the name if the name has no errors already
+        vms_of_same_name = self.class.find(name)
+        add_error(:name, 'must not be used by another virtual machine.') if vms_of_same_name && vms_of_same_name.uuid != uuid
+      end
+
+      validates_inclusion_of :os_type_id, :in => VirtualBox::Global.global.lib.virtualbox.guest_os_types.collect { |os| os.id }
+
+      min_guest_ram, max_guest_ram = Global.global.system_properties.min_guest_ram, Global.global.system_properties.max_guest_ram
+      validates_inclusion_of :memory_size, :in => (min_guest_ram..max_guest_ram), :message => "must be between #{min_guest_ram} and #{max_guest_ram}."
+      validates_inclusion_of :memory_balloon_size, :in => (0..max_guest_ram), :message => "must be between 0 and #{max_guest_ram}."
+
+      min_guest_vram, max_guest_vram = Global.global.system_properties.min_guest_vram, Global.global.system_properties.max_guest_vram
+      validates_inclusion_of :vram_size, :in => (min_guest_vram..max_guest_vram), :message => "must be between #{min_guest_vram} and #{max_guest_vram}."
+
+      min_guest_cpu_count, max_guest_cpu_count = Global.global.system_properties.min_guest_cpu_count, Global.global.system_properties.max_guest_cpu_count
+      validates_inclusion_of :cpu_count, :in => (min_guest_cpu_count..max_guest_cpu_count), :message => "must be between #{min_guest_cpu_count} and #{max_guest_cpu_count}."
+
+      validates_inclusion_of :clipboard_mode, :in => COM::Util.versioned_interface(:ClipboardMode).map
+      validates_inclusion_of :firmware_type, :in => COM::Util.versioned_interface(:FirmwareType).map
+    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
+      return false unless valid?
+      raise Exceptions::ReadonlyVMStateException.new("VM must not be in saved state to modify.") if saved?
+
       with_open_session do |session|
         # Use setters to save the attributes on the locked machine and persist
         # the settings
         machine = session.machine
 
+        # Save the boot order
+        save_interface_attribute(:boot_order, machine)
+
         # Save all the attributes and relationships
         save_changed_interface_attributes(machine)
 
         # Save relationships, which may open their own sessions if necessary
         save_relationships
       end
+
+      true
+    end
+
+    # Returns the root snapshot of this virtual machine. This root snapshot
+    # can be used to traverse the tree of snapshots.
+    #
+    # @return [Snapshot]
+    def root_snapshot
+      return nil if current_snapshot.nil?
+
+      current = current_snapshot
+      current = current.parent while current.parent != nil
+      current
+    end
+
+    # Find a snapshot by name or UUID. This allows you to find a snapshot by a given
+    # name, rather than having to resort to traversing the entire tree structure
+    # manually.
+    def find_snapshot(name)
+      find_helper = lambda do |name, root|
+        return nil if root.nil?
+        return root if root.name == name || root.uuid == name
+
+        root.children.each do |child|
+          result = find_helper.call(name, child)
+          return result unless result.nil?
+        end
+
+        nil
+      end
+
+      find_helper.call(name, root_snapshot)
     end
 
     # Opens a direct session with the machine this VM represents and yields
@@ -263,12 +399,23 @@ module VirtualBox
 
       # Close the session
       if close_session
-        # Save these settings only if we're closing
-        session.machine.save_settings
+        # Save these settings only if we're closing and only if the state
+        # is not saved, since that doesn't allow the machine to be saved.
+        session.machine.save_settings if session.machine.state != :saved
 
         # Close the session
         session.close
       end
+    rescue Exception
+      # Close the session so we don't get locked out. We use a rescue block
+      # here instead of an "ensure" since we ONLY want this to occur if an
+      # exception is raised. Otherwise, we may or may not close the session,
+      # depending how deeply nested this call to `with_open_session` is.
+      # (see close_session boolean above)
+      session.close if session.state == :open
+
+      # Reraise the exception, we're not actually catching it to handle it
+      raise
     end
 
     # Exports a virtual machine. The virtual machine will be exported
@@ -284,18 +431,33 @@ module VirtualBox
     # 60 to 90 seconds on my 2.2 GHz 2009 model MacBook Pro.
     #
     # If a block is given to the method, then it will be yielded with the
-    # percent progress of the operation (in intervals of 1 percent).
+    # progress of the operation.
     #
     # @param [String] filename The file (not directory) to save the exported
     #   OVF file. This directory will also receive the checksum file and
     #   virtual disks.
-    def export(filename, &block)
+    def export(filename, options = {}, &block)
       app = Appliance.new
       app.path = filename
-      app.add_machine(self)
+      app.add_machine(self, options)
       app.export(&block)
     end
 
+    # Take a snapshot of the current state of the machine. This method can be
+    # called while the VM is running and also while it is powered off. This
+    # method will block while the snapshot is being taken.
+    #
+    # If a block is given to this method, it will yield with a progress
+    # object which can be used to get the progress of the operation.
+    #
+    # @param [String] name Name of the snapshot.
+    # @param [String] description Description of the snapshot.
+    def take_snapshot(name, description="", &block)
+      with_open_session do |session|
+        session.console.take_snapshot(name, description).wait(&block)
+      end
+    end
+
     # Starts the virtual machine. The virtual machine can be started in a
     # variety of modes:
     #
@@ -314,11 +476,10 @@ module VirtualBox
       # as well
       session = Lib.lib.session
       interface.parent.open_remote_session(session, uuid, mode.to_s, "").wait_for_completion(-1)
-
-      # Close our session to release our lock from the machine
-      session.close
-
       true
+    ensure
+      # Be sure to close that session!
+      session.close if session && session.state == :open
     end
 
     # Shuts down the VM by directly calling "acpipowerbutton". Depending on the
@@ -385,10 +546,10 @@ module VirtualBox
 
       # Send the proper command, waiting if we have to
       result = session.console.send(command, *args)
-      result.wait_for_completion(-1) if result.is_a?(COM::Interface::Progress)
-
+      result.wait_for_completion(-1) if result.is_a?(COM::Util.versioned_interface(:Progress))
+    ensure
       # Close the session
-      session.close
+      session.close if session && session.state == :open
     end
 
     # Destroys the virtual machine. This method also removes all attached
@@ -403,6 +564,23 @@ module VirtualBox
     #     not only unregister attached media, but will also physically
     #     remove their respective data.
     def destroy(*args)
+      # Destroy all snapshots first (by destroying the root, all children
+      # are automatically destroyed)
+      if root_snapshot
+        destroy_snapshot = lambda do |snapshot|
+          return if snapshot.nil?
+
+          snapshot.children.each { |c| destroy_snapshot.call(c) }
+          snapshot.destroy
+        end
+
+        destroy_snapshot.call(root_snapshot)
+
+        # Reload ourselves before continuing since snapshots do some
+        # crazy things.
+        reload
+      end
+
       # Call super first so destroy is propogated through to relationships
       # first
       super
@@ -412,6 +590,13 @@ module VirtualBox
       interface.delete_settings
     end
 
+    # Returns true if the virtual machine state is starting
+    #
+    # @return [Boolean] True if virtual machine state is starting
+    def starting?
+      state == :starting
+    end
+
     # Returns true if the virtual machine state is running
     #
     # @return [Boolean] True if virtual machine state is running
@@ -446,5 +631,29 @@ module VirtualBox
     def aborted?
       state == :aborted
     end
+
+    # Loads the boot order for this virtual machine. This method should
+    # never be called directly. Instead, use the `boot_order` attribute
+    # to read and modify the boot order.
+    def get_boot_order(interface, key)
+      max_boot = Global.global.system_properties.max_boot_position
+
+      (1..max_boot).inject([]) do |order, position|
+        order << interface.get_boot_order(position)
+        order
+      end
+    end
+
+    # Sets the boot order for this virtual machine. This method should
+    # never be called directly. Instead, modify the `boot_order` array.
+    def set_boot_order(interface, key, value)
+      max_boot = Global.global.system_properties.max_boot_position
+      value = value.dup
+      value.concat(Array.new(max_boot - value.size)) if value.size < max_boot
+
+      (1..max_boot).each do |position|
+        interface.set_boot_order(position, value[position - 1])
+      end
+    end
   end
-end
+end

data/lib/virtualbox/vrdp_server.rb

@@ -0,0 +1,59 @@
+module VirtualBox
+  # Represents the VRDP Server settings of a {VM}.
+  class VRDPServer < AbstractModel
+    attribute :parent, :readonly => true, :property => false
+    attribute :enabled, :boolean => true
+    attribute :ports
+    attribute :net_address
+    attribute :auth_type
+    attribute :auth_timeout
+    attribute :allow_multi_connection, :boolean => true
+    attribute :reuse_single_connection, :boolean => true
+
+    class << self
+      # Populates a relationship with another model.
+      #
+      # **This method typically won't be used except internally.**
+      #
+      # @return [VRDPServer]
+      def populate_relationship(caller, imachine)
+        data = new(caller, imachine.vrdp_server)
+      end
+
+      # Saves the relationship.
+      #
+      # **This method typically won't be used except internally.**
+      def save_relationship(caller, instance)
+        instance.save
+      end
+    end
+
+    def initialize(parent, vrdp_settings)
+      write_attribute(:parent, parent)
+
+      # Load the attributes and mark the whole thing as existing
+      load_interface_attributes(vrdp_settings)
+      clear_dirty!
+      existing_record!
+    end
+
+    def validate
+      super
+
+      validates_inclusion_of :enabled, :allow_multi_connection, :reuse_single_connection, :in => [true, false]
+      validates_format_of :ports, :with => /^[\d\s\-\.]+$/, :message => "must only contain numbers, spaces, dashes or periods."
+      validates_format_of :net_address, :with => /^[\w\d\-\.]+$/, :message => "must only contain latters, numbers, dashes or periods."
+      validates_inclusion_of :auth_type, :in => COM::Util.versioned_interface(:VRDPAuthType).map
+      validates_numericality_of :auth_timeout
+    end
+
+    def save
+      parent.with_open_session do |session|
+        machine = session.machine
+
+        # Save them
+        save_changed_interface_attributes(machine.vrdp_server)
+      end
+    end
+  end
+end

data/test/test_helper.rb

@@ -18,4 +18,10 @@ require File.join(File.dirname(__FILE__), '..', 'lib', 'virtualbox')
 
 # Data
 class Test::Unit::TestCase
-end
+end
+
+# Initialize the FFI stuff. This is typically done dynamically when
+# FFI is initialized (on non-windows machines). Since the tests test
+# the FFI classes, we force initialize a specific version here. It
+# doesn't matter what version, since no actual FFI calls are made.
+VirtualBox::COM::FFI.setup("3.1.x") unless defined?(VirtualBox::COM::FFI::Version_3_1_X)

data/test/virtualbox/abstract_model/attributable_test.rb

@@ -8,6 +8,7 @@ class AttributableTest < Test::Unit::TestCase
   class AttributeModel < EmptyAttributeModel
     attribute :foo
     attribute :bar
+    attribute :boolean_bar, :boolean => true
 
     def initialize
       super
@@ -211,6 +212,13 @@ class AttributableTest < Test::Unit::TestCase
       assert atts.has_key?(:bar)
     end
 
+    should "be able to access boolean values with a '?'" do
+      @model.boolean_bar = true
+      assert @model.boolean_bar?
+      @model.boolean_bar = false
+      assert !@model.boolean_bar?
+    end
+
     should "be able to write defined attributes" do
       assert_nothing_raised {
         @model.foo = @check_string

data/test/virtualbox/abstract_model/relatable_test.rb

@@ -17,8 +17,8 @@ class RelatableTest < Test::Unit::TestCase
   end
 
   class RelatableModel < EmptyRelatableModel
-    relationship :foos, Relatee
-    relationship :bars, BarRelatee
+    relationship :foos, RelatableTest::Relatee
+    relationship :bars, RelatableTest::BarRelatee
   end
 
   setup do
@@ -246,8 +246,8 @@ class RelatableTest < Test::Unit::TestCase
 
   context "determining the class of relationships" do
     class ClassRelatableModel < EmptyRelatableModel
-      relationship :foo, Relatee
-      relationship :bar, "RelatableTest::Relatee"
+      relationship :foo, RelatableTest::Relatee
+      relationship :bar, "RelatableTest::BarRelatee"
     end
 
     setup do
@@ -259,7 +259,7 @@ class RelatableTest < Test::Unit::TestCase
     end
 
     should "turn string into class" do
-      assert_equal Relatee, @model.relationship_class(:bar)
+      assert_equal BarRelatee, @model.relationship_class(:bar)
     end
   end