velir_virtualbox 0.8.4

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, :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

data/lib/virtualbox/proxies/collection.rb

@@ -0,0 +1,57 @@
+module VirtualBox
+  module Proxies
+    # A relationship which can be described as a collection, which
+    # is a set of items.
+    class Collection < Array
+      attr_reader :parent
+
+      def initialize(parent, item_klass=nil, *args)
+        super()
+
+        @parent = parent
+        @item_klass = item_klass
+        @other = args
+      end
+
+      # Creates a new item for this collection and returns the
+      # instance. The item is automatically put into this
+      # collection. `create` happens immediately, meaning that even
+      # without a `save`, the item will already exist.
+      def create(*args)
+        item =  nil
+
+        if @item_klass.respond_to?(:create)
+          args = @other + args
+          item = @item_klass.create(self, *args)
+          self << item
+        end
+
+        item
+      end
+
+      # Returns the errors associated with all the items in this
+      # collection
+      def errors
+        collect do |item|
+          item.respond_to?(:errors) ? item.errors : {}
+        end
+      end
+
+      def <<(item)
+        item.added_to_relationship(self) if item.respond_to?(:added_to_relationship)
+        push(item)
+      end
+
+      def clear
+        each do |item|
+          delete(item)
+        end
+      end
+
+      def delete(item, no_callback=false)
+        return unless super(item)
+        item.removed_from_relationship(self) if !no_callback && item.respond_to?(:removed_from_relationship)
+      end
+    end
+  end
+end

data/lib/virtualbox/shared_folder.rb

