virtualbox 0.5.4 → 0.6.0

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

@@ -0,0 +1,42 @@
+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.
+      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)
+    end
+  end
+end

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

@@ -0,0 +1,101 @@
+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
+          # 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 = COM::Interface.const_get(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"
+            }
+
+            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, [:void], :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,65 @@
+module VirtualBox
+  module COM
+    class FFIInterface
+      extend ::FFI::Library
+
+      # 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
+        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)
+
+        virtualbox_ptr = ::FFI::MemoryPointer.new(:pointer)
+        session_ptr = ::FFI::MemoryPointer.new(:pointer)
+
+        # Initialize the virtualbox API and get the global VirtualBox
+        # interface and a session interface
+        @xpcom[:pfnComInitialize].call(COM::Interface::VirtualBox::IID_STR, virtualbox_ptr, COM::Interface::Session::IID_STR, session_ptr)
+        @virtualbox = Interface::VirtualBox.new(Implementer::FFI, self, virtualbox_ptr.get_pointer(0))
+        @session = Interface::Session.new(Implementer::FFI, self, session_ptr.get_pointer(0))
+      end
+    end
+  end
+end

data/lib/virtualbox/com/implementer/base.rb

@@ -0,0 +1,52 @@
+module VirtualBox
+  module COM
+    module Implementer
+      class Base < AbstractImplementer
+        include Logger
+
+        # 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)
+          COM::Interface.const_get(type)
+        end
+
+        # Gives the C type and inferred type of a parameter type. Quite confusing
+        # since the terminology is not consistent, but hopefully these examples
+        # will help:
+        #
+        #   type => [pointer_type, internal_type]
+        #   :int => [:int, :int]
+        #   :MyStruct => [:pointer, :struct]
+        #   :unicode_string => [:pointer, :unicode_string]
+        #
+        def infer_type(type)
+          c_type = type
+
+          begin
+            if type == WSTRING
+              # Handle strings as pointer types
+              c_type = :pointer
+            else
+              # Try to get the class from the interfaces
+              interface = COM::Interface.const_get(type)
+
+              c_type = :pointer
+
+              # Depending on the class type, we're either dealing with an interface
+              # or an enum
+              type = :interface if interface.superclass == COM::AbstractInterface
+              type = :enum if interface.superclass == COM::AbstractEnum
+            end
+          rescue NameError
+            # Do nothing
+          end
+
+          [c_type, type]
+        end
+
+      end
+    end
+  end
+end

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

