virtualbox-com 0.9.6 → 0.9.7

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

@@ -73,6 +73,7 @@ module Lib
             # Load the interface description
             require "virtualbox/com/model/#{version}"
 
+            #
             @@virtualbox = Model.create(:VirtualBox, virtualbox_ptr)
             @@session    = Model.create(:Session,       session_ptr)
 

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

@@ -1,15 +1,16 @@
 module VirtualBox
 module COM
-    WSTRING = :unicode_string
+    WSTRING = :unicode_string	# \ 
+    BOOL    = :boolean		# | They are not FFI types
+    OCTET   = :octet		# / 
     INT8    = :int8
-    INT16   = :short
-    INT32   = :int
-    INT64   = :long
+    INT16   = :int16
+    INT32   = :int32
+    INT64   = :int64
     UINT8   = :uint8
-    UINT16  = :ushort
-    UINT32  = :uint
-    UINT64  = :ulong
-    BOOL    = :char
+    UINT16  = :uint16
+    UINT32  = :uint32
+    UINT64  = :uint64
 end
 end
 

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

@@ -2,52 +2,48 @@ module VirtualBox
 module COM
 module XPCOMC
 
+# Signatures are a list of type and direction (way: :in, :out)
+# The type supported are simple types which resolved to Symbol
+# or array of simple types
+#
+# These types need to be "converted" to be interpreted corretly
+# in the contexts of:
+#  - callback
+#  - writing arguments 
+#  - reading arguments
 class Sig
+    # Store and normalize signatures
     def initialize(sig)
-        @sig = sig.dup.freeze
+        @sig = sig.map {|item|
+            if item.is_a?(Array) && item[0] == :out 
+            then [ item[1], :out ]
+            else [ item,    :in  ]
+            end
+        }.freeze.each{|type, way|
+            # Sanity check: only `[type]` or `type`
+            if type.is_a?(Array) && type.length != 1
+                raise ArgumentError,  "only arrays of simple type are supported"
+            end
+        }
     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
+
+    # Converts a function signature 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`.
+    def to_ffi_callback
+        @sig.map {|type, way| is_array = type.is_a?(Array)
+            case way
+            when :out then is_array ? [:pointer, :pointer] : :pointer
+            when :in  then is_array ? [:uint32,  :pointer] : mangling(type)[0]
             end
-        end
-            
-        # Prepend a :pointer to represent the `this` parameter required
-        # for the FFI parameter lists
-        spec.unshift(:pointer).flatten
+        }.unshift(:pointer).flatten	# Add `this` element
     end
 
 
+    # Prepare arguments by converting them to C structures
     def prepare_args(args=[])
         args = args.dup
 
@@ -57,284 +53,240 @@ class Sig
     end
 
 
-
-
-    # Takes a spec and a formal parameter list and returns the output from
+    # Takes arguments 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
+    def read_values(args)
+        values, i = [], 0
+        @sig.each do |type, way|
+            # Array of type: [ type ] 
+            # Skip 2: size + pointer to array
+            if type.is_a?(Array)
+                if way == :out
+                    size, type = args[i].read_uint32, type[0]
+                    values << if type == OCTET
+                              then read_binary_blob(args[i+1], size)
+                              else get_array_by_type(args[i+1], type, size)
+                              end
                 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
+                i += 2  
+
+            # Simple type  : type
+            # Skip 1: pointer
             else
+                if way == :out
+                    values << read_by_type(args[i], type)
+                end
                 i += 1
             end
         end
         
-        if    return_values.empty?      then nil
-        elsif return_values.length == 1 then return_values.first
-        else                                 return_values
+        case values.size when 0 then nil
+                         when 1 then values.first
+                         else        values
         end
     end
 
 
 
+    #--[ Private ]---------------------------------------------------------
+    private
 
-
-
-
-
-
-
-
-
-
-
-    # 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}"
+    def mangling(type)
+        if    type == WSTRING                     then [ :pointer, type       ]
+        elsif type == BOOL                        then [ :int,     type       ]
+        elsif model = Model.fetch(type)
+            if    model <= COM::AbstractInterface then [ :pointer, :interface ]
+            elsif model <= COM::AbstractEnum      then [ :uint32,  :enum      ]
+            end
+        else                                           [ 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)
+        c_type, = mangling(type)
+        ::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)
+        type, way = item
+
+        case way
+        when :out
+            if type.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])
+                results << if type[0] == OCTET
+                           then pointer_for_type(:pointer)
+                           else pointer_for_type(type[0])
+                           end
             else
