bbrowning-virtualbox 0.7.6.dev

data/lib/virtualbox/com/base_interface.rb

@@ -0,0 +1,38 @@
+require 'thread'
+
+module VirtualBox
+  module COM
+    class BaseInterface
+      def initialize
+        @task_queue = Queue.new
+
+        @lib_thread = Thread.new(@task_queue) do |queue|
+          while true
+            task, result = queue.pop
+
+            # Run the task, set the return value, and run the waiter
+            # which will simply finish that thread
+            result << task.call
+          end
+        end
+      end
+
+      # This function takes a block and runs it on a thread which is
+      # guaranteed to be the same since the first time this is
+      # called. This is required by the MSCOM implementation and is a
+      # good idea in general so that multiple API calls aren't firing
+      # at once.
+      def on_lib_thread(&task)
+        # If we're already on the lib thread, then just run it!
+        return task.call if Thread.current == @lib_thread
+
+        # Add the task to the queue
+        result = Queue.new
+        @task_queue << [task, result]
+
+        # Pop the result off of the result queue
+        result.pop
+      end
+    end
+  end
+end

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

@@ -0,0 +1,150 @@
+require 'ffi'
+
+module VirtualBox
+  module COM
+    module FFI
+      extend ::FFI::Library
+
+      # FFI specific types
+      NSRESULT_TYPE = :uint
+
+      # Creates all the FFI classes for a given version.
+      def self.for_version(version, &block)
+        @__module = Module.new
+        ::VirtualBox::COM::Util.set_interface_version(version)
+        const_set(::VirtualBox::COM::Util.version_const, @__module)
+        instance_eval(&block)
+        @__module = Kernel
+      end
+
+      # 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)
+        @__module.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::Util.versioned_interface(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::#{::VirtualBox::COM::Util.version_const}::#{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

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

@@ -0,0 +1,54 @@
+module VirtualBox
+  module COM
+    module FFI
+      # Creates all the interfaces for the FFI implementation. Eventually this
+      # file should be conditionally loaded based on OS, so that Windows users
+      # don't have to wait for all this translation to occur.
+      def self.setup(version)
+        # TODO: This is so hacky and hard to maintain. Can we
+        # programatically get the modules in a namespace and
+        # instantiate them somehow?
+        for_version version do
+          create_interface(:NSISupports)
+          create_interface(:NSIException, :NSISupports)
+          create_interface(:Session, :NSISupports)
+          create_interface(:VirtualBox, :NSISupports)
+          create_interface(:Appliance, :NSISupports)
+          create_interface(:AudioAdapter, :NSISupports)
+          create_interface(:BIOSSettings, :NSISupports)
+          create_interface(:Console, :NSISupports)
+          create_interface(:DHCPServer, :NSISupports)
+          create_interface(:GuestOSType, :NSISupports)
+          create_interface(:Host, :NSISupports)
+          create_interface(:HostNetworkInterface, :NSISupports)
+          create_interface(:Machine, :NSISupports)
+          create_interface(:Medium, :NSISupports)
+          create_interface(:MediumAttachment, :NSISupports)
+          create_interface(:MediumFormat, :NSISupports)
+          create_interface(:NetworkAdapter, :NSISupports)
+          create_interface(:ParallelPort, :NSISupports)
+          create_interface(:Progress, :NSISupports)
+          create_interface(:SerialPort, :NSISupports)
+          create_interface(:SharedFolder, :NSISupports)
+          create_interface(:Snapshot, :NSISupports)
+          create_interface(:StorageController, :NSISupports)
+          create_interface(:SystemProperties, :NSISupports)
+          create_interface(:USBController, :NSISupports)
+          create_interface(:USBDevice, :NSISupports)
+          create_interface(:USBDeviceFilter, :NSISupports)
+          create_interface(:VirtualBoxErrorInfo, :NSIException)
+          create_interface(:VirtualSystemDescription, :NSISupports)
+          create_interface(:VRDPServer, :NSISupports)
+
+          create_interface(:HostUSBDevice, :USBDevice)
+          create_interface(:HostUSBDeviceFilter, :USBDeviceFilter)
+
+          # 3.2.x interfaces
+          if version == "3.2.x"
+            create_interface(:NATEngine, :NSISupports)
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,119 @@
+module VirtualBox
+  module COM
+    module FFI
+      # Class which contains many class-level utility methods to assist
+      # with the FFI interface. These functions range from converting a
+      # function spec to a FFI parameter list to dereferencing pointers.
+      class Util
+        class << self
+          # Finds and returns the `COM::Interface` class associated with the type.
+          # If the class does not exist, a `NameError` will be raised.
+          #
+          # @return [Class]
+          def interface_klass(type)
+            ::VirtualBox::COM::Util.versioned_interface(type)
+          end
+
+          # Finds the versioned interface for the FFI module.
+          #
+          # @return [Class]
+          def versioned_interface(interface)
+            ::VirtualBox::COM::FFI.const_get(::VirtualBox::COM::Util.version_const).const_get(interface)
+          end
+
+          # Converts a function spec from {AbstractInterface} to an FFI
+          # function spec. This handles custom types (unicode strings,
+          # arrays, and out-parameters) and will return a perfectly valid
+          # array ready to be passed into `callback`.
+          #
+          # @param [Array] spec The function spec
+          # @return [Array]
+          def spec_to_ffi(spec)
+            spec = spec.collect do |item|
+              if item.is_a?(Array) && item[0] == :out
+                if item[1].is_a?(Array)
+                  # The out is an array of items, so we add in two pointers:
+                  # one for size and one for the array
+                  [:pointer, :pointer]
+                else
+                  # A regular out parameter is just a single pointer
+                  :pointer
+                end
+              elsif item.is_a?(Array) && item.length == 1
+                # The parameter is an array of somethings
+                [T_UINT32, :pointer]
+              elsif item == WSTRING
+                # Unicode strings are simply pointers
+                :pointer
+              elsif item.to_s[0,1] == item.to_s[0,1].upcase
+                begin
+                  # Try to get the class from the interfaces
+                  interface = interface_klass(item.to_sym)
+
+                  if interface.superclass == COM::AbstractInterface
+                    :pointer
+                  elsif interface.superclass == COM::AbstractEnum
+                    T_UINT32
+                  end
+                rescue NameError
+                  # Default to a pointer, since not all interfaces are implemented
+                  :pointer
+                end
+              else
+                # Unknown items are simply passed as-is, hopefully FFI
+                # will catch any problems
+                item
+              end
+            end
+
+            # Prepend a :pointer to represent the `this` parameter required
+            # for the FFI parameter lists
+            spec.unshift(:pointer).flatten
+          end
+
+          # An "almost complete" camel-caser. Camel cases a string with a few
+          # exceptions. For example: `get_foo` becomes `GetFoo`, but `get_os_type`
+          # becomes `GetOSType` since `os` is a special case.
+          #
+          # @param [String] string The string to camel case
+          # @return [String]
+          def camelize(string)
+            special_cases = {
+              "os" => "OS",
+              "dhcp" => "DHCP",
+              "dvd" => "DVD",
+              "usb" => "USB",
+              "vram" => "VRAM",
+              "3d" => "3D",
+              "bios" => "BIOS",
+              "vrdp" => "VRDP",
+              "hw" => "HW",
+              "png" => "PNG",
+              "io" => "IO",
+              "apic" => "APIC",
+              "acpi" => "ACPI",
+              "pxe" => "PXE",
+              "nat" => "NAT",
+              "ide" => "IDE",
+              "vfs" => "VFS",
+              "ip" => "IP",
+              "vdi" => "VDI",
+              "cpu" => "CPU",
+              "ram" => "RAM",
+              "hdd" => "HDD",
+              "rtc" => "RTC",
+              "utc" => "UTC",
+              "io" => "IO"
+            }
+
+            parts = string.to_s.split(/_/).collect do |part|
+              special_cases[part] || part.capitalize
+            end
+
+            parts.join("")
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,31 @@
+module VirtualBox
+  module COM
+    module FFI
+      # Callback types for VBOXXPCOMC
+      callback :pfnGetVersion, [], :uint
+      callback :pfnComInitialize, [:string, :pointer, :string, :pointer], :void
+      callback :pfnComUninitialize, [], :void
+      callback :pfnComUnallocMem, [:pointer], :void
+      callback :pfnUtf16Free, [:pointer], :void
+      callback :pfnUtf8Free, [:string], :void
+      callback :pfnUtf16ToUtf8, [:pointer, :pointer], :int
+      callback :pfnUtf8ToUtf16, [:string, :pointer], :int
+      callback :pfnGetEventQueue, [:pointer], :void
+
+      class VBOXXPCOMC < ::FFI::Struct
+        layout  :cb, :uint,
+                :uVersion, :uint,
+                :pfnGetVersion, :pfnGetVersion,
+                :pfnComInitialize, :pfnComInitialize,
+                :pfnComUninitialize, :pfnComUninitialize,
+                :pfnComUnallocMem, :pfnComUnallocMem,
+                :pfnUtf16Free, :pfnUtf16Free,
+                :pfnUtf8Free, :pfnUtf8Free,
+                :pfnUtf16ToUtf8, :pfnUtf16ToUtf8,
+                :pfnUtf8ToUtf16, :pfnUtf8ToUtf16,
+                :pfnGetEventQueue, :pfnGetEventQueue,
+                :uEndVersion, :uint
+      end
+    end
+  end
+end

data/lib/virtualbox/com/ffi_interface.rb

@@ -0,0 +1,96 @@
+module VirtualBox
+  module COM
+    class FFIInterface < BaseInterface
+      extend ::FFI::Library
+      include Logger
+
+      # Constant used to initialize the XPCOM C interface
+      XPCOMC_VERSION = 0x00020000
+
+      # VBOXXPCOMC struct. This typically won't be used.
+      attr_reader :xpcom
+
+      # The VirtualBox and Session interfaces, both of which are extremely
+      # important in interfacing with the VirtualBox API. Once these have been
+      # initialized, all other parts of the API can be accessed via these
+      # instances.
+      attr_reader :virtualbox
+      attr_reader :session
+
+      class << self
+        # Sets up the FFI interface and also initializes the interface,
+        # returning an instance of {FFIInterface}.
+        def create(lib_path=nil)
+          setup(lib_path)
+          new
+        end
+
+        # Sets up the FFI interface by specifying the FFI library path
+        # and attaching the initial function (which can't be done until
+        # the FFI library is specified).
+        #
+        # @param [String] lib_path
+        def setup(lib_path=nil)
+          # Setup the path to the C library
+          lib_path ||= "/Applications/VirtualBox.app/Contents/MacOS/VBoxXPCOMC.dylib"
+
+          # Attach to the interface
+          ffi_lib lib_path
+          attach_function :VBoxGetXPCOMCFunctions, [:uint], :pointer
+        end
+      end
+
+      def initialize
+        super
+        initialize_com
+      end
+
+      # Initializes the COM interface with XPCOM. This sets up the `virtualbox`,
+      # `session`, and `xpcom` attributes. This should only be called once.
+      def initialize_com
+        # Get the pointer to the XPCOMC struct which contains the functions
+        # to initialize
+        xpcom_pointer = self.class.VBoxGetXPCOMCFunctions(XPCOMC_VERSION)
+        @xpcom = FFI::VBOXXPCOMC.new(xpcom_pointer)
+
+        initialize_singletons
+      end
+
+      # Initializes the VirtualBox and Session interfaces. It goes through
+      # the various directories until it finds a working pair.
+      def initialize_singletons
+        interface_dir = File.expand_path(File.join(File.dirname(__FILE__), "interface"))
+        Dir[File.join(interface_dir, "*")].each do |f|
+          if File.directory?(f)
+            return if initialize_for_version(File.basename(f))
+          end
+        end
+      end
+
+      # Initializes the FFI interface for a specific version.
+      def initialize_for_version(version)
+        logger.debug("FFI init: Trying version #{version}")
+
+        # Setup the FFI classes
+        VirtualBox::COM::FFI.setup(version)
+        virtualbox_klass = COM::Util.versioned_interface(:VirtualBox)
+        session_klass = COM::Util.versioned_interface(:Session)
+
+        # Setup the OUT pointers
+        virtualbox_ptr = ::FFI::MemoryPointer.new(:pointer)
+        session_ptr = ::FFI::MemoryPointer.new(:pointer)
+
+        # Call the initialization functions
+        @xpcom[:pfnComInitialize].call(virtualbox_klass::IID_STR, virtualbox_ptr, session_klass::IID_STR, session_ptr)
+        @virtualbox = virtualbox_klass.new(Implementer::FFI, self, virtualbox_ptr.get_pointer(0))
+        @session = session_klass.new(Implementer::FFI, self, session_ptr.get_pointer(0))
+
+        logger.debug("    -- Valid version")
+        true
+      rescue Exception => e
+        logger.debug("    -- Invalid version")
+        false
+      end
+    end
+  end
+end