bbrowning-virtualbox 0.7.6.dev

data/lib/virtualbox/abstract_model/version_matcher.rb

@@ -0,0 +1,35 @@
+module VirtualBox
+  class AbstractModel
+    module VersionMatcher
+      # Asserts that two versions match. Otherwise raises an
+      # exception.
+      def assert_version_match(req, cur)
+        if !version_match?(req, cur)
+          message = "Required version: #{req}; Current: #{cur}"
+          raise Exceptions::UnsupportedVersionException.new(message)
+        end
+      end
+
+      # Checks if a given version requirement matches the current
+      # version.
+      #
+      # @return [Boolean]
+      def version_match?(requirement, current)
+        split_version(requirement) == split_version(current)
+      end
+
+      # Splits a version string into a two-item array with the parts
+      # of the version, respectively. If the version has more than two
+      # parts, the rest are ignored.
+      #
+      # @param [String] version
+      # @return [Array]
+      def split_version(version)
+        version.split(/\./)[0,2]
+      rescue Exception
+        []
+      end
+    end
+  end
+end
+

data/lib/virtualbox/appliance.rb

@@ -0,0 +1,62 @@
+module VirtualBox
+  # Represents an VirtualBox "appliance" which is an exported virtual machine or
+  # virtual machines. Appliances typically come with an OVF file and one or more
+  # compressed hard disks, and can be used to import directly into other VirtualBox
+  # installations. Appliances allow for virtual machine portability.
+  class Appliance < AbstractModel
+    attribute :path
+    attribute :interface, :readonly => true, :property => false
+    relationship :virtual_systems, :VirtualSystemDescription
+
+    def initialize(*args)
+      write_attribute(:interface, Lib.lib.virtualbox.create_appliance)
+
+      initialize_from_path(*args) if args.length == 1
+
+      clear_dirty!
+    end
+
+    # Initializes this Appliance instance from a path to an OVF file. This sets
+    # up the relationships and so on.
+    #
+    # @param [String] path Path to the OVF file.
+    def initialize_from_path(path)
+      # Read in the data from the path
+      interface.read(path).wait_for_completion(-1)
+
+      # Interpret the data to fill in the interface properties
+      interface.interpret
+
+      # Load the interface attributes
+      load_interface_attributes(interface)
+
+      # Fill in the virtual systems
+      populate_relationship(:virtual_systems, interface.virtual_system_descriptions)
+
+      # Should be an existing record
+      existing_record!
+    end
+
+    # Imports the machines associated with this appliance. If a block is given,
+    # it will be yielded every percent that the operation progresses. This can be
+    # done to check the progress of the import.
+    def import(&block)
+      interface.import_machines.wait(&block)
+    end
+
+    # Exports the machines to the given path. If a block is given, it will be yielded
+    # every percent that the operation progresses. This can be done to check the progress
+    # of the export in real-time.
+    def export(&block)
+      interface.write("ovf-1.0", path).wait(&block)
+    end
+
+    # Adds a VM to the appliance
+    def add_machine(vm, options = {})
+      sys_desc = vm.interface.export(interface)
+      options.each do |key, value|
+        sys_desc.add_description(key, value, value)
+      end
+    end
+  end
+end

data/lib/virtualbox/audio_adapter.rb

@@ -0,0 +1,52 @@
+module VirtualBox
+  class AudioAdapter < AbstractModel
+    attribute :parent, :readonly => true, :property => false
+    attribute :enabled, :boolean => true
+    attribute :audio_controller
+    attribute :audio_driver
+
+    class << self
+      # Populates a relationship with another model.
+      #
+      # **This method typically won't be used except internally.**
+      #
+      # @return [BIOS]
+      def populate_relationship(caller, imachine)
+        data = new(caller, imachine.audio_adapter)
+      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, iaudio)
+      write_attribute(:parent, parent)
+
+      # Load the attributes and mark the whole thing as existing
+      load_interface_attributes(iaudio)
+      clear_dirty!
+      existing_record!
+    end
+
+    def validate
+      super
+
+      validates_inclusion_of :enabled, :in => [true, false]
+      validates_inclusion_of :audio_controller, :in => COM::Util.versioned_interface(:AudioControllerType).map
+      validates_inclusion_of :audio_driver, :in => COM::Util.versioned_interface(:AudioDriverType).map
+    end
+
+    def save
+      parent.with_open_session do |session|
+        machine = session.machine
+
+        # Save them
+        save_changed_interface_attributes(machine.audio_adapter)
+      end
+    end
+  end
+end

data/lib/virtualbox/bios.rb

