virtualbox 0.7.1 → 0.7.2

data/VERSION

@@ -1 +1 @@
-0.7.1
+0.7.2

data/lib/virtualbox/abstract_model.rb

@@ -111,7 +111,6 @@ module VirtualBox
       # Go through and only save the loaded relationships, since
       # only those would be modified.
       self.class.relationships.each do |name, options|
-        next if lazy_relationship?(name) && !loaded_relationship?(name)
         save_relationship(name, *args)
       end
 
@@ -226,6 +225,16 @@ module VirtualBox
       end
     end
 
+    # Gets the root machine of an AbstractModel by traversing a
+    # `parent` attribute until it reaches a type of {VM}.
+    #
+    # @return [VM]
+    def parent_machine
+      current = parent
+      current = current.parent while current && !current.is_a?(VM)
+      current
+    end
+
     # Creates a human-readable format for this model. This method overrides the
     # default `#<class>` syntax since this doesn't work well for AbstractModels.
     # Instead, it abbreviates it, instead showing all the attributes and their

data/lib/virtualbox/abstract_model/attributable.rb

@@ -1,3 +1,5 @@
+require 'virtualbox/abstract_model/version_matcher'
+
 module VirtualBox
   class AbstractModel
     # Module which can be included into any other class which allows
@@ -37,6 +39,18 @@ module VirtualBox
     # The example above applies a default value to format. So if no value
     # is ever given to it, `format` would return `VDI`.
     #
+    # ## Attributes for a Specific VirtualBox Version
+    #
+    # Attributes change with different VirtualBox versions. One way to
+    # provide version-specific behavior is to specify the version
+    # which the attribute applies to.
+    #
+    #     attribute :name, :version => "3.2"
+    #     attribute :age, :version => "3.1"
+    #
+    # These versions only apply to major and minor releases of
+    # VirtualBox. Patch releases can't be specified (such as "3.2.4")
+    #
     # ## Populating Multiple Attributes
     #
     # Attributes can be mass populated using {#populate_attributes}. Below
@@ -118,6 +132,8 @@ module VirtualBox
     #     puts model.expensive_attribute # => 42
     #
     module Attributable
+      include VersionMatcher
+
       def self.included(base)
         base.extend ClassMethods
       end
@@ -224,13 +240,16 @@ module VirtualBox
       # if specified.
       def read_attribute(name)
         if has_attribute?(name)
+          options = self.class.attributes[name]
+
+          assert_version_match(options[:version], VirtualBox.version) if options[:version]
           if lazy_attribute?(name) && !loaded_attribute?(name)
             # Load the lazy attribute
             load_attribute(name.to_sym)
           end
 
           if attributes[name].nil?
-            self.class.attributes[name][:default]
+            options[:default]
           else
             attributes[name]
           end
@@ -268,4 +287,4 @@ module VirtualBox
       end
     end
   end
-end
+end

data/lib/virtualbox/abstract_model/interface_attributes.rb

@@ -23,6 +23,7 @@ module VirtualBox
         return unless has_attribute?(key)
         options = self.class.attributes[key.to_sym]
         return if options.has_key?(:property) && !options[:property]
+        return if options.has_key?(:version) && !version_match?(options[:version], VirtualBox.version)
         getter = options[:property] || options[:property_getter] || key.to_sym
         return unless getter
 
@@ -49,6 +50,7 @@ module VirtualBox
         options = self.class.attributes[key.to_sym]
         return if options[:readonly]
         return if options.has_key?(:property) && !options[:property]
+        return if options.has_key?(:version) && !version_match?(options[:version], VirtualBox.version)
 
         setter = options[:property] || options[:property_setter] || "#{key}=".to_sym
         return unless setter
@@ -93,4 +95,4 @@ module VirtualBox
       end
     end
   end
-end
+end

data/lib/virtualbox/abstract_model/relatable.rb

@@ -1,3 +1,5 @@
+require 'virtualbox/abstract_model/version_matcher'
+
 module VirtualBox
   class AbstractModel
     # Provides simple relationship features to any class. These relationships
