Class: OpenC3::Structure

Inherits:
Object show all
Defined in:
lib/openc3/packets/structure.rb,
ext/openc3/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

Constant Summary collapse

ASCII_8BIT_STRING =

Used to force encoding

"ASCII-8BIT".freeze
ZERO_STRING =

String providing a single 0 byte

"\000".freeze

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.



70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
 
# File 'lib/openc3/packets/structure.rb', line 70

def initialize(default_endianness = BinaryAccessor::HOST_ENDIANNESS, buffer = nil, item_class = StructureItem)
  if (default_endianness == :BIG_ENDIAN) || (default_endianness == :LITTLE_ENDIAN)
    @default_endianness = default_endianness
    if buffer
      raise TypeError, "wrong argument type #{buffer.class} (expected String)" unless String === buffer

      @buffer = buffer.force_encoding(ASCII_8BIT_STRING)
    else
      @buffer = nil
    end
    @item_class = item_class
    @items = {}
    @sorted_items = []
    @defined_length = 0
    @defined_length_bits = 0
    @pos_bit_size = 0
    @neg_bit_size = 0
    @fixed_size = true
    @short_buffer_allowed = false
    @mutex = nil
    @accessor = BinaryAccessor.new(self)
  else
    raise(ArgumentError, "Unknown endianness '#{default_endianness}', must be :BIG_ENDIAN or :LITTLE_ENDIAN")
  end
end

Instance Attribute Details

#accessor ⇒ Accessor

Returns Instance of class used to access raw data of structure from buffer.

Returns:

  • (Accessor) —

    Instance of class used to access raw data of structure from buffer



53
54
55
 
# File 'lib/openc3/packets/structure.rb', line 53

def accessor
  @accessor
end

#default_endianness ⇒ Symbol (readonly)

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

Returns:



29
30
31
 
# File 'lib/openc3/packets/structure.rb', line 29

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



39
40
41
 
# File 'lib/openc3/packets/structure.rb', line 39

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



42
43
44
 
# File 'lib/openc3/packets/structure.rb', line 42

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.



46
47
48
 
# File 'lib/openc3/packets/structure.rb', line 46

def fixed_size
  @fixed_size
end

#items ⇒ Hash

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



33
34
35
 
# File 'lib/openc3/packets/structure.rb', line 33

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.



50
51
52
 
# File 'lib/openc3/packets/structure.rb', line 50

def short_buffer_allowed
  @short_buffer_allowed
end

#sorted_items ⇒ Array

Returns Items sorted by bit_offset.

Returns:

  • (Array) —

    Items sorted by bit_offset.



36
37
38
 
# File 'lib/openc3/packets/structure.rb', line 36

def sorted_items
  @sorted_items
end

Instance Method Details

#allocate_buffer_if_needed ⇒ Object

Allocate a buffer if not available



156
157
158
159
160
161
162
 
# File 'lib/openc3/packets/structure.rb', line 156

def allocate_buffer_if_needed
  unless @buffer
    @buffer = ZERO_STRING * @defined_length
    @buffer.force_encoding(ASCII_8BIT_STRING)
  end
  return @buffer
end

#append(item) ⇒ StrutureItem

Adds an item at the end of the structure. It adds the item to the items hash and resizes the buffer to accommodate the new item.

Parameters:

Returns:

  • (StrutureItem) —

    The structure item defined



311
312
313
314
315
316
317
318
319
320
321
322
323
 
# File 'lib/openc3/packets/structure.rb', line 311

def append(item)
  if item.data_type == :DERIVED
    item.bit_offset = 0
  else
    # We're appending a new item so set the bit_offset
    item.bit_offset = @defined_length_bits
    # Also set original_bit_offset because it's currently 0
    # due to PacketItemParser::create_packet_item
    # get_bit_offset() returning 0 if append
    item.original_bit_offset = @defined_length_bits
  end
  return define(item)
end

#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 accommodate 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 dependent 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 constructor is used.

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

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

Returns:

  • (StrutureItem) —

    The structure item defined



298
299
300
301
302
303
304
 
# File 'lib/openc3/packets/structure.rb', line 298

def append_item(name, bit_size, data_type, array_size = nil, endianness = @default_endianness, overflow = :ERROR)
  if data_type == :DERIVED
    return define_item(name, 0, bit_size, data_type, array_size, endianness, overflow)
  else
    return define_item(name, @defined_length_bits, bit_size, data_type, array_size, endianness, overflow)
  end
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



484
485
486
487
488
489
490
491
 
