ffi 1.0.0 → 1.17.1

data/lib/ffi/struct.rb

@@ -3,138 +3,119 @@
 # Copyright (C) 2008, 2009 Andrea Fazzi
 # Copyright (C) 2008, 2009 Luc Heinrich
 #
-# All rights reserved.
-#
 # This file is part of ruby-ffi.
 #
-# This code is free software: you can redistribute it and/or modify it under
-# the terms of the GNU Lesser General Public License version 3 only, as
-# published by the Free Software Foundation.
+# All rights reserved.
 #
-# This code is distributed in the hope that it will be useful, but WITHOUT
-# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
-# FITNESS FOR A PARTICULAR PURPOSE.  See the GNU Lesser General Public License
-# version 3 for more details.
+# Redistribution and use in source and binary forms, with or without
+# modification, are permitted provided that the following conditions are met:
 #
-# You should have received a copy of the GNU Lesser General Public License
-# version 3 along with this work.  If not, see <http://www.gnu.org/licenses/>.
+# * Redistributions of source code must retain the above copyright notice, this
+#   list of conditions and the following disclaimer.
+# * Redistributions in binary form must reproduce the above copyright notice
+#   this list of conditions and the following disclaimer in the documentation
+#   and/or other materials provided with the distribution.
+# * Neither the name of the Ruby FFI project nor the names of its contributors
+#   may be used to endorse or promote products derived from this software
+#   without specific prior written permission.
+#
+# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+# AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+# IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+# DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE
+# FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+# DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+# SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+# CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+# OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+# OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 #
 
 require 'ffi/platform'
+require 'ffi/struct_layout'
 require 'ffi/struct_layout_builder'
+require 'ffi/struct_by_reference'
 
 module FFI
 
-  class StructLayout
-
-    def offsets
-      members.map { |m| [ m, self[m].offset ] }
-    end
-
-    def offset_of(field_name)
-      self[field_name].offset
-    end
-
-    class Enum < Field
-      
-      def get(ptr)
-        type.find(ptr.get_int(offset))
-      end
-
-      def put(ptr, value)
-        ptr.put_int(offset, type.find(value))
-      end
-
-    end
-
-    class InnerStruct < Field
-      def get(ptr)
-        type.struct_class.new(ptr.slice(self.offset, self.size))
-      end
-
-#      def put(ptr, value)
-#        raise TypeError, "wrong value type (expected #{type.struct_class}" unless value.is_a(type.struct_class)
-#      end
-    end
-
-    class Mapped < Field
-      def initialize(name, offset, type, orig_field)
-        super(name, offset, type)
-        @orig_field = orig_field
-      end
-
-      def get(ptr)
-        type.from_native(@orig_field.get(ptr), nil)
-      end
-
-      def put(ptr, value)
-        @orig_field.put(ptr, type.to_native(value, nil))
-      end
-    end
-  end
-
-  
   class Struct
 
+    # Get struct size
+    # @return [Integer]
     def size
       self.class.size
     end
 
+    # @return [Integer] Struct alignment
     def alignment
       self.class.alignment
     end
     alias_method :align, :alignment
 
+    # (see FFI::StructLayout#offset_of)
     def offset_of(name)
       self.class.offset_of(name)
     end
 
+    # (see FFI::StructLayout#members)
     def members
       self.class.members
     end
 
+    # @return [Array]
+    # Get array of values from Struct fields.
     def values
       members.map { |m| self[m] }
     end
 
+    # (see FFI::StructLayout#offsets)
     def offsets
       self.class.offsets
     end
 
+    # Clear the struct content.
+    # @return [self]
     def clear
       pointer.clear
       self
     end
 
+    # Get {Pointer} to struct content.
+    # @return [AbstractMemory]
     def to_ptr
       pointer
     end
 
+    # Get struct size
+    # @return [Integer]
     def self.size
       defined?(@layout) ? @layout.size : defined?(@size) ? @size : 0
     end
 
+    # set struct size
+    # @param [Integer] size
+    # @return [size]
     def self.size=(size)
       raise ArgumentError, "Size already set" if defined?(@size) || defined?(@layout)
       @size = size
     end
 
+    # @return (see Struct#alignment)
     def self.alignment
       @layout.alignment
     end
 
-    def self.align
-      @layout.alignment
-    end
-
+    # (see FFI::Type#members)
     def self.members
       @layout.members
     end
 
+    # (see FFI::StructLayout#offsets)
     def self.offsets
       @layout.offsets
     end
 
+    # (see FFI::StructLayout#offset_of)
     def self.offset_of(name)
       @layout.offset_of(name)
     end
@@ -165,6 +146,7 @@ module FFI
 
     class ManagedStructConverter < StructByReference
 
+      # @param [Struct] struct_class
       def initialize(struct_class)
         super(struct_class)
 