@@ -119,6 +121,8 @@ module VirtualBox
     # relationship, it will first load the relationship, since destroy typically
     # depends on some data of the relationship.
     module Relatable
+      include VersionMatcher
+
       def self.included(base)
         base.extend ClassMethods
       end
@@ -181,6 +185,9 @@ module VirtualBox
       # Reads a relationship. This is equivalent to {Attributable#read_attribute},
       # but for relationships.
       def read_relationship(name)
+        options = self.class.relationships_hash[name.to_sym]
+        assert_version_match(options[:version], VirtualBox.version) if options[:version]
+
         if lazy_relationship?(name) && !loaded_relationship?(name)
           load_relationship(name)
         end
@@ -209,6 +216,8 @@ module VirtualBox
       # calls `save_relationship` on the relationship class.
       def save_relationship(name, *args)
         options = self.class.relationships_hash[name]
+        return if lazy_relationship?(name) && !loaded_relationship?(name)
+        return if options[:version] && !version_match?(options[:version], VirtualBox.version)
         return unless relationship_class(name).respond_to?(:save_relationship)
         relationship_class(name).save_relationship(self, relationship_data[name], *args)
       end
@@ -225,6 +234,7 @@ module VirtualBox
       def populate_relationship(name, data)
         options = self.class.relationships_hash[name]
         return unless relationship_class(name).respond_to?(:populate_relationship)
+        return if options[:version] && !version_match?(options[:version], VirtualBox.version)
         relationship_data[name] = relationship_class(name).populate_relationship(self, data)
       end
 
@@ -315,4 +325,4 @@ module VirtualBox
       end
     end
   end
-end
+end

data/lib/virtualbox/abstract_model/version_matcher.rb

@@ -0,0 +1,33 @@
+module VirtualBox
+  class AbstractModel
+    module VersionMatcher
+      # Asserts that two versions match. Otherwise raises an
+      # exception.
+      def assert_version_match(req, cur)
+        if !version_match?(req, cur)
+          message = "Required version: #{req}; Current: #{cur}"
+          raise Exceptions::UnsupportedVersionException.new(message)
+        end
+      end
+
+      # Checks if a given version requirement matches the current
+      # version.
+      #
+      # @return [Boolean]
+      def version_match?(requirement, current)
+        split_version(requirement) == split_version(current)
+      end
+
+      # Splits a version string into a two-item array with the parts
+      # of the version, respectively. If the version has more than two
+      # parts, the rest are ignored.
+      #
+      # @param [String] version
+      # @return [Array]
+      def split_version(version)
+        version.split(/\./)[0,2]
+      end
+    end
+  end
+end
+

data/lib/virtualbox/com/ffi/interfaces.rb

@@ -5,6 +5,9 @@ module VirtualBox
       # file should be conditionally loaded based on OS, so that Windows users
       # don't have to wait for all this translation to occur.
       def self.setup(version)
+        # TODO: This is so hacky and hard to maintain. Can we
+        # programatically get the modules in a namespace and
+        # instantiate them somehow?
         for_version version do
           create_interface(:NSISupports)
           create_interface(:NSIException, :NSISupports)
@@ -39,8 +42,13 @@ module VirtualBox
 
           create_interface(:HostUSBDevice, :USBDevice)
           create_interface(:HostUSBDeviceFilter, :USBDeviceFilter)
+
+          # 3.2.x interfaces
+          if version == "3.2.x"
+            create_interface(:NATEngine, :NSISupports)
+          end
         end
       end
     end
   end
-end
+end

data/lib/virtualbox/exceptions.rb

@@ -10,6 +10,7 @@ module VirtualBox
     class MediumCreationFailedException < Exception; end
     class MediumNotUpdatableException < Exception; end
     class ReadonlyVMStateException < Exception; end
+    class UnsupportedVersionException < Exception; end
 
     class FFIException < Exception
       attr_accessor :data
@@ -35,4 +36,4 @@ module VirtualBox
     class InvalidSessionStateException < FFIException; end
     class ObjectInUseException < FFIException; end
   end