@@ -0,0 +1,350 @@
+module VirtualBox
+  module COM
+    module Implementer
+      class FFI < Base
+        attr_reader :ffi_interface
+        attr_reader :lib
+
+        # Initializes the FFI implementer which takes an {VirtualBox::COM::AbstractInterface AbstractInterface}
+        # instant and FFI pointer and initializes everything required to
+        # communicate with that interface via FFI.
+        #
+        # @param [VirtualBox::COM::AbstractInteface] inteface
+        # @param [FFI::Pointer] pointer
+        def initialize(interface, lib_base, pointer)
+          super(interface)
+
+          @lib = lib_base
+          @ffi_interface = ffi_class.new(pointer)
+        end
+
+        # Gets the FFI struct class associated with the interface. This works
+        # by stripping the namespace off of the interface class and finding that
+        # same class within the `COM::FFI` namespace. For example:
+        # `VirtualBox::COM::Interface::Session` becomes `VirtualBox::COM::FFI::Session`
+        #
+        # @return [Class]
+        def ffi_class
+          # Take off the last part of the class, so `Foo::Bar::Baz` becomes
+          # just `Baz`
+          klass_name = interface.class.to_s.split("::").last
+
+          # Get the associated FFI class
+          COM::FFI.const_get(klass_name)
+        end
+
+        # Reads a property from the interface with the given name.
+        def read_property(name, opts)
+          call_vtbl_function("get_#{name}".to_sym, [[:out, opts[:value_type]]])
+        end
+
+        # Writes a property to the interface with the given name and value.
+        def write_property(name, value, opts)
+          call_vtbl_function("set_#{name}".to_sym, [opts[:value_type]], [value])
+        end
+
+        # Calls a function from the interface with the given name and args. This
+        # method is called from the {AbstractInterface}.
+        def call_function(name, args, opts)
+          spec = opts[:spec].dup
+          spec << [:out, opts[:value_type]] if !opts[:value_type].nil?
+
+          call_vtbl_function(name.to_sym, spec, args)
+        end
+
+        # Calls a function on the vtbl of the FFI struct. This function handles
+        # converting the spec to proper arguments and also handles reading out
+        # the arguments, dereferencing pointers, setting up objects, etc. so that
+        # the return value is filled with nicely formatted Ruby objects.
+        #
+        # If the vtbl function being called only has one out parameter, then the
+        # return value will be that single object. If it has multiple, then it will
+        # be an array of objects.
+        def call_vtbl_function(name, spec, args=[])
+          # Get the "formal argument" list. This is the list of arguments to send
+          # to the actual function based on the spec. This contains pointers, some
+          # arguments from `args`, etc.
+          formal_args = spec_to_args(spec, args)
+
+          # Call the function.
+          logger.debug("FFI call: #{name} #{args.inspect}")
+          call_and_check(ffi_interface.vtbl[name], ffi_interface.vtbl_parent, *formal_args)
+
+          # Extract the values from the formal args array, again based on the
+          # spec (and the various :out parameters)
+          result = values_from_formal_args(spec, formal_args)
+          logger.debug("    = #{result.inspect}")
+          result
+        end
+
+        #############################################################
+        # Internal Methods, a.k.a. unless you're hacking on the code of this
+        # library, you should do well to leave these alone =]
+        #############################################################
+
+        # Checks the result of a method call for an error, and if an error
+        # occurs, then raises an exception.
+        def call_and_check(function, *args)
+          result = function.call(*args)
+
+          # Ignore NS_ERROR_NOT_IMPLEMENTED, since it seems to be raised for
+          # things which aren't really exceptional
+          if result != 2147500033 && (result & 0x8000_0000) != 0
+            # Failure, raise exception with details of the error
+            raise exception_map(result).new({
+              :function => function.to_s,
+              :result_code => result
+            })
+          end
+        end
+
+        # Maps a result code to an exception. If no mapping currently exists,
+        # then a regular {Exceptions::FFIException} is returned.
+        #
+        # @param [Fixnum] code Result code
+        # @return [Class]
+        def exception_map(code)
+          map = {
+            0x80BB_0001 => Exceptions::ObjectNotFoundException,
+            0x80BB_0002 => Exceptions::InvalidVMStateException,
+            0x80BB_0003 => Exceptions::VMErrorException,
+            0x80BB_0004 => Exceptions::FileErrorException,
+            0x80BB_0005 => Exceptions::SubsystemException,
+            0x80BB_0006 => Exceptions::PDMException,
+            0x80BB_0007 => Exceptions::InvalidObjectStateException,
+            0x80BB_0008 => Exceptions::HostErrorException,
+            0x80BB_0009 => Exceptions::NotSupportedException,
+            0x80BB_000A => Exceptions::XMLErrorException,
+            0x80BB_000B => Exceptions::InvalidSessionStateException,
+            0x80BB_000C => Exceptions::ObjectInUseException
+          }
+
+          map[code] || Exceptions::FFIException
+        end
+
+        # Converts a function spec to a proper argument list with the given
+        # arguments.
+        #
+        # @return [Array]
+        def spec_to_args(spec, args=[])
+          args = args.dup
+
+          spec = spec.collect do |item|
+            if item.is_a?(Array) && item[0] == :out
+              if item[1].is_a?(Array)
+                # For arrays we need two pointers: one for size, and one for the
+                # actual array
+                [pointer_for_type(T_UINT32), pointer_for_type(item[1][0])]
+              else
+                pointer_for_type(item[1])
+              end
+            elsif item == WSTRING
+              # We have to convert the arg to a unicode string
+              string_to_utf16(args.shift)
+            elsif item == T_BOOL
+              args.shift ? 1 : 0
+            elsif item.to_s[0,1] == item.to_s[0,1].upcase
+              # Try to get the class from the interfaces
+              interface = interface_klass(item.to_sym)
+
+              if interface.superclass == COM::AbstractInterface
+                # For interfaces, get the instance, then dig deep to get the pointer
+                # to the VtblParent, which is what the API expects
+                instance = args.shift
+
+                if !instance.nil?
+                  instance.implementer.ffi_interface.vtbl_parent
+                else
+                  # If the argument was nil, just pass a nil pointer as the argument
+                  nil
+                end
+              elsif interface.superclass == COM::AbstractEnum
+                # For enums, we need the value of the enum
+                interface.index(args.shift.to_sym)
+              end
+            else
+              # Simply replace spec item with next item in args
+              # list
+              args.shift
+            end
+          end.flatten
+        end
+
+        # Takes a spec and a formal parameter list and returns the output from
+        # a function, properly dereferencing any output pointers.
+        #
+        # @param [Array] specs The parameter spec for the function
+        # @param [Array] formal The formal parameter list
+        def values_from_formal_args(specs, formal)
+          return_values = []
+          i = 0
+          specs.each do |spec|
+            # Output parameters are all we care about
+            if spec.is_a?(Array) && spec[0] == :out
+              if spec[1].is_a?(Array)
+                # We are dealing with formal[i] and formal[i+1] here, where
+                # the first has the size and the second has the contents
+                return_values << dereference_pointer_array(formal[i+1], spec[1][0], dereference_pointer(formal[i], T_UINT32))
+
+                # Increment once more to skip the size param
+                i += 1
+              else
+                return_values << dereference_pointer(formal[i], spec[1])
+              end
+            end
+
+            i += 1
+          end
+
+          if return_values.empty?
+            nil
+          elsif return_values.length == 1
+            return_values.first
+          else
+            return_values
+          end
+        end
+
+        # Dereferences a pointer with a given type into a proper Ruby object.
+        # If the type is a standard primitive of Ruby-FFI, it simply calls the
+        # proper `get_*` method on the pointer. Otherwise, it calls a
+        # `read_*` on the Util class.
+        #
+        # @param [FFI::MemoryPointer] pointer
+        # @param [Symbol] type The type of the pointer
+        # @return [Object] The value of the dereferenced pointer
+        def dereference_pointer(pointer, type)
+          c_type, inferred_type = infer_type(type)
+
+          if pointer.respond_to?("get_#{inferred_type}".to_sym)
+            # This handles reading the typical times such as :uint, :int, etc.
+            result = pointer.send("get_#{inferred_type}".to_sym, 0)
+            result = !(result == 0) if type == T_BOOL
+            result
+          else
+            send("read_#{inferred_type}".to_sym, pointer, type)
+          end
+        end
+
+        # Dereferences an array out of a pointer into an array of proper Ruby
+        # objects.
+        #
+        # @param [FFI::MemoryPointer] pointer
+        # @param [Symbol] type The type of the pointer
+        # @param [Fixnum] length The length of the array
+        # @return [Array<Object>]
+        def dereference_pointer_array(pointer, type, length)
+          # If there are no items in the pointer, just return an empty array
+          return [] if length == 0
+
+          c_type, inferred_type = infer_type(type)
+
+          array_pointer = pointer.get_pointer(0)
+          if array_pointer.respond_to?("get_array_of_#{inferred_type}".to_sym)
+            # This handles reading the typical times such as :uint, :int, etc.
+            array_pointer.send("get_array_of_#{inferred_type}".to_sym, 0, length)
+          else
+            send("read_array_of_#{inferred_type}".to_sym, array_pointer, type, length)
+          end
+        end
+
+        # Converts a symbol type into a MemoryPointer and yield a block
+        # with the pointer, the C type, and the FFI type
+        def pointer_for_type(type)
+          c_type, type = infer_type(type)
+
+          # Create the pointer, yield, returning the result of the block
+          # if a block is given, or otherwise just returning the pointer
+          # and inferred type
+          pointer = ::FFI::MemoryPointer.new(c_type)
+          if block_given?
+            yield pointer, type
+          else
+            pointer
+          end
+        end
+
+        # Converts a ruby string to a UTF16 string
+        #
+        # @param [String] Ruby String object
+        # @return [::FFI::Pointer]
+        def string_to_utf16(string)
+          return nil if string.nil?
+
+          ptr = pointer_for_type(:pointer)
+          lib.xpcom[:pfnUtf8ToUtf16].call(string, ptr)
+          ptr.read_pointer()
+        end
+
+        # Converts a UTF16 string to UTF8
+        def utf16_to_string(pointer)
+          result_pointer = pointer_for_type(:pointer)
+          lib.xpcom[:pfnUtf16ToUtf8].call(pointer, result_pointer)
+          lib.xpcom[:pfnUtf16Free].call(pointer)
+          result_pointer.read_pointer().read_string().to_s
+        end
+
+        # Reads a unicode string value from a pointer to that value.
+        #
+        # @return [String]
+        def read_unicode_string(ptr, original_type=nil)
+          address = ptr.get_pointer(0)
+          return "" if address.null?
+          utf16_to_string(address)
+        end
+
+        # Reads an interface from the pointer
+        #
+        # @return [::FFI::Struct]
+        def read_interface(ptr, original_type)
+          ptr = ptr.get_pointer(0)
+          return nil if ptr.null?
+
+          klass = interface_klass(original_type)
+          klass.new(self.class, lib, ptr)
+        end
+
+        # Reads an enum
+        #
+        # @return [Symbol]
+        def read_enum(ptr, original_type)
+          klass = interface_klass(original_type)
+          klass[ptr.get_uint(0)]
+        end
+
+        # Reads an array of enums
+        #
+        # @return [Array<Symbol>]
+        def read_array_of_enum(ptr, type, length)
+          klass = interface_klass(type)
+          ptr.get_array_of_uint(0, length).collect do |value|
+            klass[value]
+          end
+        end
+
+        # Reads an array of structs from a pointer
+        #
+        # @return [Array<::FFI::Struct>]
+        def read_array_of_interface(ptr, type, length)
+          klass = interface_klass(type)
+          ptr.get_array_of_pointer(0, length).collect do |single_pointer|
+            klass.new(self.class, lib, single_pointer)
+          end
+        end
+
+        # Reads an array of strings from a pointer
+        #
+        # @return [Array<String>]
+        def read_array_of_unicode_string(ptr, type, length)
+          ptr.get_array_of_pointer(0, length).collect do |single_pointer|
+            if single_pointer.null?
+              nil
+            else
+              utf16_to_string(single_pointer)
+            end
+          end
+        end
+      end
+    end
+  end
+end