@@ -172,6 +154,9 @@ module FFI
         @method = struct_class.method(:release)
       end
 
+      # @param [Pointer] ptr
+      # @param [nil] ctx
+      # @return [Struct]
       def from_native(ptr, ctx)
         struct_class.new(AutoPointer.new(ptr, @method))
       end
@@ -185,10 +170,43 @@ module FFI
     class << self
       public
 
+      # @return [StructLayout]
+      # @overload layout
+      #  @return [StructLayout]
+      #  Get struct layout.
+      # @overload layout(*spec)
+      #  @param [Array<Symbol, Integer>,Array(Hash)] spec
+      #  @return [StructLayout]
+      #  Create struct layout from +spec+.
+      #  @example Creating a layout from an array +spec+
+      #    class MyStruct < Struct
+      #      layout :field1, :int,
+      #             :field2, :pointer,
+      #             :field3, :string
+      #    end
+      #  @example Creating a layout from an array +spec+ with offset
+      #    class MyStructWithOffset < Struct
+      #      layout :field1, :int,
+      #             :field2, :pointer, 6,  # set offset to 6 for this field
+      #             :field3, :string
+      #    end
+      #  @example Creating a layout from a hash +spec+
+      #    class MyStructFromHash < Struct
+      #      layout :field1 => :int,
+      #             :field2 => :pointer,
+      #             :field3 => :string
+      #    end
+      #  @example Creating a layout with pointers to functions
+      #    class MyFunctionTable < Struct
+      #      layout :function1, callback([:int, :int], :int),
+      #             :function2, callback([:pointer], :void),
+      #             :field3, :string
+      #    end
       def layout(*spec)
-#        raise RuntimeError, "struct layout already defined for #{self.inspect}" if defined?(@layout)
         return @layout if spec.size == 0
 
+        warn "[DEPRECATION] Struct layout is already defined for class #{self.inspect}. Redefinition as in #{caller[0]} will be disallowed in ffi-2.0." if defined?(@layout)
+
         builder = StructLayoutBuilder.new
         builder.union = self < Union
         builder.packed = @packed if defined?(@packed)
@@ -211,14 +229,18 @@ module FFI
 
       def callback(params, ret)
         mod = enclosing_module
-        FFI::CallbackInfo.new(find_type(ret, mod), params.map { |e| find_type(e, mod) })
+        ret_type = find_type(ret, mod)
+        if ret_type == Type::STRING
+          raise TypeError, ":string is not allowed as return type of callbacks"
+        end
+        FFI::CallbackInfo.new(ret_type, params.map { |e| find_type(e, mod) })
       end
 
       def packed(packed = 1)
         @packed = packed
       end
       alias :pack :packed
-      
+
       def aligned(alignment = 1)
         @min_alignment = alignment
       end
@@ -227,8 +249,10 @@ module FFI
       def enclosing_module
         begin
           mod = self.name.split("::")[0..-2].inject(Object) { |obj, c| obj.const_get(c) }
-          mod.respond_to?(:find_type) ? mod : nil
-        rescue Exception => ex
+          if mod.respond_to?(:find_type) && (mod.is_a?(FFI::Library) || mod < FFI::Struct)
+            mod
+          end
+        rescue Exception
           nil
         end
       end
@@ -257,13 +281,20 @@ module FFI
 
       private
 
+      # @param [StructLayoutBuilder] builder
+      # @param [Hash] spec
+      # @return [builder]
+      # Add hash +spec+ to +builder+.
       def hash_layout(builder, spec)
-        raise "Ruby version not supported" if RUBY_VERSION =~ /1.8.*/
         spec[0].each do |name, type|
           builder.add name, find_field_type(type), nil
         end
       end
 
+      # @param [StructLayoutBuilder] builder
+      # @param [Array<Symbol, Integer>] spec
+      # @return [builder]
+      # Add array +spec+ to +builder+.
       def array_layout(builder, spec)
         i = 0
         while i < spec.size

data/lib/ffi/struct_by_reference.rb

