bbrowning-virtualbox 0.7.6.dev

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.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

data/lib/virtualbox/hw_virtualization.rb

@@ -0,0 +1,63 @@
+module VirtualBox
+  # Represents the HW virtualization properties on a VM.
+  class HWVirtualization < AbstractModel
+    attribute :parent, :readonly => true, :property => false
+    attribute_scope(:property_getter => Proc.new { |instance, *args| instance.get_property(*args) },
+                    :property_setter => Proc.new { |instance, *args| instance.set_property(*args) }) do
+      attribute :enabled, :boolean => true
+      attribute :exclusive, :boolean => true
+      attribute :vpid, :boolean => true
+      attribute :nested_paging, :boolean => true
+    end
+
+    class << self
+      # Populates a relationship with another model.
+      #
+      # **This method typically won't be used except internally.**
+      #
+      # @return [HWVirtualization]
+      def populate_relationship(caller, imachine)
+        data = new(caller, imachine)
+      end
+
+      # Saves the relationship.
+      #
+      # **This method typically won't be used except internally.**
+      def save_relationship(caller, instance)
+        instance.save
+      end
+    end
+
+    def initialize(parent, imachine)
+      write_attribute(:parent, parent)
+
+      # Load the attributes and mark the whole thing as existing
+      load_interface_attributes(imachine)
+      clear_dirty!
+      existing_record!
+    end
+
+    def get_property(interface, key)
+      interface.get_hw_virt_ex_property(key)
+    end
+
+    def set_property(interface, key, value)
+      interface.set_hw_virt_ex_property(key, value)
+    end
+
+    def validate
+      super
+
+      validates_inclusion_of :enabled, :exclusive, :vpid, :nested_paging, :in => [true, false]
+    end
+
+    def save
+      parent.with_open_session do |session|
+        machine = session.machine
+
+        # Save them
+        save_changed_interface_attributes(machine)
+      end
+    end
+  end
+end

data/lib/virtualbox/lib.rb

@@ -0,0 +1,84 @@
+module VirtualBox
+  # Used by the rest of the VirtualBox library to interface with
+  # the VirtualBox XPCOM library (VBoxXPCOMC). Most users will never need
+  # to interface with this class directly, except other to set the path to
+  # the `VBoxXPCOMC` lib.
+  #
+  # # Setting the Path to the VBoxXPCOMC Library
+  #
+  # This won't be necessary for 95% of users, and won't be necessary at all
+  # for windows users. But for unix users, the VirtualBox gem uses a dynamic
+  # library named `VBoxXPCOMC` to interface with VirtualBox. The gem does its
+  # best to guess the path to this gem based on the operating system ruby is
+  # running on, but in the case you get an error about it missing, you can
+  # easily set it:
+  #
+  #     VirtualBox::Lib.lib_path = "/path/to/VBoxXPCOMC.so"
+  #
+  # **Windows users will never need to do this.**
+  #
+  class Lib
+    @@lib_path = nil
+    @@lib = nil
+
+    attr_reader :interface
+    attr_reader :virtualbox
+    attr_reader :session
+
+    class << self
+      # Resets the initialized library (if there is any). This is primarily only
+      # used for testing.
+      def reset!
+        @@lib = nil
+      end
+
+      # The singleton instance of Lib.
+      #
+      # @return [Lib]
+      def lib
+        @@lib ||= new(lib_path)
+      end
+
+      # Sets the path to the VBoxXPCOMC library which is created with any
+      # VirtualBox install. 90% of the time, this won't have to be set manually,
+      # and instead the gem will try to find it for you.
+      #
+      # @param [String] Full path to the VBoxXPCOMC library
+      def lib_path=(value)
+        @@lib_path = value.nil? ? value : File.expand_path(value)
+      end
+
+      # Returns the path to the virtual box library. If the path
+      # has not yet been set, it attempts to infer it based on the
+      # platform ruby is running on.
+      def lib_path
+        if @@lib_path.nil?
+          if Platform.mac?
+            @@lib_path = ["/Applications/VirtualBox.app/Contents/MacOS/VBoxXPCOMC.dylib"]
+          elsif Platform.linux?
+            @@lib_path = ["/opt/VirtualBox/VBoxXPCOMC.so", "/usr/lib/virtualbox/VBoxXPCOMC.so"]
+          elsif Platform.solaris?
+            @@lib_path = ["/opt/VirtualBox/amd64/VBoxXPCOMC.so", "/opt/VirtualBox/i386/VBoxXPCOMC.so"]
+          elsif Platform.windows?
+            @@lib_path = "Unknown"
+          else
+            @@lib_path = "Unknown"
+          end
+        end
+
+        @@lib_path
+      end
+    end
+
+    def initialize(lib_path)
+      if Platform.windows?
+        @interface = COM::MSCOMInterface.new
+      else
+        @interface = COM::FFIInterface.create(lib_path)
+      end
+
+      @virtualbox = @interface.virtualbox
+      @session = @interface.session
+    end
+  end
+end

data/lib/virtualbox/media.rb

