virtualbox 0.5.4 → 0.6.0

data/lib/virtualbox/audio_adapter.rb

@@ -0,0 +1,44 @@
+module VirtualBox
+  class AudioAdapter < AbstractModel
+    attribute :parent, :readonly => true, :property => false
+    attribute :enabled
+    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 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,44 @@
+module VirtualBox
+  # Represents the BIOS settings of a {VM}.
+  class BIOS < AbstractModel
+    attribute :parent, :readonly => true, :property => false
+    attribute :acpi_enabled
+    attribute :io_apic_enabled
+
+    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 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{abstract_interface abstract_implementer util ffi/interface ffi/util implementer/base})

data/lib/virtualbox/com/abstract_enum.rb

@@ -0,0 +1,42 @@
+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.
+        def map(value)
+          @map = value
+        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,43 @@
+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
+
+      # 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)
+        @interface = interface
+      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,165 @@
+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
+
+      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, *args)
+        # Instantiate the implementer and set it
+        @implementer = implementer.new(self, *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

data/lib/virtualbox/com/ffi/interface.rb

@@ -0,0 +1,141 @@
+require 'ffi'
+
+module VirtualBox
+  module COM
+    module FFI
+      extend ::FFI::Library
+
+      # FFI specific types
+      NSRESULT_TYPE = :uint
+
+      # Returns a Class which creates an FFI interface to the specified
+      # com interface and potentially a parent class as well.
+      def self.create_interface(interface, parent=nil)
+        klass = Class.new(Interface)
+        const_set(interface, klass)
+        klass.com_interface(interface, parent)
+        klass
+      end
+
+      # Represents a VirtualBox XPCOM C interface, which is a C struct
+      # which emulates an object (a struct with function pointers
+      # and getters/setters). This class does **a lot** of magic which pretty
+      # much represents everything wrong about ruby programmers, but keep
+      # in mind it is well tested and well commented, and the meta-programming
+      # was done out of a need to keep things DRY between Windows and Unix
+      # operating systems.
+      class Interface
+        extend ::FFI::Library
+
+        attr_reader :vtbl_parent
+        attr_reader :vtbl
+
+        class <<self
+          # Sets up the args to the FFI::Struct `layout` method. This
+          # method defines all the callbacks necessary for working with
+          # FFI and also sets up any layout args to send in. The way the
+          # XPCOM C structs are setup, the properties are first, in
+          # `GetFoo` and `SetFoo` format. And the functions are next. They are
+          # put into the struct in the order defined in the {AbstractInterface}.
+          def com_interface(interface, parent=nil)
+            # Create the parent class and vtbl class
+            interface = ::VirtualBox::COM::Interface.const_get(interface)
+            define_vtbl_parent_for_interface(interface)
+            define_vtbl_for_interface(interface, parent)
+          end
+
+          # Creates the parent of the vtbl class associated with a given
+          # interface.
+          def define_vtbl_parent_for_interface(interface)
+            @vtbl_parent_klass = Class.new(::FFI::Struct)
+            @vtbl_parent_klass.layout(:vtbl, :pointer)
+
+            # Set the constant
+            const_set("VtblParent", @vtbl_parent_klass)
+          end
+
+          # Creates the vtbl class associated with a given interface.
+          def define_vtbl_for_interface(interface, parent=nil)
+            # Define the properties, then the functions, since thats the order
+            # the FFI structs are in
+            layout_args.clear
+            define_interface_parent(parent)
+            define_interface_properties(interface)
+            define_interface_functions(interface)
+
+            # Finally create the classes (the struct and the structs vtbl)
+            @vtbl_klass = Class.new(::FFI::Struct)
+
+            # Set the constant within this class
+            const_set("Vtbl", @vtbl_klass).layout(*layout_args.flatten)
+          end
+
+          # Defines the parent item of the layout. Since the VirtualBox XPCOM C
+          # library emulates an object-oriented environment using structs, the parent
+          # instance is pointed to by the first member of the struct. This method
+          # sets up that member.
+          #
+          # @param [Symbol] parent The name of the parent represented by a symbol
+          def define_interface_parent(parent)
+            return if parent.nil?
+
+            parent_klass = Object.module_eval("::VirtualBox::COM::FFI::#{parent}::Vtbl")
+            layout_args << [:superklass, parent_klass]
+          end
+
+          # Defines all the properties on a com interface.
+          def define_interface_properties(interface)
+            interface.properties.each do |name, opts|
+              # Define the getter
+              define_interface_function("get_#{name}".to_sym, opts[:value_type])
+
+              # Define the setter unless the property is readonly
+              define_interface_function("set_#{name}".to_sym, nil, [opts[:value_type]]) unless opts[:opts] && opts[:opts][:readonly]
+            end
+          end
+
+          # Defines all the functions on a com interface.
+          def define_interface_functions(interface)
+            interface.functions.each do |name, opts|
+              # Define the function
+              define_interface_function(name, opts[:value_type], opts[:spec].dup)
+            end
+          end
+
+          # Defines a single function of a com interface
+          def define_interface_function(name, return_type, spec=[])
+            # Append the return type to the spec as an out parameter (this is how
+            # the C API handles it)
+            spec << [:out, return_type] unless return_type.nil?
+
+            # Define the "callback" type for the FFI module
+            callback(name, Util.spec_to_ffi(spec), NSRESULT_TYPE)
+
+            # Add to the layout args
+            layout_args << [name, name]
+          end
+
+          # Returns an array of the layout args to send to `layout` eventually.
+          #
+          # @return [Array]
+          def layout_args
+            @_layout_args ||= []
+          end
+        end
+
+        # Initializes the interface to the FFI struct with the given pointer. The
+        # pointer is used to initialize the VtblParent which is used to initialize
+        # the Vtbl itself.
+        def initialize(pointer)
+          initialize_vtbl(pointer)
+        end
+
+        def initialize_vtbl(pointer)
+          klass = self.class
+          @vtbl_parent = klass::VtblParent.new(pointer)
+          @vtbl = klass::Vtbl.new(vtbl_parent[:vtbl])
+        end
+      end
+    end
+  end
+end