virtualbox-com 0.9.6

data/lib/virtualbox/com/xpcomc-ffi/lib.rb

@@ -0,0 +1,90 @@
+require 'virtualbox/com/util'
+
+module VirtualBox
+module COM
+module XPCOMC
+
+
+module Lib
+    extend ::FFI::Library
+
+    # Constant with default library path and name
+    # according to running plateform
+    PATH = case Util.platform
+           when :mac
+               [ "/Applications/VirtualBox.app/Contents/MacOS",
+                 "/Applications/MacPorts/VirtualBox.app/Contents/MacOS" ]
+           when :linux
+               [ "/opt/VirtualBox", 
+                 "/usr/lib/virtualbox",
+                 "/usr/lib64/virtualbox" ]
+           when :solaris
+               [ "/opt/VirtualBox/amd64",
+                 "/opt/VirtualBox/i386" ]
+           when :freebsd
+               [ "/usr/local/lib/virtualbox" ]
+           else 
+               [ ]
+           end
+
+    NAME = case Util.platform
+           when :max then "VBoxXPCOMC.dylib"
+           else           "VBoxXPCOMC.so"
+           end
+
+
+    def self.init
+        # Only once
+        return if respond_to?(:VBoxGetXPCOMCFunctions)
+
+        # Initialize lib and attach main function
+        ffi_lib_flags(:now, :local)
+        ffi_lib(ENV['VBOX_APP_HOME'] || PATH.map {|path| "#{path}/#{NAME}"})
+        attach_function :VBoxGetXPCOMCFunctions, [:uint], :pointer
+
+    
+        # Get the pointer to the XPCOMC struct which contains the functions
+        # to initialize
+        xpcom_ptr = self.VBoxGetXPCOMCFunctions(XPCOMC::VERSION)
+        @@xpcom = XPCOMC::VBox.new(xpcom_ptr)
+
+
+        # Initializes the VirtualBox and Session interfaces.
+        # It goes through the various supported interfaces.
+        SUPPORTED_VERSIONS.each {|version, iids|
+            virtualbox_iid_str, session_iid_str = iids
+
+            # Setup the OUT pointers
+            virtualbox_ptr = ::FFI::MemoryPointer.new(:pointer)
+               session_ptr = ::FFI::MemoryPointer.new(:pointer)
+
+            # Call the initialization functions
+            @@xpcom[:pfnComInitialize].call(virtualbox_iid_str, virtualbox_ptr,
+                                               session_iid_str,    session_ptr)
+
+            # Read the pointers from the results 
+            virtualbox_ptr = virtualbox_ptr.read_pointer
+               session_ptr =    session_ptr.read_pointer
+
+            # If either pointers are null it means that 
+            # the initialization was not successful
+            next if virtualbox_ptr.null? || session_ptr.null?
+
+            # Load the interface description
+            require "virtualbox/com/model/#{version}"
+
+            @@virtualbox = Model.create(:VirtualBox, virtualbox_ptr)
+            @@session    = Model.create(:Session,       session_ptr)
+
+            break
+        }
+    end
+
+    def self.xpcom      ; @@xpcom      ; end
+    def self.virtualbox ; @@virtualbox ; end
+    def self.session    ; @@session    ; end
+end
+
+end
+end
+end

data/lib/virtualbox/com/xpcomc-ffi/model-types.rb

@@ -0,0 +1,15 @@
+module VirtualBox
+module COM
+    WSTRING = :unicode_string
+    INT8    = :int8
+    INT16   = :short
+    INT32   = :int
+    INT64   = :long
+    UINT8   = :uint8
+    UINT16  = :ushort
+    UINT32  = :uint
+    UINT64  = :ulong
+    BOOL    = :char
+end
+end
+

data/lib/virtualbox/com/xpcomc-ffi/sig.rb

