Class: Cosmos::Structure

Inherits:
Object show all
Defined in:
lib/cosmos/packets/structure.rb,
ext/cosmos/ext/structure/structure.c

Overview

Maintains knowledge of a raw binary structure. Uses structure_item to create individual structure items which are read and written by binary_accessor.

Defined Under Namespace

Modules: MethodMissing

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(*args) ⇒ Object

Structure constructor

Parameters:

  • default_endianness (Symbol) —

    Must be one of BinaryAccessor::ENDIANNESS. By default it uses BinaryAccessor::HOST_ENDIANNESS to determine the endianness of the host platform.

  • buffer (String) —

    Buffer used to store the structure

  • item_class (Class) —

    Class used to instantiate new structure items. Must be StructureItem or one of its subclasses.



746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
 
# File 'ext/cosmos/ext/structure/structure.c', line 746

static VALUE structure_initialize(int argc, VALUE* argv, VALUE self) {
  VALUE default_endianness = Qnil;
  VALUE buffer = Qnil;
  VALUE item_class = Qnil;

  switch (argc)
  {
    case 0:
      default_endianness = HOST_ENDIANNESS;
      buffer = rb_str_new2("");
      item_class = cStructureItem;
      break;
    case 1:
      default_endianness = argv[0];
      buffer = rb_str_new2("");
      item_class = cStructureItem;
      break;
    case 2:
      default_endianness = argv[0];
      buffer = argv[1];
      item_class = cStructureItem;
      break;
    case 3:
      default_endianness = argv[0];
      buffer = argv[1];
      item_class = argv[2];
      break;
    default:
      /* Invalid number of arguments given */
      rb_raise(rb_eArgError, "wrong number of arguments (%d for 0..3)", argc);
      break;
  };

  if ((default_endianness == symbol_BIG_ENDIAN) || (default_endianness == symbol_LITTLE_ENDIAN)) {
    rb_ivar_set(self, id_ivar_default_endianness, default_endianness);
    if (RTEST(buffer)) {
      Check_Type(buffer, T_STRING);
      rb_funcall(buffer, id_method_force_encoding, 1, ASCII_8BIT_STRING);
      rb_ivar_set(self, id_ivar_buffer, buffer);
    } else {
      rb_ivar_set(self, id_ivar_buffer, Qnil);
    }
    rb_ivar_set(self, id_ivar_item_class, item_class);
    rb_ivar_set(self, id_ivar_items, rb_hash_new());
    rb_ivar_set(self, id_ivar_sorted_items, rb_ary_new());
    rb_ivar_set(self, id_ivar_defined_length, INT2FIX(0));
    rb_ivar_set(self, id_ivar_defined_length_bits, INT2FIX(0));
    rb_ivar_set(self, id_ivar_pos_bit_size, INT2FIX(0));
    rb_ivar_set(self, id_ivar_neg_bit_size, INT2FIX(0));
    rb_ivar_set(self, id_ivar_fixed_size, Qtrue);
    rb_ivar_set(self, id_ivar_short_buffer_allowed, Qfalse);
    rb_ivar_set(self, id_ivar_mutex, Qnil);
  } else {
    rb_raise(rb_eArgError, "Unrecognized endianness: %s - Must be :BIG_ENDIAN or :LITTLE_ENDIAN", RSTRING_PTR(rb_funcall(default_endianness, id_method_to_s, 0)));
  }

  return self;
}

Instance Attribute Details

#default_endianness ⇒ Symbol (readonly)

Returns Default endianness for items in the structure. One of BinaryAccessor::ENDIANNESS.

Returns:



24
25
26
 
# File 'lib/cosmos/packets/structure.rb', line 24

def default_endianness
  @default_endianness
end

#defined_length ⇒ Integer (readonly)

Returns Defined length in bytes (not bits) of the structure.

Returns:

  • (Integer) —

    Defined length in bytes (not bits) of the structure



34
35
36
 
# File 'lib/cosmos/packets/structure.rb', line 34

def defined_length
  @defined_length
end

#defined_length_bits ⇒ Integer (readonly)

Returns Defined length in bits of the structure.

Returns:

  • (Integer) —

    Defined length in bits of the structure



37
38
39
 
# File 'lib/cosmos/packets/structure.rb', line 37

def defined_length_bits
  @defined_length_bits