-end
+end

data/lib/virtualbox/forwarded_port.rb

@@ -121,7 +121,7 @@ module VirtualBox
     # @param [Hash] data The initial attributes to populate.
     def initialize(data={})
       super()
-      populate_attributes(data)
+      populate_attributes(data) if !data.empty?
     end
 
     # Validates a forwarded port.

data/lib/virtualbox/nat_engine.rb

@@ -0,0 +1,71 @@
+module VirtualBox
+  # Represents a NAT engine for a given {NetworkAdapter}. This data is
+  # available through the `nat_driver` relationship on
+  # {NetworkAdapter} only if the adapter is a NAT adapter.
+  class NATEngine < AbstractModel
+    attribute :parent, :readonly => true, :property => false
+    attribute :network
+    attribute :tftp_prefix
+    attribute :tftp_boot_file
+    attribute :tftp_next_server
+    attribute :alias_mode
+    attribute :dns_pass_domain
+    attribute :dns_proxy
+    attribute :dns_use_host_resolver
+    attribute :interface, :readonly => true, :property => false
+    relationship :forwarded_ports, :NATForwardedPort
+
+    class << self
+      # Populates the NAT engine for anything which is related to it.
+      #
+      # **This method typically won't be used except internally.**
+      #
+      # @return [NATEngine]
+      def populate_relationship(caller, inat)
+        return nil if inat.nil?
+        new(caller, inat)
+      end
+
+      # Saves the relationship. This simply calls {#save} on every
+      # member of the relationship.
+      #
+      # **This method typically won't be used except internally.**
+      def save_relationship(caller, item)
+        item.save
+      end
+    end
+
+    def initialize(caller, inat)
+      super()
+      initialize_attributes(caller, inat)
+    end
+
+    # Initializes the attributes of an existing NAT engine.
+    def initialize_attributes(parent, inat)
+      write_attribute(:parent, parent)
+      write_attribute(:interface, inat)
+
+      # Load the interface attributes associated with this model
+      load_interface_attributes(inat)
+      populate_relationships(inat)
+
+      # Clear dirty and set as existing
+      clear_dirty!
+      existing_record!
+    end
+
+    def save
+      modify_engine do |nat|
+        save_changed_interface_attributes(nat)
+        save_relationships
+      end
+    end
+
+    # Helper method to get the mutable `INATEngine` interface.
+    def modify_engine
+      parent.modify_adapter do |adapter|
+        yield adapter.nat_driver
+      end
+    end
+  end
+end

data/lib/virtualbox/nat_forwarded_port.rb