# File 'lib/openc3/packets/structure.rb', line 484

def buffer(copy = true)
  local_buffer = allocate_buffer_if_needed()
  if copy
    return local_buffer.dup
  else
    return local_buffer
  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 structure items



498
499
500
501
502
 
# File 'lib/openc3/packets/structure.rb', line 498

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



509
510
511
512
513
514
515
516
517
518
 
# File 'lib/openc3/packets/structure.rb', line 509

def clone
  structure = super()
  # Use instance_variable_set since we have overridden buffer= to do
  # additional work that isn't necessary here
  structure.instance_variable_set("@buffer".freeze, @buffer.clone) if @buffer
  # Need to update reference packet in the Accessor
  structure.accessor = @accessor.clone
  structure.accessor.packet = structure
  return structure
end

#deep_copy ⇒ Structure

Clone that also deep copies items

Returns:

  • (Structure) —

    A deep copy of the structure



523
524
525
526
527
528
529
530
531
532
533
534
535
 
# File 'lib/openc3/packets/structure.rb', line 523

def deep_copy
  cloned = clone()
  cloned_items = []
  cloned.sorted_items.each do |item|
    cloned_items << item.clone()
  end
  cloned.sorted_items = cloned_items
  cloned.items = {}
  cloned_items.each do |item|
    cloned.items[item.name] = item
  end
  return cloned
end

#define(item) ⇒ StrutureItem

Adds the given item to the items hash. It also resizes the buffer to accommodate the new item.

Parameters:

Returns:

  • (StrutureItem) —

    The structure item defined



212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
 
# File 'lib/openc3/packets/structure.rb', line 212

def define(item)
  # Handle Overwriting Existing Item
  if @items[item.name]
    item_index = nil
    @sorted_items.each_with_index do |sorted_item, index|
      if sorted_item.name == item.name
        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 last
    # 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
    end
  else
    @sorted_items << item
  end

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

  # Recalculate the overall defined length of the structure
  update_needed = false
  if not item.parent_item
    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
  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

#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 accommodate 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 dependent 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 constructor is used.

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

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

Returns:

  • (StrutureItem) —

    The structure item defined



201
202
203
204
205
 
# File 'lib/openc3/packets/structure.rb', line 201

def define_item(name, bit_offset, bit_size, data_type, array_size = nil, endianness = @default_endianness, overflow = :ERROR)
  # Create the item
  item = @item_class.new(name, bit_offset, bit_size, data_type, endianness, array_size, overflow)
  define(item)
end

#defined? ⇒ TrueClass or FalseClass

Indicates if any items have been defined for this structure

Returns:



166
167
168
 
# File 'lib/openc3/packets/structure.rb', line 166

def defined?
  @sorted_items.length > 0
end

#delete_item(name) ⇒ Object

Parameters:

  • name (String) —

    Name of the item to delete in the items Hash

Raises:

  • (ArgumentError) 


359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
 
# File 'lib/openc3/packets/structure.rb', line 359

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

  # Find the item to delete in the sorted_items array
  item_index = nil
  @sorted_items.each_with_index do |sorted_item, index|
    if sorted_item.name == item.name
      item_index = index
      break
    end
  end
  @sorted_items.delete_at(item_index)
  @items.delete(name.upcase)
end

#enable_method_missing ⇒ Object

Enable the ability to read and write item values as if they were methods to the class



539
540
541
 
# File 'lib/openc3/packets/structure.rb', line 539

def enable_method_missing
  extend(MethodMissing)
end

#formatted(value_type = :RAW, indent = 0, buffer = @buffer, ignored = nil) ⇒ 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

  • ignored (Array<String>) (defaults to: nil) —

    List of items to ignore when building the string

Returns:

  • (String) —

    String formatted with all the item names and values



453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
 
# File 'lib/openc3/packets/structure.rb', line 453

def formatted(value_type = :RAW, indent = 0, buffer = @buffer, ignored = nil)
  indent_string = ' ' * indent
  string = ''
  synchronize_allow_reads(true) do
    @sorted_items.each do |item|
      next if item.hidden || (ignored && ignored.include?(item.name))

      if (item.data_type != :BLOCK) ||
         (item.data_type == :BLOCK and value_type != :RAW and
          item.respond_to? :read_conversion and item.read_conversion)
        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) 


327
328
329
330
331
332
 
# File 'lib/openc3/packets/structure.rb', line 327

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



112
113
114
115
 
# File 'lib/openc3/packets/structure.rb', line 112