@@ -0,0 +1,50 @@
+module VirtualBox
+  # Represents the BIOS settings of a {VM}.
+  class BIOS < AbstractModel
+    attribute :parent, :readonly => true, :property => false
+    attribute :acpi_enabled, :boolean => true
+    attribute :io_apic_enabled, :boolean => true
+
+    class << self
+      # Populates a relationship with another model.
+      #
+      # **This method typically won't be used except internally.**
+      #
+      # @return [BIOS]
+      def populate_relationship(caller, imachine)
+        data = new(caller, imachine.bios_settings)
+      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, bios_settings)
+      write_attribute(:parent, parent)
+
+      # Load the attributes and mark the whole thing as existing
+      load_interface_attributes(bios_settings)
+      clear_dirty!
+      existing_record!
+    end
+
+    def validate
+      super
+
+      validates_inclusion_of :acpi_enabled, :io_apic_enabled, :in => [true, false]
+    end
+
+    def save
+      parent.with_open_session do |session|
+        machine = session.machine
+
+        # Save them
+        save_changed_interface_attributes(machine.bios_settings)
+      end
+    end
+  end
+end

data/lib/virtualbox/com.rb

@@ -0,0 +1,23 @@
+module VirtualBox
+  module COM
+    WSTRING = :unicode_string
+    T_INT32 = :int
+    T_INT64 = :long
+    T_ULONG = :ulong
+    T_UINT8 = :uchar
+    T_UINT16 = :ushort
+    T_UINT32 = :uint
+    T_UINT64 = :ulong
+    T_BOOL = :char
+  end
+end
+
+# The com directory of the gem
+comdir = File.join(File.dirname(__FILE__), 'com')
+
+# Require the abstract interface first then glob load all
+# of the interfaces
+require File.expand_path("abstract_interface", comdir)
+require File.expand_path("abstract_enum", comdir)
+VirtualBox::GlobLoader.glob_require(File.join(comdir, "interface"))
+VirtualBox::GlobLoader.glob_require(comdir, %w{base_interface abstract_interface abstract_implementer util ffi/interface ffi/util implementer/base})

data/lib/virtualbox/com/abstract_enum.rb

@@ -0,0 +1,43 @@
+module VirtualBox
+  module COM
+    # Represents a C enum type. Provides functionality to easily convert
+    # an int value to its proper symbol within the enum.
+    class AbstractEnum
+      extend Enumerable
+
+      class << self
+        # Defines the mapping of int => symbol for the given Enum.
+        # The parameter to this can be an Array or Hash or anything which
+        # can be indexed with `[]` and an integer and returns a value of
+        # some sort. If value is left nil, it will return the current mapping
+        def map(value = nil)
+          @map = value if value
+          @map
+        end
+
+        # Returns the symbol associatd with the given key
+        def [](key)
+          @map[key]
+        end
+
+        # Returns the index associated with a value
+        def index(key)
+          @map.index(key)
+        end
+
+        # Iterate over the enum, yielding each item to a block.
+        def each
+          @map.each do |key|
+            yield key
+          end
+        end
+
+        # Provided mostly for testing purposes only, but resets the mapping
+        # to nil.
+        def reset!
+          @map = nil
+        end
+      end
+    end
+  end
+end

data/lib/virtualbox/com/abstract_implementer.rb

@@ -0,0 +1,45 @@
+module VirtualBox
+  module COM
+    # Base class for a COM interface implementer. Any child of this class is
+    # responsible for properly handling the various method and propery calls
+    # of a given {AbstractInterface} and making them do actual work.
+    #
+    # This abstraction is necessary to change the behavior of calls between
+    # Windows (COM) and Unix (XPCOM), which have different calling conventions.
+    class AbstractImplementer
+      attr_reader :interface
+      attr_reader :lib
+
+      # Initializes an implementer for the given {AbstractInterface}. The
+      # implementor's other methods, such as {read_property} or
+      # {call_function} are responsible for executing the said action on
+      # the interface.
+      #
+      # @param [AbstractInterface] interface
+      def initialize(interface, lib)
+        @interface = interface
+        @lib = lib
+      end
+
+      # Read a property of the interface.
+      #
+      # @param [Symbol] name The propery name
+      def read_property(name, opts)
+      end
+
+      # Writes a property of the interface.
+      #
+      # @param [Symbol] name The property name
+      # @param [Object] value The value to set
+      def write_property(name, value, opts)
+      end
+
+      # Calls a function on the interface.
+      #
+      # @param [Symbol] name The function name
+      # @param [Array] args The arguments to the function
+      def call_function(name, args, opts)
+      end
+    end
+  end
+end

