virtualbox 0.5.4 → 0.6.0

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/network_adapter.rb

@@ -0,0 +1,134 @@
+module VirtualBox
+  # Represents a single NIC (Network Interface Card) of a virtual machine.
+  #
+  # **Currently, new NICs can't be created, so the only way to get this
+  # object is through a {VM}'s `nics` relationship.**
+  #
+  # # Editing a NIC
+  #
+  # Nics 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.
+  #
+  #     vm = VirtualBox::VM.find("foo")
+  #     vm.nics[0].macaddress = @new_mac_address
+  #     vm.save
+  #
+  # # 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 :parent, :readonly => :readonly
+  #     attribute :nic
+  #     attribute :nictype
+  #     attribute :macaddress
+  #     attribute :cableconnected
+  #     attribute :bridgeadapter
+  #
+  class NetworkAdapter < AbstractModel
+    attribute :parent, :readonly => true, :property => false
+    attribute :slot, :readonly => true
+    attribute :enabled
+    attribute :attachment_type
+    attribute :adapter_type
+    attribute :mac_address
+    attribute :cable_connected
+    attribute :nat_network
+    attribute :internal_network
+    attribute :host_interface
+    attribute :interface, :readonly => true, :property => false
+
+    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
+
+    # Save a network adapter.
+    def save
+      modify_adapter do |adapter|
+        save_attachment_type(adapter)
+        save_changed_interface_attributes(adapter)
+      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.with_open_session do |session|
+        machine = session.machine
+        yield machine.get_network_adapter(slot)
+      end
+    end
+  end
+end

data/lib/virtualbox/shared_folder.rb

@@ -85,9 +85,11 @@ module VirtualBox
   #     attribute :hostpath
   #
   class SharedFolder < AbstractModel
-    attribute :parent, :readonly => :readonly
+    attribute :parent, :readonly => true, :property => false
     attribute :name
-    attribute :hostpath
+    attribute :host_path
+    attribute :writable, :default => true
+    attribute :accessible, :readonly => true
 
     class <<self
       # Populates the shared folder relationship for anything which is related to it.
@@ -95,13 +97,11 @@ module VirtualBox
       # **This method typically won't be used except internally.**
       #
       # @return [Array<SharedFolder>]
-      def populate_relationship(caller, doc)
+      def populate_relationship(caller, imachine)
         relation = Proxies::Collection.new(caller)
 
-        counter = 1
-        doc.css("Hardware SharedFolders SharedFolder").each do |folder|
-          relation << new(counter, caller, folder)
-          counter += 1
+        imachine.shared_folders.each do |ishared|
+          relation << new(caller, ishared)
         end
 
         relation
@@ -111,10 +111,9 @@ module VirtualBox
       # member of the relationship.
       #
       # **This method typically won't be used except internally.**
-      def save_relationship(caller, data)
-        # Just call save on each folder with the VM
-        data.each do |sf|
-          sf.save
+      def save_relationship(caller, items)
+        items.each do |item|
+          item.save
         end
       end
     end
@@ -127,51 +126,31 @@ module VirtualBox
     # @overload initialize(index, caller, data)
     #   Creates an SharedFolder for a relationship. **This should
     #   never be called except internally.**
-    #   @param [Integer] index Index of the shared folder
     #   @param [Object] caller The parent
     #   @param [Hash] data A hash of data which must be used
     #     to extract the relationship data.
     def initialize(*args)
       super()
 
-      if args.length == 3
-        initialize_for_relationship(*args)
-      elsif args.length == 1
-        initialize_for_data(*args)
-      elsif args.length == 0
-        return
-      else
-        raise NoMethodError.new
+      if args.length == 2
+        initialize_attributes(*args)
       end
     end
 
-    # Initializes the record for use in a relationship. This
-    # is automatically called by {#initialize} if it has three
-    # parameters.
-    #
-    # **This method typically won't be used except internally.**
-    def initialize_for_relationship(index, caller, data)
-      # Setup the index specific attributes
-      populate_data = {}
-      data.attributes.each do |key, value|
-        populate_data[key.downcase.to_sym] = value.to_s
-      end
+    # Initializes the attributes of an existing shared folder.
+    def initialize_attributes(parent, ishared)
+      # Set the parent
+      write_attribute(:parent, parent)
 
-      populate_attributes(populate_data.merge({
-        :parent => caller
-      }))
-    end
+      # Load the interface attributes
+      load_interface_attributes(ishared)
 
-    # Initializes a record with initial data but keeping it a "new
-    # record." This is called automatically if {#initialize} is given
-    # only a single parameter. View {#initialize} for documentation.
-    def initialize_for_data(data)
-      self.class.attributes.each do |name, options|
-        data[options[:populate_key]] = data[name]
-      end
+      # Clear dirtiness, since this should only be called initially and
+      # therefore shouldn't affect dirtiness
+      clear_dirty!
 
-      populate_attributes(data)
-      new_record!
+      # But this is an existing record
+      existing_record!
     end
 
     # Validates a shared folder.
@@ -180,33 +159,35 @@ module VirtualBox
 
       validates_presence_of :parent
       validates_presence_of :name
-      validates_presence_of :hostpath
+      validates_presence_of :host_path
     end
 
     # Saves or creates a shared folder.
-    #
-    # @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)
-      return true unless changed?
-
-      if !valid?
-        raise Exceptions::ValidationFailedException.new(errors) if raise_errors
-        return false
+    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
       end
 