def length
  allocate_buffer_if_needed()
  return @buffer.length
end

#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.



408
409
410
 
# File 'lib/openc3/packets/structure.rb', line 408

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.



433
434
435
436
437
438
439
440
441
442
443
 
# File 'lib/openc3/packets/structure.rb', line 433

def read_all(value_type = :RAW, buffer = @buffer, top = true)
  item_array = []
  synchronize_allow_reads(top) do
    @sorted_items.each do |item|
      unless item.hidden
        item_array << [item.name, read_item(item, value_type, buffer)]
      end
    end
  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.



104
105
106
107
 
# File 'lib/openc3/packets/structure.rb', line 104

def read_item(item, _value_type = :RAW, buffer = @buffer)
  buffer = allocate_buffer_if_needed() unless buffer
  return @accessor.read_item(item, buffer)
end

#read_items(items, _value_type = :RAW, buffer = @buffer) ⇒ Object

Read a list of items in the structure

Parameters:

  • items (StructureItem) —

    Array 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) (defaults to: @buffer) —

    The binary buffer to read the item from

Returns:

  • Hash of read names and values



150
151
152
153
 
# File 'lib/openc3/packets/structure.rb', line 150

def read_items(items, _value_type = :RAW, buffer = @buffer)
  buffer = allocate_buffer_if_needed() unless buffer
  return @accessor.read_items(items, buffer)
end

#rename_item(item_name, new_item_name) ⇒ Object

Rename an existing item

Parameters:

  • item_name (String) —

    Name of the currently defined item

  • new_item_name (String) —

    New name for the item



174
175
176
177
178
179
180
181
182
 
# File 'lib/openc3/packets/structure.rb', line 174

def rename_item(item_name, new_item_name)
  item = get_item(item_name)
  item.name = new_item_name
  @items.delete(item_name)
  @items[new_item_name] = item
  # Since @sorted_items contains the actual item reference it is
  # updated when we set the item.name
  item
end

#resize_buffer ⇒ Object

Resize the buffer at least the defined length of the structure



118
119
120
121
122
123
124
125
126
127
128
129
 
# File 'lib/openc3/packets/structure.rb', line 118

def resize_buffer
  if @buffer
    # Extend data size
    if @buffer.length < @defined_length
      @buffer << (ZERO_STRING * (@defined_length - @buffer.length))
    end
  else
    allocate_buffer_if_needed()
  end

  return self
end

#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.



336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
 
# File 'lib/openc3/packets/structure.rb', line 336

def set_item(item)
  if @items[item.name]
    @items[item.name] = item
    # Need to allocate space for the variable length item if its minimum size is greater than zero
    if item.variable_bit_size
      minimum_data_bits = 0
      if (item.data_type == :INT or item.data_type == :UINT) and not item.original_array_size
        # Minimum QUIC encoded integer, see https://datatracker.ietf.org/doc/html/rfc9000#name-variable-length-integer-enc
        minimum_data_bits = 6
      # :STRING, :BLOCK, or array item
      elsif item.variable_bit_size['length_value_bit_offset'] > 0
        minimum_data_bits = item.variable_bit_size['length_value_bit_offset'] * item.variable_bit_size['length_bits_per_count']
      end
      if minimum_data_bits > 0 and item.bit_offset >= 0 and @defined_length_bits == item.bit_offset and not item.parent_item
        @defined_length_bits += minimum_data_bits
      end
    end
  else
    raise ArgumentError, "Unknown item: #{item.name} - Ensure item name is uppercase"
  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



420
421
422
 
# File 'lib/openc3/packets/structure.rb', line 420

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) —

    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



383
384
385
386
 
# File 'lib/openc3/packets/structure.rb', line 383

def write_item(item, value, _value_type = :RAW, buffer = @buffer)
  buffer = allocate_buffer_if_needed() unless buffer
  return @accessor.write_item(item, value, buffer)
end

#write_items(items, values, _value_type = :RAW, buffer = @buffer) ⇒ Object

Write values to the buffer based on the item definitions

Parameters:

  • items (StructureItem) —

    Array of StructureItem or one of its subclasses

  • value (Object) —

    Array of values based on the item definitions.

  • value_type (Symbol) —

    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 values to



395
396
397
398
 
# File 'lib/openc3/packets/structure.rb', line 395

def write_items(items, values, _value_type = :RAW, buffer = @buffer)
  buffer = allocate_buffer_if_needed() unless buffer
  return @accessor.write_items(items, values, buffer)
end