@@ -0,0 +1,72 @@
+#
+# Copyright (C) 2010 Wayne Meissner
+#
+# This file is part of ruby-ffi.
+#
+# All rights reserved.
+#
+# Redistribution and use in source and binary forms, with or without
+# modification, are permitted provided that the following conditions are met:
+#
+# * Redistributions of source code must retain the above copyright notice, this
+#   list of conditions and the following disclaimer.
+# * Redistributions in binary form must reproduce the above copyright notice
+#   this list of conditions and the following disclaimer in the documentation
+#   and/or other materials provided with the distribution.
+# * Neither the name of the Ruby FFI project nor the names of its contributors
+#   may be used to endorse or promote products derived from this software
+#   without specific prior written permission.
+#
+# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+# AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+# IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+# DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE
+# FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+# DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+# SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+# CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+# OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+# OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.#
+
+module FFI
+  # This class includes the {FFI::DataConverter} module.
+  class StructByReference
+    include DataConverter
+
+    attr_reader :struct_class
+
+    # @param [Struct] struct_class
+    def initialize(struct_class)
+      unless Class === struct_class and struct_class < FFI::Struct
+        raise TypeError, 'wrong type (expected subclass of FFI::Struct)'
+      end
+      @struct_class = struct_class
+    end
+
+    # Always get {FFI::Type}::POINTER.
+    def native_type
+      FFI::Type::POINTER
+    end
+
+    # @param [nil, Struct] value
+    # @param [nil] ctx
+    # @return [AbstractMemory] Pointer on +value+.
+    def to_native(value, ctx)
+      return Pointer::NULL if value.nil?
+
+      unless @struct_class === value
+        raise TypeError, "wrong argument type #{value.class} (expected #{@struct_class})"
+      end
+
+      value.pointer
+    end
+
+    # @param [AbstractMemory] value
+    # @param [nil] ctx
+    # @return [Struct]
+    # Create a struct from content of memory +value+.
+    def from_native(value, ctx)
+      @struct_class.new(value)
+    end
+  end
+end

data/lib/ffi/struct_layout.rb

@@ -0,0 +1,96 @@
+#
+# Copyright (C) 2008-2010 Wayne Meissner
+# Copyright (C) 2008, 2009 Andrea Fazzi
+# Copyright (C) 2008, 2009 Luc Heinrich
+#
+# This file is part of ruby-ffi.
+#
+# All rights reserved.
+#
+# Redistribution and use in source and binary forms, with or without
+# modification, are permitted provided that the following conditions are met:
+#
+# * Redistributions of source code must retain the above copyright notice, this
+#   list of conditions and the following disclaimer.
+# * Redistributions in binary form must reproduce the above copyright notice
+#   this list of conditions and the following disclaimer in the documentation
+#   and/or other materials provided with the distribution.
+# * Neither the name of the Ruby FFI project nor the names of its contributors
+#   may be used to endorse or promote products derived from this software
+#   without specific prior written permission.
+#
+# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+# AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+# IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+# DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE
+# FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+# DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+# SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+# CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+# OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+# OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+#
+
+module FFI
+
+  class StructLayout
+
+    # @return [Array<Array(Symbol, Integer)>
+    # Get an array of tuples (field name, offset of the field).
+    def offsets
+      members.map { |m| [ m, self[m].offset ] }
+    end
+
+    # @return [Integer]
+    # Get the offset of a field.
+    def offset_of(field_name)
+      self[field_name].offset
+    end
+
+    # An enum {Field} in a {StructLayout}.
+    class Enum < Field
+
+      # @param [AbstractMemory] ptr pointer on a {Struct}
+      # @return [Object]
+      # Get an object of type {#type} from memory pointed by +ptr+.
+      def get(ptr)
+        type.find(ptr.get_int(offset))
+      end
+
+      # @param [AbstractMemory] ptr pointer on a {Struct}
+      # @param  value
+      # @return [nil]
+      # Set +value+ into memory pointed by +ptr+.
+      def put(ptr, value)
+        ptr.put_int(offset, type.find(value))
+      end
+
+    end
+
+    class InnerStruct < Field
+      def get(ptr)
+        type.struct_class.new(ptr.slice(self.offset, self.size))
+      end
+
+     def put(ptr, value)
+       raise TypeError, "wrong value type (expected #{type.struct_class})" unless value.is_a?(type.struct_class)
+       ptr.slice(self.offset, self.size).__copy_from__(value.pointer, self.size)
+     end
+    end
+
+    class Mapped < Field
+      def initialize(name, offset, type, orig_field)
+        @orig_field = orig_field
+        super(name, offset, type)
+      end
+
+      def get(ptr)
+        type.from_native(@orig_field.get(ptr), nil)
+      end
+
+      def put(ptr, value)
+        @orig_field.put(ptr, type.to_native(value, nil))
+      end
+    end
+  end
+end

data/lib/ffi/struct_layout_builder.rb

@@ -1,27 +1,41 @@
 #
 # Copyright (C) 2008-2010 Wayne Meissner
 #
-# All rights reserved.
-#
 # This file is part of ruby-ffi.
 #
-# This code is free software: you can redistribute it and/or modify it under
-# the terms of the GNU Lesser General Public License version 3 only, as
-# published by the Free Software Foundation.
+# All rights reserved.
 #
-# This code is distributed in the hope that it will be useful, but WITHOUT
-# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
-# FITNESS FOR A PARTICULAR PURPOSE.  See the GNU Lesser General Public License
-# version 3 for more details.
+# Redistribution and use in source and binary forms, with or without
+# modification, are permitted provided that the following conditions are met:
 #
