Class: FFI::Struct

Inherits:
Object
  • Object
show all
Defined in:
ext/ffi_c/Struct.c,
lib/ffi/struct.rb,
ext/ffi_c/Struct.c

Overview

A FFI::Struct means to mirror a C struct.

A Struct is defined as:

class MyStruct < FFI::Struct
  layout :value1, :int,
         :value2, :double
end

and is used as:

my_struct = MyStruct.new
my_struct[:value1] = 12

For more information, see github.com/ffi/ffi/wiki/Structs

Direct Known Subclasses

ManagedStruct, Union

Defined Under Namespace

Classes: InlineArray, ManagedStructConverter

Class Method Summary collapse

Instance Method Summary collapse

Class Method Details

.alignment ⇒ Fixnum

Returns Struct alignment.

Returns:

  • (Fixnum) —

    Struct alignment



104
105
106
 
# File 'lib/ffi/struct.rb', line 104

def self.alignment
  @layout.alignment
end

.array_layout(builder, spec) ⇒ builder (private)

Add array spec to builder.

Parameters:

Returns:

  • (builder) 


298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
 
# File 'lib/ffi/struct.rb', line 298

def array_layout(builder, spec)
  i = 0
  while i < spec.size
    name, type = spec[i, 2]
    i += 2

    # If the next param is a Integer, it specifies the offset
    if spec[i].kind_of?(Integer)
      offset = spec[i]
      i += 1
    else
      offset = nil
    end

    builder.add name, find_field_type(type), offset
  end
end

.auto_ptr ⇒ Object 



165
166
167
 
# File 'lib/ffi/struct.rb', line 165

def self.auto_ptr
  @managed_type ||= Type::Mapped.new(ManagedStructConverter.new(self))
end

.by_ref(flags = :inout) ⇒ Object 



143
144
145
 
# File 'lib/ffi/struct.rb', line 143

def self.by_ref(flags = :inout)
  self.ptr(flags)
end

.by_value ⇒ Object 



139
140
141
 
# File 'lib/ffi/struct.rb', line 139

def self.by_value
  self.val
end

.hash_layout(builder, spec) ⇒ builder (private)

Add hash spec to builder.

Parameters:

Returns:

  • (builder) 


288
289
290
291
292
 
# File 'lib/ffi/struct.rb', line 288

def hash_layout(builder, spec)
  spec[0].each do |name, type|
    builder.add name, find_field_type(type), nil
  end
end

.in ⇒ Object 



123
124
125
 
# File 'lib/ffi/struct.rb', line 123

def self.in
  ptr(:in)
end

.layout ⇒ StructLayout .layout(*spec) ⇒ StructLayout

Overloads:

  • .layout ⇒ StructLayout

    Get struct layout.

    Returns:

  • .layout(*spec) ⇒ StructLayout

    Create struct layout from spec.

    Examples:

    Creating a layout from an array spec

    class MyStruct < Struct
  layout :field1, :int,
         :field2, :pointer,
         :field3, :string
end

    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

    Creating a layout from a hash spec

    class MyStructFromHash < Struct
  layout :field1 => :int,
         :field2 => :pointer,
         :field3 => :string
end

    Creating a layout with pointers to functions

    class MyFunctionTable < Struct
  layout :function1, callback([:int, :int], :int),
         :function2, callback([:pointer], :void),
         :field3, :string
end

    Parameters:

    • spec (Array<Symbol, Integer>, Array(Hash))

    Returns:

Returns:



205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
 
# File 'lib/ffi/struct.rb', line 205

def layout(*spec)
  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)
  builder.alignment = @min_alignment if defined?(@min_alignment)

  if spec[0].kind_of?(Hash)
    hash_layout(builder, spec)
  else
    array_layout(builder, spec)
  end
  builder.size = @size if defined?(@size) && @size > builder.size
  cspec = builder.build
  @layout = cspec unless self == Struct
  @size = cspec.size
  return cspec
end

.members ⇒ Object 