data/lib/virtualbox/com/abstract_interface.rb

@@ -0,0 +1,167 @@
+module VirtualBox
+  module COM
+    # Base class for a COM (component object model) interface class. This
+    # abstraction is necessary to maintain a common ground between
+    # Windows COM usage and the VirtualBox C API for unix based systems.
+    #
+    # # Defining an Interface
+    #
+    # Defining an interface is done by subclassing AbstractInterface and
+    # using the provided class methods to define the COM methods and
+    # properties. A small example class is shown below:
+    #
+    #     class Time < AbstractInterface
+    #       function :now, [[:out, :uint]]
+    #       property :hour, :uint
+    #     end
+    #
+    # # Accessing an Interface
+    #
+    # Interfaces are never accessed directly. Instead, an {InterfaceRunner}
+    # should be used. Depending on the OS of the running system, the VirtualBox
+    # gem will automatically either load the MSCOM interface (on Windows)
+    # or the XPCOM interface (on Unix). One loaded, interfaces can simply be
+    # accessed:
+    #
+    #     # Assume `time` was retrieved already
+    #     puts time.foo.to_s
+    #     time.hour = 20
+    #     x = time.now
+    #
+    # The above example shows how the properties and functions can be used
+    # with a given interface.
+    #
+    class AbstractInterface
+      attr_reader :implementer
+      attr_reader :lib
+
+      class << self
+        # Adds a function to the interface with the given name and function
+        # spec. The spec determines the arguments required, the order they
+        # are required in, and any out-arguments.
+        def function(name, type, spec, opts={})
+          members << [name, {
+            :type => :function,
+            :value_type => type,
+            :spec => spec,
+            :opts => opts
+          }]
+
+          # Define the method to call the function
+          define_method(name) { |*args| call_function(name, *args) }
+        end
+
+        # Adds a property to the interface with the given name, type, and
+        # options.
+        def property(name, type, opts={})
+          members << [name, {
+            :type => :property,
+            :value_type => type,
+            :opts => opts
+          }]
+
+          # Define the method to read the property
+          define_method(name) { read_property(name) }
+
+          # Define method to write the property
+          define_method("#{name}=".to_sym) { |value| write_property(name, value) } unless opts[:readonly]
+        end
+
+        # Returns the information for a given member
+        #
+        # @return [Hash]
+        def member(name)
+          members.each do |current_name, opts|
+            if name == current_name
+              return opts
+            end
+          end
+
+          nil
+        end
+
+        # Returns the members of the interface as an array.
+        #
+        # @return [Array]
+        def members
+          @members ||= []
+        end
+
+        # Returns the functions of the interface as an array in the order they
+        # were defined.
+        #
+        # @return [Array]
+        def functions
+          members.find_all do |data|
+            data[1][:type] == :function
+          end
+        end
+
+        # Returns the properties of the interface as an array in the order they
+        # were defined.
+        #
+        # @return [Array]
+        def properties
+          members.find_all do |data|
+            data[1][:type] == :property
+          end
+        end
+      end
+
+      # Initializes the interface with the given implementer
+      def initialize(implementer, lib, *args)
+        # Instantiate the implementer and set it
+        @lib = lib
+        @implementer = implementer.new(self, lib, *args)
+      end
+
+      # Reads a property with the given name by calling the read_property
+      # method on the implementer.
+      def read_property(name)
+        # Just call it on the implementer
+        @implementer.read_property(name, member(name))
+      end
+
+      # Writes a property with the given name and value by calling the
+      # `write_property` method on the implementer.
+      def write_property(name, value)
+        @implementer.write_property(name, value, member(name))
+      end
+
+      # Calls a function with the given name by calling call_function on the
+      # implementer.
+      def call_function(name, *args)
+        @implementer.call_function(name, args, member(name))
+      end
+
+      # Returns a boolean if a given function exists or not
+      def has_function?(name)
+        info = member(name)
+        !info.nil? && info[:type] == :function
+      end
+
+      # Returns a boolean if a given property exists or not.
+      def has_property?(name)
+        info = member(name)
+        !info.nil? && info[:type] == :property
+      end
+
+      # Returns the member of the interface specified by name. This simply
+      # calls {AbstractInterface.member}
+      def member(name)
+        self.class.member(name)
+      end
+
+      # Returns the members of the interface as an array. This simply calls
+      # {AbstractInterface.members}.
+      def members
+        self.class.members
+      end
+
+      # Concise inspect
+      def inspect
+        "#<#{self.class.name}>"
+      end
+    end
+  end
+end