-# You should have received a copy of the GNU Lesser General Public License
-# version 3 along with this work.  If not, see <http://www.gnu.org/licenses/>.
+# * Redistributions of source code must retain the above copyright notice, this
+#   list of conditions and the following disclaimer.
+# * Redistributions in binary form must reproduce the above copyright notice
+#   this list of conditions and the following disclaimer in the documentation
+#   and/or other materials provided with the distribution.
+# * Neither the name of the Ruby FFI project nor the names of its contributors
+#   may be used to endorse or promote products derived from this software
+#   without specific prior written permission.
+#
+# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+# AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+# IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+# DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE
+# FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+# DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+# SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+# CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+# OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+# OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 #
 
 module FFI
+
+  # Build a {StructLayout struct layout}.
   class StructLayoutBuilder
-    attr_reader :size, :alignment
-    
+    attr_reader :size
+    attr_reader :alignment
+
     def initialize
       @size = 0
       @alignment = 1
@@ -31,25 +45,49 @@ module FFI
       @fields = Array.new
     end
 
+    # Set size attribute with +size+ only if +size+ is greater than attribute value.
+    # @param [Integer] size
     def size=(size)
       @size = size if size > @size
     end
 
+    # Set alignment attribute with +align+ only if it is greater than attribute value.
+    # @param [Integer] align
     def alignment=(align)
       @alignment = align if align > @alignment
       @min_alignment = align
     end
 
+    # Set union attribute.
+    # Set to +true+ to build a {Union} instead of a {Struct}.
+    # @param [Boolean] is_union
+    # @return [is_union]
     def union=(is_union)
       @union = is_union
     end
 
+    # Building a {Union} or a {Struct} ?
+    #
+    # @return [Boolean]
+    #
     def union?
       @union
     end
 
+    # Set packed attribute
+    # @overload packed=(packed) Set alignment and packed attributes to
+    #   +packed+.
+    #
+    #   @param [Integer] packed
+    #
+    #   @return [packed]
+    # @overload packed=(packed) Set packed attribute.
+    #   @param packed
+    #
+    #   @return [0,1]
+    #
     def packed=(packed)
-      if packed.is_a?(Fixnum)
+      if packed.is_a?(0.class)
         @alignment = packed
         @packed = packed
       else
@@ -58,6 +96,7 @@ module FFI
     end
 
 
+    # List of number types
     NUMBER_TYPES = [
       Type::INT8,
       Type::UINT8,
@@ -71,8 +110,16 @@ module FFI
       Type::UINT64,
       Type::FLOAT32,
       Type::FLOAT64,
-    ]
-
+      Type::LONGDOUBLE,
+      Type::BOOL,
+    ].freeze
+
+    # @param [String, Symbol] name name of the field
+    # @param [Array, DataConverter, Struct, StructLayout::Field, Symbol, Type] type type of the field
+    # @param [Integer, nil] offset
+    # @return [self]
+    # Add a field to the builder.
+    # @note Setting +offset+ to +nil+ or +-1+ is equivalent to +0+.
     def add(name, type, offset = nil)
 
       if offset.nil? || offset == -1
@@ -90,31 +137,53 @@ module FFI
       return self
     end
 
+    # @param (see #add)
+    # @return (see #add)
+    # Same as {#add}.
+    # @see #add
     def add_field(name, type, offset = nil)
       add(name, type, offset)
     end
-    
+
+    # @param (see #add)
+    # @return (see #add)
+    # Add a struct as a field to the builder.
     def add_struct(name, type, offset = nil)
       add(name, Type::Struct.new(type), offset)
     end
 
+    # @param name (see #add)
+    # @param type (see #add)
+    # @param [Integer] count array length
+    # @param offset (see #add)
+    # @return (see #add)
+    # Add an array as a field to the builder.
     def add_array(name, type, count, offset = nil)
       add(name, Type::Array.new(type, count), offset)
     end
 
+    # @return [StructLayout]
+    # Build and return the struct layout.
     def build
       # Add tail padding if the struct is not packed
       size = @packed ? @size : align(@size, @alignment)
-      
-      StructLayout.new(@fields, size, @alignment)
+
+      layout = StructLayout.new(@fields, size, @alignment)
+      layout.__union! if @union
+      layout
     end
 
     private
-    
+
+    # @param [Integer] offset
+    # @param [Integer] align
+    # @return [Integer]
     def align(offset, align)
       align + ((offset - 1) & ~(align - 1));
     end
 
+    # @param (see #add)
+    # @return [StructLayout::Field]
     def field_for_type(name, offset, type)
       field_class = case
       when type.is_a?(Type::Function)
@@ -155,4 +224,4 @@ module FFI
     end
   end
 
-end
+end