@@ -0,0 +1,20 @@
+module VirtualBox
+  # Represents the media registry within the global VirtualBox configuration.
+  class Media < AbstractModel
+    attribute :parent, :readonly => true
+    relationship :hard_drives, :HardDrive
+    relationship :dvds, :DVD
+
+    class << self
+      def populate_relationship(caller, lib)
+        new(caller, lib)
+      end
+    end
+
+    def initialize(parent, lib)
+      populate_attributes({ :parent => parent }, :ignore_relationships => true)
+      populate_relationship(:hard_drives, lib.virtualbox.hard_disks)
+      populate_relationship(:dvds, lib.virtualbox.dvd_images)
+    end
+  end
+end

data/lib/virtualbox/medium.rb

@@ -0,0 +1,145 @@
+module VirtualBox
+  # Represents a medium object part of VirtualBox. A medium is a
+  # hard drive, DVD, floppy disk, etc. Each of these share common
+  # properties represented here.
+  class Medium < AbstractModel
+    include SubclassListing
+
+    attribute :uuid, :readonly => true, :property => :id
+    attribute :type, :readonly => true
+    attribute :description, :readonly => true
+    attribute :location, :readonly => true
+    attribute :state, :readonly => true, :property => :refresh_state
+    attribute :interface, :readonly => true, :property => false
+    relationship :children, :Medium, :lazy => true
+
+    class << self
+      # Populates a relationship with another model. Depending on the data sent
+      # through as the `media` parameter, this can either return a single value
+      # or an array of values. {Global}, for example, has a relationship of media,
+      # while a {MediumAttachment} has a relationship with a single medium.
+      #
+      # **This method typically won't be used except internally.**
+      def populate_relationship(caller, media)
+        if media.is_a?(Array)
+          # has many relationship
+          populate_array_relationship(caller, media)
+        else
+          # has one relationship
+          populate_single_relationship(caller, media)
+        end
+      end
+
+      # Populates a relationship which has many media.
+      #
+      # **This method typically won't be used except internally.**
+      #
+      # @return [Array<Medium>]
+      def populate_array_relationship(caller, media)
+        relation = Proxies::Collection.new(caller)
+
+        media.each do |medium|
+          # Skip media this class isn't interested in
+          next if device_type != :all && medium.device_type != device_type
+
+          # Wrap it up and add to the relationship
+          relation << new(medium)
+        end
+
+        relation
+      end
+
+      # Populates a relationship which has one medium. This method goes one step
+      # further and instantiates the proper class for the type of medium given.
+      # For example, given a `device_type` of `:hard_drive`, it would return a
+      # {HardDrive} object.
+      #
+      # **This method typically won't be used except internally.**
+      #
+      # @return [Medium]
+      def populate_single_relationship(caller, medium)
+        return nil if medium.nil?
+
+        subclasses.each do |subclass|
+          # Skip this class unless the device type matches
+          next unless subclass.device_type == medium.device_type
+
+          # Wrap it up and return it
+          return subclass.new(medium)
+        end
+
+        # If all else fails, just wrap it in a Medium
+        new(medium)
+      end
+
+      # Specifies the device type that a {Medium} class is interested in. This
+      # is `:all` on {Medium}, but is expected to be overridden by child classes.
+      # The value returned should be one of {COM::Interface::DeviceType}.
+      #
+      # @return [Symbol]
+      def device_type
+        :all
+      end
+    end
+
+    # Initializes a medium object, retrieving the attributes and information
+    # from the {COM::Interface::Medium} object given as the parameter. This initialization
+    # is done automatically by virtualbox when populating a relationship. Mediums should
+    # never be initialized manually.
+    #
+    # @param [COM::Interface::Medium] imedium
+    def initialize(imedium)
+      write_attribute(:interface, imedium)
+      initialize_attributes(imedium)
+    end
+
+    def initialize_attributes(imedium)
+      # First refresh the state (required for many attributes)
+      imedium.refresh_state
+
+      # Load interface attributes
+      load_interface_attributes(imedium)
+
+      # 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)
+      # Populate children
+      populate_relationship(name, interface.children)
+    end
+
+    # Returns the basename of the images location (the file name +extension)
+    #
+    # @return [String]
+    def filename
+      File.basename(location.to_s)
+    end
+
+    # Destroys the medium, optionally also phsyically destroying the backing
+    # storage. This removes this medium from the VirtualBox media registry.
+    # In order to remove the medium, it must not be attached to any virtual
+    # machine. If it is, an exception of some sort will be raised.
+    # This action happens *immediately* when the method is called, and is not
+    # deferred to a save.
+    def destroy(destroy_backing=false)
+      if destroy_backing
+        destroy_storage
+      else
+        interface.close
+      end
+    end
+
+    # Destroys the backing store of the medium and the media registry. This is
+    # analagous to calling {#destroy} with the first parameter set to true. This
+    # method requires that the medium not be attached to any virtual machine
+    # (running or not).
+    def destroy_storage
+      interface.delete_storage.wait_for_completion(-1)
+    end
+  end
+end