bbrowning-virtualbox 0.7.6.dev

data/lib/virtualbox/medium_attachment.rb

@@ -0,0 +1,61 @@
+module VirtualBox
+  # Represents the attachment of a medium (DVD, Hard Drive, etc) to a
+  # virtual machine, and specifically to a {StorageController}.
+  class MediumAttachment < AbstractModel
+    attribute :parent, :readonly => true, :property => false
+    attribute :controller_name, :readonly => :true, :property => :controller
+    attribute :port, :readonly => true
+    attribute :device, :readonly => true
+    attribute :passthrough, :readonly => true
+    attribute :type, :readonly => true
+    relationship :medium, :Medium
+    relationship :storage_controller, :StorageController
+
+    class << self
+      # Populates a relationship with another model.
+      #
+      # **This method typically won't be used except internally.**
+      #
+      # @return [Array<MediumAttachment>]
+      def populate_relationship(caller, imachine)
+        relation = Proxies::Collection.new(caller)
+
+        imachine.medium_attachments.each do |ima|
+          relation << new(caller, ima)
+        end
+
+        relation
+      end
+    end
+
+    def initialize(parent, imedium_attachment)
+      populate_attributes({:parent => parent}, :ignore_relationships => true)
+      initialize_attributes(imedium_attachment)
+    end
+
+    def initialize_attributes(ima)
+      load_interface_attributes(ima)
+      populate_relationship(:medium, ima.medium)
+      populate_relationship(:storage_controller, self)
+    end
+
+    # Detaches the medium from it's parent virtual machine. Note that this
+    # **does not delete** the `medium` which this attachment references; it
+    # merely removes the assocation of said medium with this attachment's
+    # virtual machine.
+    def detach
+      parent.with_open_session do |session|
+        machine = session.machine
+
+        machine.detach_device(storage_controller.name, port, device)
+      end
+    end
+
+    # Destroy this medium attachment. This simply detaches the medium attachment.
+    # This will also delete the medium if that option is specified.
+    def destroy(opts={})
+      detach
+      medium.destroy(opts[:destroy_medium] == :delete) if opts[:destroy_medium] && medium
+    end
+  end
+end

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].to_i,
+            :hostport => parts[3].to_i
+          })
+
+          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(false) 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(update_collection=true)
+      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 && update_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

data/lib/virtualbox/network_adapter.rb

@@ -0,0 +1,166 @@
+module VirtualBox
+  # Represents a single NIC (Network Interface Card) of a virtual machine.
+  #
+  # # Create a Network Adapter
+  #
+  # There is no need to have the ability to create a network adapter,
+  # since when creating a VM from scratch, all eight network adapter
+  # slots are created, but set to `attachment_type` `nil`. Simply
+  # modify the adapter you're interested in and save.
+  #
+  #
+  # # Editing a Network Adapter
+  #
+  # Network adapters can be modified directly in their relationship to other
+  # virtual machines. When {VM#save} is called, it will also save any
+  # changes to its relationships. Additionally, you may call {#save}
+  # on the relationship itself.
+  #
+  #     vm = VirtualBox::VM.find("foo")
+  #     vm.network_adapters[0].macaddress = @new_mac_address
+  #     vm.save
+  #
+  # # Destroying a Network Adapter
+  #
+  # Network adapters can not actually be "destroyed" but can be
+  # removed by setting the `attachment_type` to `nil` and saving.
+  #
+  # # Attributes
+  #
+  # 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. If you aren't sure what this means or you can't understand
+  # why the below is listed, please read {Attributable}.
+  #
+  #     attribute :slot, :readonly => true
+  #     attribute :enabled, :boolean => true
+  #     attribute :attachment_type
+  #     attribute :adapter_type
+  #     attribute :mac_address
+  #     attribute :cable_connected, :boolean => true
+  #     attribute :nat_network
+  #     attribute :internal_network
+  #     attribute :host_interface
+  #     attribute :interface, :readonly => true, :property => false
+  #
+  class NetworkAdapter < AbstractModel
+    attribute :parent, :readonly => true, :property => false
+    attribute :slot, :readonly => true
+    attribute :enabled, :boolean => true
+    attribute :attachment_type
+    attribute :adapter_type
+    attribute :mac_address
+    attribute :cable_connected, :boolean => true
+    attribute :nat_network
+    attribute :internal_network
+    attribute :host_interface
+    attribute :interface, :readonly => true, :property => false
+    relationship :nat_driver, :NATEngine, :version => "3.2", :lazy => true
+
+    class << self
+      # Populates the nic relationship for anything which is related to it.
+      #
+      # **This method typically won't be used except internally.**
+      #
+      # @return [Array<Nic>]
+      def populate_relationship(caller, imachine)
+        relation = Proxies::Collection.new(caller)
+
+        # Get the count of network adapters
+        count = imachine.parent.system_properties.network_adapter_count
+
+        count.times do |i|
+          relation << new(caller, imachine.get_network_adapter(i))
+        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, items)
+        items.each do |item|
+          item.save
+        end
+      end
+    end
+
+    def initialize(caller, inetwork)
+      super()
+
+      initialize_attributes(caller, inetwork)
+    end
+
+    # Initializes the attributes of an existing shared folder.
+    def initialize_attributes(parent, inetwork)
+      # Set the parent and interface
+      write_attribute(:parent, parent)
+      write_attribute(:interface, inetwork)
+
+      # Load the interface attributes
+      load_interface_attributes(inetwork)
+
+      # Clear dirtiness, since this should only be called initially and
+      # therefore shouldn't affect dirtiness
+      clear_dirty!
+
+      # But this is an existing record
+      existing_record!
+    end
+
+    def load_relationship(name)
+      # Lazy load the NAT driver. This is only supported by VirtualBox
+      # 3.2 and higher. This restriction is checked when the
+      # relationship attribute is accessed.
+      populate_relationship(:nat_driver, interface.nat_driver)
+    end
+
+    # Gets the host interface object associated with the class if it
+    # exists.
+    def host_interface_object
+      VirtualBox::Global.global.host.network_interfaces.find do |ni|
+        ni.name == host_interface
+      end
+    end
+
+    # Save a network adapter.
+    def save
+      modify_adapter do |adapter|
+        save_attachment_type(adapter)
+        save_changed_interface_attributes(adapter)
+        save_relationships
+      end
+    end
+
+    # Saves the attachment type. This should never be called directly. Instead,
+    # {save} should be called, which will call this method if appropriate.
+    def save_attachment_type(adapter)
+      return unless attachment_type_changed?
+
+      mapping = {
+        :nat => :attach_to_nat,
+        :bridged => :attach_to_bridged_interface,
+        :internal => :attach_to_internal_network,
+        :host_only => :attach_to_host_only_interface
+      }
+
+      adapter.send(mapping[attachment_type])
+      clear_dirty!(:attachment_type)
+    end
+
+    # Opens a session, yields the adapter and then saves the machine at
+    # the end
+    def modify_adapter
+      parent_machine.with_open_session do |session|
+        machine = session.machine
+        yield machine.get_network_adapter(slot)
+      end
+    end
+  end
+end