-      # If this isn't a new record, we destroy it first
-      destroy(raise_errors) if !new_record?
+      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.with_open_session do |session|
+        machine = session.machine
+        machine.create_shared_folder(name, host_path, writable)
+      end
 
-      Command.vboxmanage("sharedfolder", "add", parent.name, "--name", name, "--hostpath", hostpath)
       existing_record!
       clear_dirty!
-
-      true
-    rescue Exceptions::CommandFailedException
-      raise if raise_errors
-      false
     end
 
     # Relationship callback when added to a collection. This is automatically
@@ -219,20 +200,14 @@ module VirtualBox
     # 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.
-    #
-    # @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(raise_errors=false)
-      # If the name changed, we have to be sure to use the previous
-      # one.
-      name_value = name_changed? ? name_was : name
-
-      Command.vboxmanage("sharedfolder", "remove", parent.name, "--name", name_value)
-      true
-    rescue Exceptions::CommandFailedException
-      raise if raise_errors
-      false
-    end
+    def destroy
+      parent.with_open_session do |session|
+        machine = session.machine
+        machine.remove_shared_folder(name)
+      end
+
+      # Mark as a new record so if it is saved again, it will create it
+      new_record!
+   end
   end
 end

data/lib/virtualbox/storage_controller.rb

@@ -40,11 +40,12 @@ module VirtualBox
   #     relationship :devices, AttachedDevice, :dependent => :destroy
   #
   class StorageController < AbstractModel
-    attribute :parent, :readonly => true
-    attribute :name
-    attribute :type
-    attribute :ports, :populate_key => :portcount
-    relationship :devices, AttachedDevice, :dependent => :destroy
+    attribute :parent, :readonly => true, :property => false
+    attribute :interface, :readonly => true, :property => false
+    attribute :name, :readonly => true
+    attribute :port_count
+    attribute :bus, :readonly => true
+    attribute :controller_type
 
     class <<self
       # Populates a relationship with another model.
@@ -52,18 +53,41 @@ module VirtualBox
       # **This method typically won't be used except internally.**
       #
       # @return [Array<StorageController>]
-      def populate_relationship(caller, doc)
+      def populate_relationship(caller, data)
+        if data.is_a?(COM::Interface::Machine)
+          populate_array_relationship(caller, data)
+        elsif data.is_a?(MediumAttachment)
+          populate_attachment_relationship(caller, data)
+        end
+      end
+
+      # Populates a has many relationship for a {VM}.
+      #
+      # **This method typically won't be used except internally.**
+      #
+      # @return [Array<StorageController>]
+      def populate_array_relationship(caller, imachine)
         relation = Proxies::Collection.new(caller)
 
-        counter = 0
-        doc.css("StorageControllers StorageController").each do |sc|
-          relation << new(counter, caller, sc)
-          counter += 1
+        imachine.storage_controllers.each do |icontroller|
+          relation << new(caller, icontroller)
         end
 
         relation
       end
 
+      # Populates a single relationship for a {MediumAttachment}.
+      #
+      # **This method typically won't be used except internally.**
+      #
+      # @return [Array<StorageController>]
+      def populate_attachment_relationship(caller, attachment)
+        # Find the storage controller with the matching name
+        attachment.parent.storage_controllers.find do |sc|
+          sc.name == attachment.controller_name
+        end
+      end
+
       # Destroys a relationship with another model.
       #
       # **This method typically won't be used except internally.**
@@ -75,8 +99,8 @@ module VirtualBox
       # member of the relationship.
       #
       # **This method typically won't be used except internally.**
-      def save_relationship(caller, data)
-        data.each do |sc|
+      def save_relationship(caller, controllers)
+        controllers.each do |sc|
           sc.save
         end
       end
@@ -86,19 +110,51 @@ module VirtualBox
     # this method shouldn't be called. Instead, storage controllers
     # can be retrieved through relationships of other models such
     # as {VM}.
-    def initialize(index, caller, data)
+    def initialize(caller, icontroller)
       super()
 
-      @index = index
+      populate_attributes({
+        :parent => caller,
+        :interface => icontroller
+      }, :ignore_relationships => true)
+      load_interface_attributes(icontroller)
+      clear_dirty!
+    end
 
-      # Setup the index specific attributes
-      populate_data = {}
-      data.attributes.each do |key,value|
-        populate_data[key.downcase.to_sym] = value.to_s
+    # Retrieves the array of medium attachments related to this storage controller.
+    # This is not implemented as a relationship simply because it would have been
+    # difficult to do so (circular) and its not really necessary.
+    def medium_attachments
+      parent.medium_attachments.find_all do |ma|
+        ma.storage_controller == self
       end
+    end
 
-      populate_attributes(populate_data.merge({:parent => caller}), :ignore_relationships => true)
-      populate_relationship(:devices, data)
+    # Saves the storage controller. This method shouldn't be called directly.
+    # Instead, {VM#save} should be called, which will save all attached storage
+    # controllers as well. This will setup the proper parameter for `interface`
+    # here.
+    def save
+      parent.with_open_session do |session|
+        machine = session.machine
+        save_changed_interface_attributes(machine.get_storage_controller_by_name(name))
+      end
+    end
+
+    # Destroys the storage controller. This first detaches all attachments on this
+    # storage controller. Note that this does *not* delete the media on the attachments,
+    # unless specified by the options.
+    def destroy(*args)
+      # First remove all attachments
+      medium_attachments.each do |ma|
+        ma.destroy(*args)
+      end
+
+      # Finally, remove ourselves
+      parent.with_open_session do |session|
+        machine = session.machine
+        machine.remove_storage_controller(name)
+      end
     end
   end
 end