end

#fixed_size ⇒ Boolean (readonly)

Returns Flag indicating if the structure contains any variably sized items or not.

Returns:

  • (Boolean) —

    Flag indicating if the structure contains any variably sized items or not.



41
42
43
 
# File 'lib/cosmos/packets/structure.rb', line 41

def fixed_size
  @fixed_size
end

#items ⇒ Hash (readonly)

Returns Items that make up the structure. Hash key is the item’s name in uppercase.

Returns:

  • (Hash) —

    Items that make up the structure. Hash key is the item's name in uppercase



28
29
30
 
# File 'lib/cosmos/packets/structure.rb', line 28

def items
  @items
end

#short_buffer_allowed ⇒ Boolean

Returns Flag indicating if giving a buffer with less than required data size is allowed.

Returns:

  • (Boolean) —

    Flag indicating if giving a buffer with less than required data size is allowed.



45
46
47
 
# File 'lib/cosmos/packets/structure.rb', line 45

def short_buffer_allowed
  @short_buffer_allowed
end

#sorted_items ⇒ Array (readonly)

Returns Items sorted by bit_offset.

Returns:

  • (Array) —

    Items sorted by bit_offset.



31
32
33
 
# File 'lib/cosmos/packets/structure.rb', line 31

def sorted_items
  @sorted_items
end

Instance Method Details

#append_item(name, bit_size, data_type, array_size = nil, endianness = @default_endianness, overflow = :ERROR) ⇒ StrutureItem

Define an item at the end of the structure. This creates a new instance of the item_class as given in the constructor and adds it to the items hash. It also resizes the buffer to accomodate the new item.

Parameters:

  • name (String) —

    Name of the item. Used by the items hash to retrieve the item.

  • bit_size (Integer) —

    Bit size of the item in the raw buffer

  • data_type (Symbol) —

    Type of data contained by the item. This is dependant on the item_class but by default see StructureItem.

  • array_size (Integer) (defaults to: nil) —

    Set to a non nil value if the item is to represented as an array.

  • endianness (Symbol) (defaults to: @default_endianness) —

    Endianness of this item. By default the endianness as set in the constructure is used.

  • overflow (Symbol) (defaults to: :ERROR) —

    How to handle value overflows. This is dependant on the item_class but by default see StructureItem.

Returns:

  • (StrutureItem) —

    The struture item defined

Raises:

  • (ArgumentError) 


176
177
178
179
 
# File 'lib/cosmos/packets/structure.rb', line 176

def append_item(name, bit_size, data_type, array_size = nil, endianness = @default_endianness, overflow = :ERROR)
  raise ArgumentError, "Can't append an item after a variably sized item" if !@fixed_size
  return define_item(name, @defined_length_bits, bit_size, data_type, array_size, endianness, overflow)
end

#buffer(copy = true) ⇒ String

Get the buffer used by the structure. The current buffer is copied and thus modifications to the returned buffer will have no effect on the structure items.

Parameters:

Returns:

  • (String) —

    Data buffer backing the structure



309
310
311
312
313
314
315
316
317
318
319
 
# File 'lib/cosmos/packets/structure.rb', line 309

def buffer(copy = true)
  if @buffer
    if copy
      return @buffer.dup
    else
      return @buffer
    end
  else
    return nil
  end
end

#buffer=(buffer) ⇒ Object

Set the buffer to be used by the structure. The buffer is copied and thus further modifications to the buffer have no effect on the structure items.

Parameters:

  • buffer (String) —

    Buffer of data to back the stucture items



326
327
328
329
330
 
# File 'lib/cosmos/packets/structure.rb', line 326

def buffer=(buffer)
  synchronize() do
    internal_buffer_equals(buffer)
  end
end

#clone ⇒ Structure Also known as: dup

Make a light weight clone of this structure. This only creates a new buffer of data. The defined structure items are the same.

Returns:

  • (Structure) —

    A copy of the current structure with a new underlying buffer of data



373
374
375
376
377
 
# File 'lib/cosmos/packets/structure.rb', line 373

def clone
  structure = super()
  @buffer = @buffer.clone if @buffer # Deep Copy @buffer
  return structure
end

#define_item(name, bit_offset, bit_size, data_type, array_size = nil, endianness = @default_endianness, overflow = :ERROR) ⇒ StrutureItem