@@ -0,0 +1,342 @@
+module VirtualBox
+module COM
+module XPCOMC
+
+class Sig
+    def initialize(sig)
+        @sig = sig.dup.freeze
+    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 to_ffi
+        spec = @sig.map 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
+                [ UINT32, :pointer ]
+            elsif item == WSTRING
+                # Unicode strings are simply pointers
+                :pointer
+            elsif item.to_s[0,1] == item.to_s[0,1].upcase
+                # Try to get the class from the interfaces
+                Model.get(item).to_ffi
+            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
+
+
+    def prepare_args(args=[])
+        args = args.dup
+
+        results = @sig.inject([]) do |results, item|
+            single_type_to_arg(args, item, results)
+        end
+    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 retrieve_values(formal)
+        return_values = []
+        i = 0
+        @sig.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], UINT32))
+                    
+                    # Skip 2: size param + pointer
+                    i += 2
+                else
+                    return_values << dereference_pointer(formal[i], spec[1])
+                    
+                    # Skip 1: Pointer
+                    i += 1
+                end
+            elsif spec.is_a?(Array) && spec.length == 1
+                # This is an array argument, meaning it takes two
+                # arguments: one for size and one is a pointer to the
+                # array items. Therefore, skip two items.
+                i += 2
+            else
+                i += 1
+            end
+        end
+        
+        if    return_values.empty?      then nil
+        elsif return_values.length == 1 then 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 Binding 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)        
+        method = :"read_#{inferred_type}"
+
+        if pointer.respond_to?(method)
+            result = pointer.send(method)
+            result = result != 0 if type == BOOL
+            result
+        elsif respond_to?(method)
+            send(method, pointer, type)
+        else
+            raise "don't know how to dereference pointer of type #{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)
+        return [] if length == 0
+        
+        c_type, inferred_type = infer_type(type)
+        method = :"get_array_of_#{inferred_type}"
+
+        array_pointer = pointer.get_pointer(0)
+
+        if array_pointer.respond_to?(method)
+            array_pointer.send(method, 0, length)
+        elsif respond_to?(method)
+            send(method, array_pointer, type, length)
+        else
+            raise "don't know how to dereference array of type #{type}"
+        end
+    end
+
+
+
+    def pointer_for_type(type)
+        c_type, type = infer_type(type)
+        pointer = ::FFI::MemoryPointer.new(c_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 = Model.get(type)
+                
+                c_type = :pointer
+                
+                # Depending on the class type, we're either dealing with an 
+                # interface or an enum
+                if    interface.superclass == COM::AbstractInterface
+                    c_type, type = :pointer, :interface
+                elsif interface.superclass == COM::AbstractEnum
+                    c_type, type = :uint32,  :enum
+                end
+            end
+        rescue ModelNotFoundException
+            # Do nothing
+        end
+        
+        [c_type, type]
+    end
+
+
+    # Converts a single type and args list to the proper formal args list
+    def single_type_to_arg(args, item, results)
+        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
+                results << pointer_for_type(UINT32)
+                results << pointer_for_type(item[1][0])
+            else
+                results << pointer_for_type(item[1])
+            end
+        elsif item.is_a?(Array) && item.length == 1
+            # Array argument
+            data = args.shift
+
+            # First add the length of the array
+            results << data.length
+
+            # Create the array
+            c_type, type = infer_type(item.first)
+            
+            # If its a regular type (int, bool, etc.) then just make it an
+            # array of that
+            if type != :interface
+              # Build a pointer to an array of values
+                result = ::FFI::MemoryPointer.new(c_type, data.length)
+                adder = result.method("put_#{c_type}")
+                data.each_with_index do |single, index|
+                    value = []
+                    single_type_to_arg([single], item[0], value)
+                    adder.call(index, value.first)
+                end
+
+                results << result
+            else
+                # Then convert the rest into a raw MemoryPointer
+                array = ::FFI::MemoryPointer.new(:pointer, data.length)
+                data.each_with_index do |datum, i|
+                    converted = []
+                    single_type_to_arg([datum], item.first, converted)
+                    array[i].put_pointer(0, converted.first)
+                end
+                
+                results << array
+            end
+        elsif item == WSTRING
+            # We have to convert the arg to a unicode string
+            results << XPCOMC::Lib.xpcom.string_to_utf16(args.shift)
+        elsif item == BOOL
+            results << (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 = Model.get(item)
+            val = args.shift
+
+            results << 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
+                           val && val.implementer.binding.object
+                       elsif interface.superclass == COM::AbstractEnum
+                           # For enums, we need the value of the enum
+                           interface.index(val)
+                       end
+        else
+            # Simply replace spec item with next item in args
+            # list
+            results << args.shift
+        end
+    end
+
+
+
+
+
+
+
+    # Reads a unicode string value from a pointer to that value.
+    #
+    # @return [String]
+    def read_unicode_string(ptr, original_type=nil)
+        XPCOMC::Lib.xpcom.utf16_to_string(ptr.read_pointer) || ''
+    end
+    
+    # Reads an interface from the pointer
+    #
+    # @return [::FFI::Struct]
+    def read_interface(ptr, original_type)
+        ptr = ptr.read_pointer
+        return nil if ptr.null?        
+        Model.create(original_type, ptr)
+    end
+    
+    # Reads an enum
+    #
+    # @return [Symbol]
+    def read_enum(ptr, original_type)
+        Model.get(original_type)[ptr.get_uint(0)]
+    end
+    
+    # Reads an array of enums
+    #
+    # @return [Array<Symbol>]
+    def get_array_of_enum(ptr, type, length)
+        klass = Model.get(type)
+        ptr.get_array_of_uint(0, length).map do |value|
+            klass[value]
+        end
+    end
+    
+    # Reads an array of structs from a pointer
+    #
+    # @return [Array<::FFI::Struct>]
+    def get_array_of_interface(ptr, type, length)
+        klass = Model.get(type)
+        ptr.get_array_of_pointer(0, length).map do |pointer|
+            klass.new(pointer)
+        end
+    end
+    
+    # Reads an array of strings from a pointer
+    #
+    # @return [Array<String>]
+    def get_array_of_unicode_string(ptr, type, length)
+        ptr.get_array_of_pointer(0, length).map do |pointer|
+            XPCOMC::Lib.xpcom.utf16_to_string(pointer)
+        end
+    end
+
+
+end
+
+end
+end
+end

data/lib/virtualbox/com/xpcomc-ffi/spec.rb

@@ -0,0 +1,58 @@
+require_relative 'sig'
+
+module VirtualBox
+module COM
+module XPCOMC
+
+class Spec
+    attr_reader :name
+
+    def hide?
+        @opts[:hide]
+    end
+
+    class Function < Spec
+        def initialize(name, type, args, opts)
+            @name, @type, @args, @opts = name, type, args, opts
+        end
+
+        def signatures
+            { name => to_call }
+        end
+
+        def to_call
+            Sig.new( if @type.nil?
+                     then @args
+                     else @args + [ [ :out, @type ] ]
+                     end)
+        end
+    end
+    
+    class Property < Spec
+        attr_reader :getter, :setter
+
+        def initialize(name, type, opts) 
+            @name, @type, @opts = name, type, opts
+        end
+
+        def signatures
+            r = {}
+            r[getter] = to_read 
+            r[setter] = to_write unless self.readonly?
+            r
+        end
+
+        def readonly?
+            @opts[:readonly]
+        end
+
+        def getter	; :"get_#{@name}" 		; end
+        def setter	; :"set_#{@name}" 		; end
+        def to_read	; Sig.new([[:out, @type]]) 	; end
+        def to_write	; Sig.new([ @type ]) 		; end
+    end
+end
+
+end
+end
+end