-                results << pointer_for_type(item[1])
+                results << pointer_for_type(type)
             end
-        elsif item.is_a?(Array) && item.length == 1
+        when :in
+            if type.is_a?(Array)
             # 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)
+                data = args.shift
+                
+                # First add the length of the array
+                results << data.length
+                
+                # Create the array
+                c_type, type = mangling(type.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], type[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], type.first, converted)
+                        array[i].put_pointer(0, converted.first)
+                    end
+                    
+                    results << array
                 end
+            elsif type == WSTRING
+                # We have to convert the arg to a unicode string
+                results << XPCOMC::Lib.xpcom.string_to_utf16(args.shift)
+            elsif type == BOOL
+                results << (args.shift ? 1 : 0)
+            elsif type.to_s[0,1] == type.to_s[0,1].upcase
+                # Try to get the class from the interfaces
+                interface = Model.get(type)
+                val = args.shift
                 
-                results << array
+                results << if interface.superclass == COM::AbstractInterface
+                               # For interfaces, we need the COM object
+                               val && val.implementer.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
-        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
 
 
 
 
+    
+    def read_by_type(ptr, type)
+        # Retrieve information
+        _, reader = mangling(type)
+
+        # Try default pointer reader
+        method = :"read_#{reader}"
+        return ptr.send(method) if ptr.respond_to?(method)
+
+        # Custom reader
+        case reader
+        when :unicode_string then read_unicode_string(ptr)
+        when :boolean        then read_boolean(ptr)
+        when :interface      then read_interface(ptr, type)
+        when :enum           then read_enum(ptr, type)
+        else raise "don't know how to dereference pointer of type #{type}"
+        end
+    end
+    
+    def get_array_by_type(ptr, type, length)
+        # Shortcut
+        return [] if length == 0
 
+        # Retrieve information
+        _, reader = mangling(type)
+        ary_ptr = ptr.read_pointer
+
+        # Try default pointer reader
+        method = :"get_array_of_#{reader}"
+        return ary_ptr.send(method, 0, length) if ary_ptr.respond_to?(method)
+
+        # Custom reader
+        case reader
+        when :unicode_string then get_array_of_unicode_string(ary_ptr, length)
+        when :boolean        then get_array_of_boolean(ary_ptr, length)
+        when :interface      then get_array_of_interface(ary_ptr, type, length)
+        when :enum           then get_array_of_enum(ary_ptr, type, length)
+        else raise "don't know how to dereference array of type #{type}"
+        end
+    ensure
+        XPCOMC::Lib.xpcom.free(ary_ptr)
+    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) || ''
+    ## Read_*
+    def read_binary_blob(ptr, size)
+        XPCOMC::Lib.xpcom.binary_to_string(ptr.read_pointer, size)
     end
+
+    def read_unicode_string(ptr)
+        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)
+    def read_boolean(ptr)
+        ptr.read_int != 0
+    end
+
+    def read_interface(ptr, name)
         ptr = ptr.read_pointer
         return nil if ptr.null?        
-        Model.create(original_type, ptr)
+        Model.create(name, ptr)
     end
     
-    # Reads an enum
-    #
-    # @return [Symbol]
-    def read_enum(ptr, original_type)
-        Model.get(original_type)[ptr.get_uint(0)]
+    def read_enum(ptr, name)
+        Model.get(name)[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]
+
+    ## get_array_of_*
+    def get_array_of_unicode_string(ptr, length)
+        ptr.get_array_of_pointer(0, length).map do |pointer|
+            XPCOMC::Lib.xpcom.utf16_to_string(pointer)
         end
     end
-    
-    # Reads an array of structs from a pointer
-    #
-    # @return [Array<::FFI::Struct>]
+
+    def get_array_of_boolean(ptr, length)
+        ptr.get_array_of_int(0, length).map do |value|
+            value != 0
+        end
+    end
+
     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)
+
+    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
-
-
+    
 end
 
 end