Define an item in the structure. This creates a new instance of the item_class as given in the constructor and adds it to the items hash. It also resizes the buffer to accomodate the new item.

Parameters:

  • name (String) —

    Name of the item. Used by the items hash to retrieve the item.

  • bit_offset (Integer) —

    Bit offset of the item in the raw buffer

  • bit_size (Integer) —

    Bit size of the item in the raw buffer

  • data_type (Symbol) —

    Type of data contained by the item. This is dependant on the item_class but by default see StructureItem.

  • array_size (Integer) (defaults to: nil) —

    Set to a non nil value if the item is to represented as an array.

  • endianness (Symbol) (defaults to: @default_endianness) —

    Endianness of this item. By default the endianness as set in the constructure is used.

  • overflow (Symbol) (defaults to: :ERROR) —

    How to handle value overflows. This is dependant on the item_class but by default see StructureItem.

Returns:

  • (StrutureItem) —

    The struture item defined



86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
 
# File 'lib/cosmos/packets/structure.rb', line 86

def define_item(name, bit_offset, bit_size, data_type, array_size = nil, endianness = @default_endianness, overflow = :ERROR)
  # Handle case-insensitive naming
  name_upcase = name.upcase

  # Create the item
  item = @item_class.new(name_upcase, bit_offset, bit_size, data_type, endianness, array_size, overflow)

  # Handle Overwriting Existing Item
  if @items[name_upcase]
    item_index = nil
    @sorted_items.each_with_index do |sorted_item, index|
      if sorted_item.name == name_upcase
        item_index = index
        break
      end
    end
    @sorted_items.delete_at(item_index) if item_index < @sorted_items.length
  end

  # Add to Sorted Items
  unless @sorted_items.empty?
    last_item = @sorted_items[-1]
    @sorted_items << item
    # If the current item or last item have a negative offset then we have
    # to re-sort. We also re-sort if the current item is less than the less
    # item because we are inserting.
    if last_item.bit_offset <= 0 or item.bit_offset <= 0 or item.bit_offset < last_item.bit_offset
      @sorted_items = @sorted_items.sort {|item1, item2| item1 <=> item2}
    end
  else
    @sorted_items << item
  end

  # Add to the overall hash of defined items
  @items[name_upcase] = item
  # Update fixed size knowledge
  @fixed_size = false if ((data_type != :DERIVED and bit_size <= 0) or (array_size and array_size <= 0))

  # Recalculate the overall defined length of the structure
  update_needed = false
  if item.bit_offset >= 0
    if item.bit_size > 0
      if item.array_size
        if item.array_size >= 0
          item_defined_length_bits = item.bit_offset + item.array_size
        else
          item_defined_length_bits = item.bit_offset
        end
      else
        item_defined_length_bits = item.bit_offset + item.bit_size
      end
      if item_defined_length_bits > @pos_bit_size
        @pos_bit_size = item_defined_length_bits
        update_needed = true
      end
    else
      if item.bit_offset > @pos_bit_size
        @pos_bit_size = item.bit_offset
        update_needed = true
      end
    end
  else
    if item.bit_offset.abs > @neg_bit_size
      @neg_bit_size = item.bit_offset.abs
      update_needed = true
    end
  end
  if update_needed
    @defined_length_bits = @pos_bit_size + @neg_bit_size
    @defined_length = @defined_length_bits / 8
    @defined_length += 1 if @defined_length_bits % 8 != 0
  end

  # Resize the buffer if necessary
  resize_buffer() if @buffer

  return item
end

#defined? ⇒ TrueClass or FalseClass

Indicates if any items have been defined for this structure

Returns:



65
66
67
 
# File 'lib/cosmos/packets/structure.rb', line 65

def defined?
  @sorted_items.length > 0
end

#enable_method_missing ⇒ Object 



380
381
382
 
# File 'lib/cosmos/packets/structure.rb', line 380

def enable_method_missing
  extend(MethodMissing)
end

#formatted(value_type = :RAW, indent = 0, buffer = @buffer) ⇒ String

Create a string that shows the name and value of each item in the structure

Parameters:

  • value_type (Symbol) (defaults to: :RAW) —

    Not used. Subclasses should overload this parameter to check whether to perform conversions on the item.

  • indent (Integer) (defaults to: 0) —

    Amount to indent before printing the item name

  • buffer (String) (defaults to: @buffer) —

    The binary buffer to write the value to