@@ -0,0 +1,220 @@
+module VirtualBox
+  # Represents a shared folder in VirtualBox. In VirtualBox, shared folders are a
+  # method for basically "symlinking" a folder on the guest system to a folder which
+  # exists on the host system. This allows for sharing of files across the virtual
+  # machine.
+  #
+  # **Note:** Whenever modifying shared folders on a VM, the changes won't take
+  # effect until a _cold reboot_ occurs. This means actually closing the virtual
+  # machine _completely_, then restarting it. You can't just hit "Start > Restart"
+  # or do a `sudo reboot`. It doesn't work that way!
+  #
+  # # Getting Shared Folders
+  #
+  # All shared folders are attached to a {VM} object, by definition. Therefore, to
+  # get a list of the shared folders, first {VM.find find} the VM you need, then
+  # use the `shared_folders` relationship to access an array of the shared folders.
+  # With this array, you can create, modify, update, and delete the shared folders
+  # for that virtual machine.
+  #
+  # # Creating a Shared Folder
+  #
+  # **This whole section will assume you already looked up a {VM} and assigned it to
+  # a local variable named `vm`.**
+  #
+  # With a VM found, creating a shared folder is just a few lines of code:
+  #
+  #     folder = VirtualBox::SharedFolder.new
+  #     folder.name = "desktop-images"
+  #     folder.hostpath = File.expand_path("~/Desktop/images")
+  #     vm.shared_folders << folder
+  #     folder.save # Or you can call vm.save, which works too!
+  #
+  # # Modifying an Existing Shared Folder
+  #
+  # **This whole section will assume you already looked up a {VM} and assigned it to
+  # a local variable named `vm`.**
+  #
+  # Nothing tricky here: You treat existing shared folder objects just as if they
+  # were new ones. Assign a new name and/or a new path, then save.
+  #
+  #     folder = vm.shared_folders.first
+  #     folder.name = "rufus"
+  #     folder.save # Or vm.save
+  #
+  # **Note**: The VirtualBox-saavy will know that VirtualBox doesn't actually
+  # expose a way to edit shared folders. Under the hood, the virtualbox ruby
+  # library is actually deleting the old shared folder, then creating a new
+  # one with the new details. This shouldn't affect the way anything works for
+  # the VM itself.
+  #
+  # # Deleting a Shared Folder
+  #
+  # **This whole section will assume you already looked up a {VM} and assigned it to
+  # a local variable named `vm`.**
+  #
+  #     folder = vm.shared_folder.first
+  #     folder.destroy
+  #
+  # Poof! It'll be gone. This is usually the place where I warn you about this
+  # being non-reversable, but since no _data_ was actually destroyed, this is
+  # not too risky. You could always just recreate the shared folder with the
+  # same name and path and it'll be like nothing happened.
+  #
+  # # 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 => :readonly
+  #     attribute :name
+  #     attribute :hostpath
+  #
+  class SharedFolder < AbstractModel
+    attribute :parent, :readonly => true, :property => false
+    attribute :parent_collection, :readonly => true, :property => false
+    attribute :name
+    attribute :host_path
+    attribute :writable, :default => true, :boolean => true
+    attribute :accessible, :readonly => true, :boolean => true
+
+    class << self
+      # Populates the shared folder relationship for anything which is related to it.
+      #
+      # **This method typically won't be used except internally.**
+      #
+      # @return [Array<SharedFolder>]
+      def populate_relationship(caller, imachine)
+        relation = Proxies::Collection.new(caller)
+
+        imachine.shared_folders.each do |ishared|
+          relation << new(ishared)
+        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.dup.each do |item|
+          item.save
+        end
+      end
+    end
+
+    # @overload initialize(data={})
+    #   Creates a new SharedFolder which is a new record. This
+    #   should be attached to a VM and saved.
+    #   @param [Hash] data (optional) A hash which contains initial attribute
+    #     values for the SharedFolder.
+    # @overload initialize(interface)
+    #   Creates an SharedFolder for a relationship. **This should
+    #   never be called except internally.**
+    #   @param [Object] caller The parent
+    #   @param [Hash] data A hash of data which must be used
+    #     to extract the relationship data.
+    def initialize(data=nil)
+      super()
+
+      if data
+        initialize_attributes(data)
+      end
+    end
+
+    # Initializes the attributes of an existing shared folder.
+    def initialize_attributes(ishared)
+      # Load the interface attributes
+      load_interface_attributes(ishared)
+
+      # 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
+
+    # Validates a shared folder.
+    def validate
+      super
+
+      validates_presence_of :parent
+      validates_presence_of :name
+      validates_presence_of :host_path
+    end
+
+    # Saves or creates a shared folder.
+    def save
+      return true if !new_record? && !changed?
+      raise Exceptions::ValidationFailedException.new(errors) if !valid?
+
+      if !new_record?
+        # If its not a new record, any changes will require a new shared
+        # folder to be created, so we first destroy it then recreate it.
+        destroy(false)
+      end
+
+      create
+    end
+
+    # Creates a new shared folder. This method should not be called directly.
+    # Instead, {save} should always be called, which will do the right thing.
+    def create
+      return unless new_record?
+
+      parent_machine.with_open_session do |session|
+        machine = session.machine
+        machine.create_shared_folder(name, host_path, writable)
+      end
+
+      existing_record!
+      clear_dirty!
+    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)
+      was_clean = parent.nil? && !changed?
+
+      write_attribute(:parent, proxy.parent)
+      write_attribute(:parent_collection, proxy)
+
+      # This keeps existing records not dirty when added to collection
+      clear_dirty! if !new_record? && was_clean
+    end
+
+    # Destroys the shared folder. This doesn't actually delete the folder
+    # from the host system. Instead, it simply removes the mapping to the
+    # virtual machine, meaning it will no longer be possible to mount it
+    # from within the virtual machine.
+    def destroy(update_collection=true)
+      parent.with_open_session do |session|
+        machine = session.machine
+        machine.remove_shared_folder(name)
+      end
+
+      # Remove it from it's parent collection
+      parent_collection.delete(self, true) if parent_collection && update_collection
+
+      # Mark as a new record so if it is saved again, it will create it
+      new_record!
+   end
+  end
+end