@@ -0,0 +1,171 @@
+module VirtualBox
+  # When a VM uses NAT as its NIC type, VirtualBox acts like its
+  # own private router for all virtual machines. Because of this,
+  # the host machine can't access services within the guest machine.
+  # To get around this, NAT supports port forwarding, which allows the
+  # guest machine services to be forwarded to some port on the host
+  # machine. Port forwarding is done completely through {ExtraData}, but
+  # is a complicated enough procedure that this class was made to
+  # faciliate it.
+  #
+  # **Note:** After changing any forwarded ports, the entire VirtualBox
+  # process must be restarted completely for them to take effect. When
+  # working with the ruby library, this isn't so much of an issue, but
+  # if you have any VMs running, they must all be shut down and restarted.
+  #
+  # # Adding a new Forwarded Port
+  #
+  # Since forwarded ports rely on being part of a {VM}, we're going to
+  # assume that `vm` points to a {VM} which has already been found.
+  #
+  #     port = VirtualBox::NATForwardedPort.new
+  #     port.name = "apache" # This can be anything
+  #     port.guestport = 80
+  #     port.hostport = 8080
+  #     vm.network_adapters[0].nat_driver.forwarded_ports << port
+  #     port.save # Or vm.save
+  #
+  # # Modifying an Existing Forwarded Port
+  #
+  # This is assuming that `vm` is a local variable storing a {VM} object
+  # which has already been found.
+  #
+  #     ports = vm.network_adapters[0].nat_driver.forwarded_ports
+  #     ports.first.hostport = 1919
+  #     vm.save
+  #
+  # # Deleting a Forwarded Port
+  #
+  # To delete a forwarded port, you simply destroy it like any other model:
+  #
+  #     ports = vm.network_adapters[0].nat_driver.forwarded_ports
+  #     ports.first.destroy
+  #
+  # # Attributes and Relationships
+  #
+  # Properties of the model 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.
+  #
+  # These attributes can be accessed and modified via standard ruby-style
+  # `instance.attribute` and `instance.attribute=` methods. The attributes are
+  # listed below.
+  #
+  # Relationships are also accessed like attributes but can't be set. Instead,
+  # they are typically references to other objects such as an {AttachedDevice} which
+  # in turn have their own attributes which can be modified.
+  #
+  # ## Attributes
+  #
+  # This is copied directly from the class header, but lists all available
+  # attributes. If you don't understand what this means, read {Attributable}.
+  #
+  #     attribute :parent, :readonly => true
+  #     attribute :name
+  #     attribute :protocol, :default => "TCP"
+  #     attribute :guestport
+  #     attribute :hostport
+  #
+  class NATForwardedPort < AbstractModel
+    attribute :parent, :readonly => true, :property => false
+    attribute :parent_collection, :readonly => true, :property => false
+    attribute :name
+    attribute :protocol, :default => :tcp
+    attribute :guestport
+    attribute :hostport
+
+    class << self
+      # Populates a relationship with another model.
+      #
+      # **This method typically won't be used except internally.**
+      #
+      # @return [Array<NATForwardedPort>]
+      def populate_relationship(caller, interface)
+        relation = Proxies::Collection.new(caller)
+
+        interface.redirects.each do |key, value|
+          parts = key.split(",")
+
+          port = new({
+            :parent => caller,
+            :parent_collection => relation,
+            :name => parts[0],
+            :protocol => COM::Util.versioned_interface(:NATProtocol).index(parts[1]),
+            :guestport => parts[5],
+            :hostport => parts[3]
+          })
+
+          port.existing_record!
+
+          relation.push(port)
+        end
+
+        relation
+      end
+
+      # Saves the relationship. This simply calls {#save} on every
+      # member of the relationship.
+      #
+      # **This method typically won't be used except internally.**
+      def save_relationship(caller, data)
+        data.dup.each do |fp|
+          fp.save
+        end
+      end
+    end
+
+    # @param [Hash] data The initial attributes to populate.
+    def initialize(data={})
+      super()
+      populate_attributes(data) if !data.empty?
+    end
+
+    # Validates a forwarded port.
+    def validate
+      super
+
+      validates_presence_of :parent
+      validates_presence_of :name
+      validates_presence_of :guestport
+      validates_presence_of :hostport
+    end
+
+    # Saves the forwarded port.
+    #
+    # @return [Boolean] True if command was successful, false otherwise.
+    def save
+      return true if !new_record? && !changed?
+      raise Exceptions::ValidationFailedException.new(errors) if !valid?
+      destroy if !new_record?
+
+      parent.modify_engine do |nat|
+        nat.add_redirect(name, protocol, "", hostport, "", guestport)
+      end
+
+      clear_dirty!
+      existing_record!
+      true
+    end
+
+    # Destroys the port forwarding mapping.
+    #
+    # @return [Boolean] True if command was successful, false otherwise.
+    def destroy
+      return if new_record?
+      previous_name = name_changed? ? name_was : name
+      parent.modify_engine do |nat|
+        nat.remove_redirect(previous_name)
+      end
+      parent_collection.delete(self, true) if parent_collection
+      new_record!
+      true
+    end
+
+    # Relationship callback when added to a collection. This is automatically
+    # called by any relationship collection when this object is added.
+    def added_to_relationship(proxy)
+      write_attribute(:parent, proxy.parent)
+      write_attribute(:parent_collection, proxy)
+    end
+  end
+end