Returns:

  • (String) —

    String formatted with all the item names and values



277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
 
# File 'lib/cosmos/packets/structure.rb', line 277

def formatted(value_type = :RAW, indent = 0, buffer = @buffer)
  indent_string = ' ' * indent
  string = ''
  synchronize_allow_reads(true) do
    @sorted_items.each do |item|
      if item.data_type != :BLOCK
        string << "#{indent_string}#{item.name}: #{read_item(item, value_type, buffer)}\n"
      else
        value = read_item(item, value_type, buffer)
        if String === value
          string << "#{indent_string}#{item.name}:\n"
          string << value.formatted(1, 16, ' ', indent + 2)
        else
          string << "#{indent_string}#{item.name}: #{value}\n"
        end
      end
    end
  end
  return string
end

#get_item(name) ⇒ StructureItem

Returns StructureItem or one of its subclasses.

Parameters:

  • name (String) —

    Name of the item to look up in the items Hash

Returns:

Raises:

  • (ArgumentError) 


183
184
185
186
187
 
# File 'lib/cosmos/packets/structure.rb', line 183

def get_item(name)
  item = @items[name.upcase]
  raise ArgumentError, "Unknown item: #{name}" unless item
  return item
end

#length ⇒ Object

Returns the actual structure length.

structure.length #=> 324



622
623
624
 
# File 'ext/cosmos/ext/structure/structure.c', line 622

static VALUE structure_length(VALUE self) {
  return INT2FIX(get_int_length(self));
}

#read(name, value_type = :RAW, buffer = @buffer) ⇒ Object

Read an item in the structure by name

Parameters:

  • name (String) —

    Name of an item to read

  • value_type (Symbol) (defaults to: :RAW) —

    Not used. Subclasses should overload this parameter to check whether to perform conversions on the item.

  • buffer (String) (defaults to: @buffer) —

    The binary buffer to read the item from

Returns:

  • Value based on the item definition. This could be an integer, float, or array of values.



237
238
239
 
# File 'lib/cosmos/packets/structure.rb', line 237

def read(name, value_type = :RAW, buffer = @buffer)
  return read_item(get_item(name), value_type, buffer)
end

#read_all(value_type = :RAW, buffer = @buffer, top = true) ⇒ Array<Array>

Read all items in the structure into an array of arrays

[[item name, item value], ...]

Parameters:

  • value_type (Symbol) (defaults to: :RAW) —

    Not used. Subclasses should overload this parameter to check whether to perform conversions on the item.

  • buffer (String) (defaults to: @buffer) —

    The binary buffer to write the value to

  • top (Boolean) (defaults to: true) —

    Indicates if this is a top level call for the mutex

Returns:

  • (Array<Array>) —

    Array of two element arrays containing the item name as element 0 and item value as element 1.



262
263
264
265
266
267
268
 
# File 'lib/cosmos/packets/structure.rb', line 262

def read_all(value_type = :RAW, buffer = @buffer, top = true)
  item_array = []
  synchronize_allow_reads(top) do
    @sorted_items.each {|item| item_array << [item.name, read_item(item, value_type, buffer)]}
  end
  return item_array
end

#read_item(*args) ⇒ Object

Read an item in the structure

Parameters:

  • item (StructureItem) —

    Instance of StructureItem or one of its subclasses

  • value_type (Symbol) —

    Not used. Subclasses should overload this parameter to check whether to perform conversions on the item.

  • buffer (String) —

    The binary buffer to read the item from

Returns:

  • Value based on the item definition. This could be a string, integer, float, or array of values.



663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
 
# File 'ext/cosmos/ext/structure/structure.c', line 663

static VALUE read_item(int argc, VALUE* argv, VALUE self)
{
  VALUE item = Qnil;
  VALUE buffer = Qnil;

  switch (argc)
  {
    case 1:
    case 2:
      item = argv[0];
      buffer = rb_ivar_get(self, id_ivar_buffer);
      break;
    case 3:
      item = argv[0];
      buffer = argv[2];
      break;
    default:
      /* Invalid number of arguments given */
      rb_raise(rb_eArgError, "wrong number of arguments (%d for 1..3)", argc);
      break;
  };

  return read_item_internal(self, item, buffer);
}