109
110
111
 
# File 'lib/ffi/struct.rb', line 109

def self.members
  @layout.members
end

.offset_of(name) ⇒ Numeric

Get the offset of a field.

Returns:

  • (Numeric) 


119
120
121
 
# File 'lib/ffi/struct.rb', line 119

def self.offset_of(name)
  @layout.offset_of(name)
end

.offsets ⇒ Array<Array(Symbol, Numeric)>

Get an array of tuples (field name, offset of the field).

Returns:

  • (Array<Array(Symbol, Numeric)>) —

    Array<Array(Symbol, Numeric)>



114
115
116
 
# File 'lib/ffi/struct.rb', line 114

def self.offsets
  @layout.offsets
end

.out ⇒ Object 



127
128
129
 
# File 'lib/ffi/struct.rb', line 127

def self.out
  ptr(:out)
end

.ptr(flags = :inout) ⇒ Object 



131
132
133
 
# File 'lib/ffi/struct.rb', line 131

def self.ptr(flags = :inout)
  @ref_data_type ||= Type::Mapped.new(StructByReference.new(self))
end

.size ⇒ Numeric

Get struct size

Returns:

  • (Numeric) 


91
92
93
 
# File 'lib/ffi/struct.rb', line 91

def self.size
  defined?(@layout) ? @layout.size : defined?(@size) ? @size : 0
end

.size=(size) ⇒ size

set struct size

Parameters:

  • size (Numeric)

Returns:

Raises:

  • (ArgumentError) 


98
99
100
101
 
# File 'lib/ffi/struct.rb', line 98

def self.size=(size)
  raise ArgumentError, "Size already set" if defined?(@size) || defined?(@layout)
  @size = size
end

.val ⇒ Object 



135
136
137
 
# File 'lib/ffi/struct.rb', line 135

def self.val
  @val_data_type ||= StructByValue.new(self)
end

Instance Method Details

#align ⇒ Fixnum

Returns Struct alignment.

Returns:

  • (Fixnum) —

    Struct alignment



53
54
55
 
# File 'lib/ffi/struct.rb', line 53

def alignment
  self.class.alignment
end

#alignment ⇒ Fixnum

Returns Struct alignment.

Returns:

  • (Fixnum) —

    Struct alignment



50
51
52
 
# File 'lib/ffi/struct.rb', line 50

def alignment
  self.class.alignment
end

#clear ⇒ self

Clear the struct content.

Returns:

  • (self) 


78
79
80
81
 
# File 'lib/ffi/struct.rb', line 78

def clear
  pointer.clear
  self
end

#members ⇒ Array<Symbol>

Get list of field names.

Returns:

  • (Array<Symbol>) 


61
62
63
 
# File 'lib/ffi/struct.rb', line 61

def members
  self.class.members
end

#offset_of(name) ⇒ Numeric

Get the offset of a field.

Returns:

  • (Numeric) 


56
57
58
 
# File 'lib/ffi/struct.rb', line 56

def offset_of(name)
  self.class.offset_of(name)
end

#offsets ⇒ Array<Array(Symbol, Numeric)>

Get an array of tuples (field name, offset of the field).

Returns:

  • (Array<Array(Symbol, Numeric)>) —

    Array<Array(Symbol, Numeric)>



72
73
74
 
# File 'lib/ffi/struct.rb', line 72

def offsets
  self.class.offsets
end

#size ⇒ Numeric

Get struct size

Returns:

  • (Numeric) 


45
46
47
 
# File 'lib/ffi/struct.rb', line 45

def size
  self.class.size
end

#to_ptr ⇒ AbstractMemory

Get Pointer to struct content.

Returns:



85
86
87
 
# File 'lib/ffi/struct.rb', line 85

def to_ptr
  pointer
end

#values ⇒ Array

Get array of values from Struct fields.

Returns:

  • (Array) 


67
68
69
 
# File 'lib/ffi/struct.rb', line 67

def values
  members.map { |m| self[m] }
end