velir_virtualbox 0.8.4

data/lib/virtualbox/global.rb

@@ -0,0 +1,96 @@
+module VirtualBox
+  # Represents the VirtualBox main configuration file (VirtualBox.xml)
+  # which VirtualBox uses to keep track of all known virtual machines
+  # and images. This "global" configuration has many relationships which
+  # allow the user to retrieve a list of all VMs, media, global extra data,
+  # etc. Indeed, even methods like {VM.all} are implemented using this class.
+  #
+  # # Getting Global Data
+  #
+  # To retrieve the global data, use `Global.global`. This value is _cached_
+  # between calls, so subsequent calls will not go through the entire parsing
+  # process. To force a reload, set the `reload` parameter to true. Besides
+  # setting the parameter explicitly, some actions will implicitly force the
+  # global data to reload on the next call, such as saving a VM or destroying
+  # an image, for example.
+  #
+  #     # Retrieve global data for the first time. This will parse all the
+  #     # data.
+  #     global_object = VirtualBox::Global.global
+  #
+  #     # Subsequent calls are near-instant:
+  #     VirtualBox::Global.global
+  #
+  #     # Or we can choose to reload the data...
+  #     reloaded_object = VirtualBox::Global.global(true)
+  #
+  # # Relationships
+  #
+  # While a global object doesn't have attributes, it does have many
+  # relationships. The relationships are listed below. If you don't
+  # understand this, read {Relatable}.
+  #
+  #     relationship :vms, VM
+  #     relationship :media, Media
+  #     relationship :extra_data, ExtraData
+  #     relationship :system_properties, :SystemProperties, :lazy => true
+  #
+  class Global < AbstractModel
+    attribute :lib, :readonly => true
+
+    relationship :vms, :VM, :lazy => true
+    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
+      # 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
+      # force global to reload itself on the next call, such as saving a VM,
+      # or destroying an image.
+      #
+      # @param [Boolean] reload True if you want to force a reload of the data.
+      # @return [Global]
+      def global(reload=false)
+        if !@@global_data || reload
+          @@global_data = new(Lib.lib)
+        end
+
+        @@global_data
+      end
+
+      # Resets the global data singleton. This is used for testing purposes.
+      def reset!
+        @@global_data = nil
+      end
+    end
+
+    def initialize(lib)
+      write_attribute(:lib, lib)
+
+      # Required to load lazy relationships
+      existing_record!
+    end
+
+    def load_relationship(name)
+      # "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

data/lib/virtualbox/hard_drive.rb

@@ -0,0 +1,246 @@
+module VirtualBox
+  # Represents a hard disk which is registered with VirtualBox.
+  #
+  # # Finding a Hard Drive
+  #
+  # Hard drives can be found use {HardDrive.all} and {HardDrive.find}, which
+  # find all or a specific hard drive, respectively. Example below:
+  #
+  #     VirtualBox::HardDrive.all
+  #
+  # Or use find with the UUID of the HardDrive:
+  #
+  #     VirtualBox::HardDrive.find("4a896f0b-b3a3-4dec-8c26-8406c6fccd6e")
+  #
+  # # Creating a Hard Drive
+  #
+  # 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
+  #
+  #     # You can now access other attributes, since its saved:
+  #     hd.uuid
+  #     hd.location # will return a full path now
+  #
+  # # Destroying Hard Drives
+  #
+  # Hard drives can also be deleted. **This operation is not reversable**.
+  #
+  #     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.
+  #
+  #     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. 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("...")
+  #     hd.clone("bar.vmdk", "VMDK") # Will clone and convert to VMDK format
+  #
+  # # 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 :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"
+    attribute :location
+    attribute :logical_size
+    attribute :physical_size, :readonly => true, :property => :size
+
+    class << self
+      # Returns an array of all available hard drives as HardDrive
+      # objects.
+      #
+      # @return [Array<HardDrive>]
+      def all
+        Global.global(true).media.hard_drives
+      end
+
+      # 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)
+        all.detect { |hd| hd.uuid == id }
+      end
+
+      # Override of {Medium.device_type}.
+      def device_type
+        :hard_disk
+      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
+
+    # 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. 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)
+
+      # 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)
+
+      # 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.**
+    #
+    # @return [Boolean] True if command was successful, false otherwise.
+    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)
+
+      # Create the storage on the host system
+      new_medium.create_base_storage(logical_size, :standard).wait_for_completion(-1)
+
+      # 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,
+    # this will create a new hard drive. Otherwise, it will
+    # save any other details about the existing hard drive.
+    #
+    # Currently, **saving existing hard drives does nothing**.
+    # This is a limitation of VirtualBox, rather than the library itself.
+    #
+    # @return [Boolean] True if command was successful, false otherwise.
+    def save
+      return true if !new_record? && !changed?
+      raise Exceptions::ValidationFailedException.new(errors) if !valid?
+
+      if new_record?
+        create # Create a new hard drive
+      else
+        # 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

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.enabled? && 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