virtualbox 0.6.1 → 0.7.0

data/lib/virtualbox/forwarded_port.rb

@@ -67,7 +67,8 @@ module VirtualBox
   #     attribute :hostport
   #
   class ForwardedPort < AbstractModel
-    attribute :parent, :readonly => true
+    attribute :parent, :readonly => true, :property => false
+    attribute :parent_collection, :readonly => true, :property => false
     attribute :name
     attribute :instance, :default => "0"
     attribute :device, :default => "pcnet"
@@ -75,7 +76,7 @@ module VirtualBox
     attribute :guestport
     attribute :hostport
 
-    class <<self
+    class << self
       # Populates a relationship with another model.
       #
       # **This method typically won't be used except internally.**
@@ -89,6 +90,7 @@ module VirtualBox
 
           port = new({
             :parent => caller,
+            :parent_collection => relation,
             :name => $4.to_s,
             :instance => $3.to_s,
             :device => $2.to_s,
@@ -182,8 +184,6 @@ module VirtualBox
 
     # Destroys the port forwarding mapping.
     #
-    # @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 destroy
       results = []
@@ -193,6 +193,9 @@ module VirtualBox
         results << parent.extra_data.delete("#{key_prefix(true)}GuestPort")
         results << parent.extra_data.delete("#{key_prefix(true)}HostPort")
 
+        # Remove it from any collection
+        parent_collection.delete(self, true) if parent_collection
+
         new_record!
       end
 
@@ -201,8 +204,9 @@ module VirtualBox
 
     # Relationship callback when added to a collection. This is automatically
     # called by any relationship collection when this object is added.
-    def added_to_relationship(parent)
-      write_attribute(:parent, parent)
+    def added_to_relationship(proxy)
+      write_attribute(:parent, proxy.parent)
+      write_attribute(:parent_collection, proxy)
     end
 
     # Returns the prefix to be used for the extra data key. Forwarded ports
@@ -216,4 +220,4 @@ module VirtualBox
       "VBoxInternal\/Devices\/#{device}\/#{instance}\/LUN#0\/Config\/#{name_value}\/"
     end
   end
-end
+end

data/lib/virtualbox/global.rb

@@ -42,10 +42,12 @@ module VirtualBox
     relationship :media, :Media, :lazy => true
     relationship :extra_data, :ExtraData, :lazy => true
     relationship :system_properties, :SystemProperties, :lazy => true
+    relationship :host, :Host, :lazy => true
+    relationship :dhcp_servers, :DHCPServer, :lazy => true
 
     @@global_data = nil
 
-    class <<self
+    class << self
       # Retrieves the global data. The return value of this call is cached,
       # and can be reloaded by setting the `reload` parameter to true. Besides
       # explicitly setting the parameter, some actions within the library
@@ -76,10 +78,19 @@ module VirtualBox
     end
 
     def load_relationship(name)
-      populate_relationship(:vms, lib.virtualbox.machines)
-      populate_relationship(:media, lib)
-      populate_relationship(:extra_data, lib.virtualbox)
-      populate_relationship(:system_properties, lib.virtualbox.system_properties)
+      # "Lazy loaded" associations table. These associate the relationship
+      # with the data it needs to load. The data is wrapped in lambdas so
+      # that the evaluation doesn't occur unless necessary.
+      relationships = {
+        :vms => lambda { lib.virtualbox.machines },
+        :media => lambda { lib },
+        :extra_data => lambda { lib.virtualbox },
+        :system_properties => lambda { lib.virtualbox.system_properties },
+        :host => lambda { lib.virtualbox.host },
+        :dhcp_servers => lambda { lib.virtualbox.dhcp_servers }
+      }
+
+      populate_relationship(name, relationships[name].call)
     end
   end
-end
+end

data/lib/virtualbox/hard_drive.rb

@@ -8,16 +8,18 @@ module VirtualBox
   #
   #     VirtualBox::HardDrive.all
   #
-  # Or:
+  # Or use find with the UUID of the HardDrive:
   #
-  #     VirtualBox::HardDrive.find("Foo.vdi")
+  #     VirtualBox::HardDrive.find("4a896f0b-b3a3-4dec-8c26-8406c6fccd6e")
   #
   # # Creating a Hard Drive
   #
-  # The hard drive is one of the few data items at the moment which supports
-  # new creation. Below is a simple example of how this works:
+  # Hard Drives can be created by intilizing an empty hard drive, assigning
+  # values to the necessary attributes, and calling save on the object.
+  # Below is a simple example of how this works:
   #
   #     hd = VirtualBox::HardDrive.new
+  #     hd.format = "VDI" # Or any format list with `VBoxManage list hddbackends`
   #     hd.location = "foo.vdi"
   #     hd.size = 2400 # in megabytes
   #     hd.save
@@ -26,38 +28,32 @@ module VirtualBox
   #     hd.uuid
   #     hd.location # will return a full path now
   #
-  # Although `VDI` is the default format for newly created hard drives, other
-  # formats are supported:
-  #
-  #     hd = VirtualBox::HardDrive.new
-  #     hd.format = "VMDK"
-  #     hd.location = "bar.vmdk"
-  #     hd.size = 9001 # Its over 9000! (If you don't understand the reference, just ignore this comment)
-  #     hd.save
-  #
-  # Any formats listed by your VirtualBox installation's `VBoxManage list hddbackends` command
-  # can be used with the virtualbox gem.
-  #
   # # Destroying Hard Drives
   #
-  # Hard drives can also be deleted, which will completely remove them from
-  # disk. **This operation is not reversable**.
+  # Hard drives can also be deleted. **This operation is not reversable**.
   #
-  #     hd = VirtualBox::HardDrive.find("foo")
+  #     hd = VirtualBox::HardDrive.find("...")
   #     hd.destroy
   #
+  # This will only unregister the Hard Drive from VirtualBox and will not destroy
+  # the storage space on the disk. To destroy the storage space, pass `true` to
+  # the destroy method, example:
+  #
+  #     hd.destroy(true)
+  #
   # # Cloning Hard Drives
   #
-  # Hard drives can just as easily be cloned as they can be created or destroyed.
+  # Hard Drives can just as easily be cloned as they can be created or destroyed.
   #
-  #     hd = VirtualBox::HardDrive.find("foo")
-  #     cloned_hd = hd.clone("bar")
+  #     hd = VirtualBox::HardDrive.find("...")
+  #     cloned_hd = hd.clone("bar.vdi")
   #
   # In addition to simply cloning hard drives, this command can be used to
-  # clone to a different format:
+  # clone to a different format. If the format is not passed in (as with the
+  # the above example, the system default format will be used). example:
   #
-  #     hd = VirtualBox::HardDrive.find("foo")
-  #     hd.clone("bar", "VMDK") # Will clone and convert to VMDK format
+  #     hd = VirtualBox::HardDrive.find("...")
+  #     hd.clone("bar.vmdk", "VMDK") # Will clone and convert to VMDK format
   #
   # # Attributes
   #
@@ -70,35 +66,38 @@ module VirtualBox
   # listed below. If you aren't sure what this means or you can't understand
   # why the below is listed, please read {Attributable}.
   #
-  #     attribute :format, :default => "VDI", :property => :format
-  #     attribute :logical_size, :property => :logical_size
+  #     attribute :format, :default => "VDI"
+  #     attribute :location
+  #     attribute :logical_size
   #     attribute :physical_size, :readonly => true, :property => :size
   #
   # There are more attributes on the {Medium} model, which {HardDrive} inherits
   # from.
+  #
   class HardDrive < Medium
     include ByteNormalizer
 
-    attribute :format, :default => "VDI", :property => :format
-    attribute :logical_size, :property => :logical_size
+    attribute :format, :default => "VDI"
+    attribute :location
+    attribute :logical_size
     attribute :physical_size, :readonly => true, :property => :size
 
-    class <<self
+    class << self
       # Returns an array of all available hard drives as HardDrive
       # objects.
       #
       # @return [Array<HardDrive>]
       def all
-        Global.global.media.hard_drives
+        Global.global(true).media.hard_drives
       end
 
-      # Finds one specific hard drive by UUID or file name. If the
-      # hard drive can not be found, will return `nil`.
+      # Finds one specific hard drive by UUID. If the hard drive
+      # can not be found, will return `nil`.
       #
       # @param [String] id The UUID of the hard drive
       # @return [HardDrive]
-      def find(id, raise_errors=false)
-        all.find { |hd| hd.uuid == id }
+      def find(id)
+        all.detect { |hd| hd.uuid == id }
       end
 
       # Override of {Medium.device_type}.
@@ -107,58 +106,118 @@ module VirtualBox
       end
     end
 
+    # Overwrite the AbstractModel initialize to make the imedium parameter
+    # optional so that new Hard Drives can be created
+    def initialize(imedium = nil)
+      super if imedium
+    end
+
     # Custom getter to convert the physical size from bytes to megabytes.
     def physical_size
       bytes_to_megabytes(read_attribute(:physical_size))
     end
 
-    # Clone hard drive, possibly also converting formats. All formats
-    # supported by your local VirtualBox installation are supported
-    # here. If no format is specified, the format of the source drive
-    # will be used.
+    # Get an array of machines attached to this Virtual Machine
+    def machines
+      interface.machine_ids.collect { |id| VirtualBox::VM.find(id) }
+    end
+
+    # Validates a hard drive for the minimum attributes required to
+    # create or save.
+    def validate
+      super
+
+      medium_formats = Global.global.system_properties.medium_formats.collect { |mf| mf.id }
+      validates_inclusion_of :format, :in => medium_formats, :message => "must be one of the following: #{medium_formats.join(', ')}."
+
+      validates_presence_of :location
+
+      max_vdi_size = Global.global.system_properties.max_vdi_size
+      validates_inclusion_of :logical_size, :in => (0..max_vdi_size), :message => "must be between 0 and #{max_vdi_size}."
+    end
+
+    # Creates a new {COM::Interface::Medium} instance. This simply creates
+    # the new {COM::Interface::Medium} structure. It does not (and shouldn't)
+    # create the storage space on the host system. See the create method for
+    # an example on to create the storage space.
     #
     # @param [String] outputfile The output file. This can be a full path
     #   or just a filename. If its just a filename, it will be placed in
-    #   the default hard drives directory.
-    # @param [String] format The format to convert to.
-    # @param [Boolean] raise_errors If true, {Exceptions::CommandFailedException}
-    #   will be raised if the command failed.
-    # @return [HardDrive] The new, cloned hard drive, or nil on failure.
-    def clone(outputfile, format="VDI")
+    #   the default hard drives directory. Should not be present already.
+    # @param [String] format The format to convert to. If not present, the
+    #   systems default will be used.
+    # @return [COM::Interface::Medium] The new {COM::Interface::Medium} instance
+    #   or will raise a {Exceptions::MediumCreationFailedException} on failure.
+    def create_hard_disk_medium(outputfile, format = nil)
       # Get main VirtualBox object
       virtualbox = Lib.lib.virtualbox
 
+      # Assign the default format if it isn't set yet
+      format ||= virtualbox.system_properties.default_hard_disk_format
+
       # Expand path relative to the default hard disk folder. This allows
       # filenames to exist in the default folder while full paths will use
       # the paths specified.
       outputfile = File.expand_path(outputfile, virtualbox.system_properties.default_hard_disk_folder)
 
-      # Create the new medium. This simply creates a new IMedium structure
+      # If the outputfile path is in use by another Hard Drive, lets fail
+      # now with a meaningful exception rather than simply return a nil
+      raise Exceptions::MediumLocationInUseException.new(outputfile) if File.exist?(outputfile)
+
+      # Create the new {COM::Interface::Medium} instance.
       new_medium = virtualbox.create_hard_disk(format, outputfile)
 
-      # Clone the current drive
+      # Raise an error if the creation of the {COM::Interface::Medium}
+      # instance failed
+      raise Exceptions::MediumCreationFailedException.new unless new_medium
+
+      # Return the new {COM::Interface::Medium} instance.
+      new_medium
+    end
+
+    # Clone hard drive, possibly also converting formats. All formats
+    # supported by your local VirtualBox installation are supported
+    # here. If no format is specified, the systems default will be used.
+    #
+    # @param [String] outputfile The output file. This can be a full path
+    #   or just a filename. If its just a filename, it will be placed in
+    #   the default hard drives directory. Should not be present already.
+    # @param [String] format The format to convert to. If not present, the
+    #   systems default will be used.
+    # @return [HardDrive] The new, cloned hard drive, or nil on failure.
+    def clone(outputfile, format = nil)
+      # Create the new Hard Disk medium
+      new_medium = create_hard_disk_medium(outputfile, format)
+
+      # Clone the current drive onto the new Hard Disk medium
       interface.clone_to(new_medium, :standard, nil).wait_for_completion(-1)
+
+      # Locate the newly cloned hard drive
+      self.class.find(new_medium.id) if new_medium.respond_to?(:id)
     end
 
     # Creates a new hard drive.
     #
     # **This method should NEVER be called. Call {#save} 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 create(raise_errors=false)
-      if !valid?
-        raise Exceptions::ValidationFailedException.new(errors) if raise_errors
-        return false
-      end
+    def create
+      return false unless new_record?
+      raise Exceptions::ValidationFailedException.new(errors) if !valid?
+
+      # Create the new Hard Disk medium
+      new_medium = create_hard_disk_medium(location, format)
 
-      # TODO
+      # Create the storage on the host system
+      new_medium.create_base_storage(logical_size, :standard).wait_for_completion(-1)
 
-      true
-    rescue Exceptions::CommandFailedException
-      raise if raise_errors
-      false
+      # Update the current Hard Drive instance with the uuid and
+      # other attributes assigned after storage was written
+      write_attribute(:interface, new_medium)
+      initialize_attributes(new_medium)
+
+      # If the uuid is present, then everything worked
+      uuid && !uuid.to_s.empty?
     end
 
     # Saves the hard drive object. If the hard drive is new,
@@ -168,16 +227,20 @@ module VirtualBox
     # Currently, **saving existing hard drives does nothing**.
     # This is a limitation of VirtualBox, rather than the library itself.
     #
-    # @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(raise_errors=false)
+    def save
+      return true if !new_record? && !changed?
+      raise Exceptions::ValidationFailedException.new(errors) if !valid?
+
       if new_record?
-        # Create a new hard drive
-        create(raise_errors)
+        create # Create a new hard drive
       else
-        super
+        # Mediums like Hard Drives are not updatable, they need to be recreated
+        # Because Hard Drives contain info and paritions, it's easier to error
+        # out now than try and do some complicated logic
+        msg = "Hard Drives cannot be updated. You need to create one from scratch."
+        raise Exceptions::MediumNotUpdatableException.new(msg)
       end
     end
   end
-end
+end

data/lib/virtualbox/host.rb

@@ -0,0 +1,71 @@
+module VirtualBox
+  # Represents information about the host machine. This includes
+  # information such as memory available, processors, dvds, network
+  # interfaces, etc.
+  #
+  # This information is different from system properties in that some
+  # parts represent data which is stored in the VirtualBox "registry"
+  # (such as the dvd drives, host only network interfaces, etc.)
+  class Host < AbstractModel
+    attribute :parent, :readonly => true, :property => false
+    attribute :interface, :readonly => true, :property => false
+    attribute :processor_count, :readonly => true
+    attribute :processor_online_count, :readonly => true
+    attribute :memory_size, :readonly => true
+    attribute :memory_available, :readonly => true
+    attribute :operating_system, :readonly => true
+    attribute :os_version, :readonly => true
+    attribute :utc_time, :readonly => true
+    attribute :acceleration_3d_available, :readonly => true
+    relationship :network_interfaces, :HostNetworkInterface
+
+    class << self
+      # Populates the system properties relationship for anything
+      # which is related to it.
+      #
+      # **This method typically won't be used except internally.**
+      #
+      # @return [SystemProperties]
+      def populate_relationship(caller, data)
+        new(caller, data)
+      end
+
+      # Saves the relationship. This simply calls {#save} on the
+      # relationship object.
+      #
+      # **This method typically won't be used except internally.**
+      def save_relationship(caller, item)
+        item.save
+      end
+    end
+
+    # Initializes the system properties object. This shouldn't be called
+    # directly. Instead `Global#system_properties` should be used to
+    # retrieve this object.
+    def initialize(caller, raw)
+      initialize_attributes(caller, raw)
+    end
+
+    # Initializes the attributes of an existing shared folder.
+    def initialize_attributes(caller, raw)
+      # Save the interface and parent
+      write_attribute(:parent, caller)
+      write_attribute(:interface, raw)
+
+      # Load the attributes from the interface
+      load_interface_attributes(interface)
+
+      # Get the relationships setup
+      populate_relationship(:network_interfaces, interface)
+
+      # Clear dirty and mark as existing
+      clear_dirty!
+      existing_record!
+    end
+
+    # Saves the system properties.
+    def save
+      save_changed_interface_attributes(interface)
+    end
+  end
+end

data/lib/virtualbox/host_network_interface.rb

@@ -0,0 +1,137 @@
+module VirtualBox
+  # Represents a network interface on the host. There are generally
+  # two types of network interfaces wihch exist on the host: bridged
+  # and host-only. This class represents both.
+  class HostNetworkInterface < AbstractModel
+    attribute :parent, :readonly => true, :property => false
+    attribute :parent_collection, :readonly => true, :property => false
+    attribute :interface, :readonly => true, :property => false
+    attribute :name, :readonly => true
+    attribute :uuid, :readonly => true, :property => :id
+    attribute :network_name, :readonly => true
+    attribute :dhcp_enabled, :readonly => true
+    attribute :ip_address, :readonly => true
+    attribute :network_mask, :readonly => true
+    attribute :ip_v6_supported, :readonly => true
+    attribute :ip_v6_address, :readonly => true
+    attribute :ip_v6_network_mask_prefix_length, :readonly => true
+    attribute :hardware_address, :readonly => true
+    attribute :medium_type, :readonly => true
+    attribute :status, :readonly => true
+    attribute :interface_type, :readonly => true
+
+    class << self
+      # Populates a relationship with another model.
+      #
+      # **This method typically won't be used except internally.**
+      #
+      # @return [Array<HostNetworkInterface>]
+      def populate_relationship(caller, ihost)
+        relation = Proxies::Collection.new(caller, self, ihost)
+
+        ihost.network_interfaces.each do |inet|
+          relation << new(inet)
+        end
+
+        relation
+      end
+
+      # Creates a host only network interface. This method should not
+      # be called directly. Instead, the `create` method on the
+      # `Global#host` relationship should be called instead. Example:
+      #
+      #     VirtualBox::Global.global.host.network_interfaces.create
+      #
+      # The above will create a host only network interface, add it to
+      # the collection, and will return the instance of the new
+      # interface.
+      def create(proxy, interface)
+        inet, progress = interface.create_host_only_network_interface
+        progress.wait
+
+        new(inet)
+      end
+    end
+
+    def initialize(inet)
+      initialize_attributes(inet)
+    end
+
+    def initialize_attributes(inet)
+      write_attribute(:interface, inet)
+
+      load_interface_attributes(inet)
+      existing_record!
+    end
+
+    def added_to_relationship(proxy)
+      write_attribute(:parent, proxy.parent)
+      write_attribute(:parent_collection, proxy)
+    end
+
+    # Gets the DHCP server associated with the network interface. Only
+    # host only network interfaces have dhcp servers. If a DHCP server
+    # doesn't exist for this network interface, one will be created.
+    def dhcp_server(create_if_not_found=true)
+      return nil if interface_type != :host_only
+
+      # Try to find the dhcp server in the list of DHCP servers.
+      dhcp_name = "HostInterfaceNetworking-#{name}"
+      result = parent.parent.dhcp_servers.find do |dhcp|
+        dhcp.network_name == dhcp_name
+      end
+
+      # If no DHCP server is found, create one
+      result = parent.parent.dhcp_servers.create(dhcp_name) if result.nil? && create_if_not_found
+      result
+    end
+
+    # Gets the VMs which have an adapter which is attached to this
+    # network interface.
+    def attached_vms
+      parent.parent.vms.find_all do |vm|
+        result = vm.network_adapters.find do |adapter|
+          adapter.host_interface == name
+        end
+
+        !result.nil?
+      end
+    end
+
+    # Sets up the static IPV4 configuration for the host only network
+    # interface. This allows the caller to set the IPV4 address of the
+    # interface as well as the netmask.
+    def enable_static(ip, netmask=nil)
+      netmask ||= network_mask
+
+      interface.enable_static_ip_config(ip, netmask)
+      reload
+    end
+
+    # Reloads the information regarding this host only network
+    # interface.
+    def reload
+      # Find the interface again and reload the data
+      inet = parent.interface.find_host_network_interface_by_id(uuid)
+      initialize_attributes(inet)
+      self
+    end
+
+    # Destroy the host only network interface. Warning: If any VMs are
+    # currently attached to this network interface, their networks
+    # will fail to work after removing this. Therefore, one should be
+    # careful to make sure to remove all VMs from this network prior
+    # to destroying it.
+    def destroy
+      return false if interface_type == :bridged
+
+      parent.interface.remove_host_only_network_interface(uuid).wait
+      dhcp_server.destroy if dhcp_server(false)
+
+      # Remove from collection
+      parent_collection.delete(self, true) if parent_collection
+
+      true
+    end
+  end
+end

data/lib/virtualbox/hw_virtualization.rb

@@ -4,13 +4,13 @@ module VirtualBox
     attribute :parent, :readonly => true, :property => false
     attribute_scope(:property_getter => Proc.new { |instance, *args| instance.get_property(*args) },
                     :property_setter => Proc.new { |instance, *args| instance.set_property(*args) }) do
-      attribute :enabled
-      attribute :exclusive
-      attribute :vpid
-      attribute :nested_paging
+      attribute :enabled, :boolean => true
+      attribute :exclusive, :boolean => true
+      attribute :vpid, :boolean => true
+      attribute :nested_paging, :boolean => true
     end
 
-    class <<self
+    class << self
       # Populates a relationship with another model.
       #
       # **This method typically won't be used except internally.**
@@ -45,6 +45,12 @@ module VirtualBox
       interface.set_hw_virt_ex_property(key, value)
     end
 
+    def validate
+      super
+
+      validates_inclusion_of :enabled, :exclusive, :vpid, :nested_paging, :in => [true, false]
+    end
+
     def save
       parent.with_open_session do |session|
         machine = session.machine
@@ -54,4 +60,4 @@ module VirtualBox
       end
     end
   end
-end
+end

data/lib/virtualbox/lib.rb

@@ -25,7 +25,7 @@ module VirtualBox
     attr_reader :virtualbox
     attr_reader :session
 
-    class <<self
+    class << self
       # Resets the initialized library (if there is any). This is primarily only
       # used for testing.
       def reset!
@@ -79,4 +79,4 @@ module VirtualBox
       @session = @interface.session
     end
   end
-end
+end

data/lib/virtualbox/media.rb

@@ -5,7 +5,7 @@ module VirtualBox
     relationship :hard_drives, :HardDrive
     relationship :dvds, :DVD
 
-    class <<self
+    class << self
       def populate_relationship(caller, lib)
         new(caller, lib)
       end
@@ -17,4 +17,4 @@ module VirtualBox
       populate_relationship(:dvds, lib.virtualbox.dvd_images)
     end
   end
-end
+end