#resize_buffer ⇒ Object

Resize the buffer at least the defined length of the structure



808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
 
# File 'ext/cosmos/ext/structure/structure.c', line 808

static VALUE resize_buffer(VALUE self)
{
  VALUE buffer = rb_ivar_get(self, id_ivar_buffer);
  if (RTEST(buffer)) {
    VALUE value_defined_length = rb_ivar_get(self, id_ivar_defined_length);
    long defined_length = FIX2INT(value_defined_length);
    long current_length = RSTRING_LEN(buffer);

    /* Extend data size */
    if (current_length < defined_length)
    {
      rb_str_concat(buffer, rb_str_times(ZERO_STRING, INT2FIX(defined_length - current_length)));
    }
  }

  return self;
}

#set_item(item) ⇒ Object

Parameters:

  • item (#name) —

    Instance of StructureItem or one of its subclasses. The name method will be used to look up the item and set it to the new instance.



191
192
193
194
195
196
197
 
# File 'lib/cosmos/packets/structure.rb', line 191

def set_item(item)
  if @items[item.name]
    @items[item.name] = item
  else
    raise ArgumentError, "Unknown item: #{item.name} - Ensure item name is uppercase"
  end
end

#synchronize ⇒ Object

Take the structure mutex to ensure the buffer does not change while you perform activities



333
334
335
336
 
# File 'lib/cosmos/packets/structure.rb', line 333

def synchronize
  @mutex ||= Mutex.new
  @mutex.synchronize {|| yield}
end

#synchronize_allow_reads(top = false) ⇒ Object

Take the structure mutex to ensure the buffer does not change while you perform activities This versions allows reads to happen if a top level function has already taken the mutex

Parameters:

  • top (Boolean) (defaults to: false) —

    If true this will take the mutex and set an allow reads flag to allow lower level calls to go forward without getting the mutex



342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
 
# File 'lib/cosmos/packets/structure.rb', line 342

def synchronize_allow_reads(top = false)
  @mutex_allow_reads ||= false
  @mutex ||= Mutex.new
  if top
    @mutex.synchronize do
      @mutex_allow_reads = Thread.current
      begin
        yield
      ensure
        @mutex_allow_reads = false
      end
    end
  else
    got_mutex = @mutex.try_lock
    if got_mutex
      begin
        yield
      ensure
        @mutex.unlock
      end
    elsif @mutex_allow_reads == Thread.current
      yield
    end
  end
end

#write(name, value, value_type = :RAW, buffer = @buffer) ⇒ Object

Write an item in the structure by name

Parameters:

  • name (Object) —

    Name of the item to write

  • value (Object) —

    Value based on the item definition. This could be a string, integer, float, or array of values.

  • value_type (Symbol) (defaults to: :RAW) —

    Not used. Subclasses should overload this parameter to check whether to perform conversions on the item.

  • buffer (String) (defaults to: @buffer) —

    The binary buffer to write the value to



249
250
251
 
# File 'lib/cosmos/packets/structure.rb', line 249

def write(name, value, value_type = :RAW, buffer = @buffer)
  write_item(get_item(name), value, value_type, buffer)
end

#write_item(item, value, value_type = :RAW, buffer = @buffer) ⇒ Object

Write a value to the buffer based on the item definition

Parameters:

  • item (StructureItem) —

    Instance of StructureItem or one of its subclasses

  • value (Object) —

    Value based on the item definition. This could be a string, integer, float, or array of values.

  • value_type (Symbol) (defaults to: :RAW) —

    Not used. Subclasses should overload this parameter to check whether to perform conversions on the item.

  • buffer (String) (defaults to: @buffer) —

    The binary buffer to write the value to



217
218
219
220
221
222
223
224
225
226
227
 
# File 'lib/cosmos/packets/structure.rb', line 217

def write_item(item, value, value_type = :RAW, buffer = @buffer)
  if buffer
    if item.array_size
      BinaryAccessor.write_array(value, item.bit_offset, item.bit_size, item.data_type, item.array_size, buffer, item.endianness, item.overflow)
    else
      BinaryAccessor.write(value, item.bit_offset, item.bit_size, item.data_type, buffer, item.endianness, item.overflow)
    end
  else
    raise "No buffer given to write_item"
  end
end