Class: PacketGen::Types::AbstractTLV

Inherits:
Fields
  • Object
show all
Includes:
Fieldable
Defined in:
lib/packetgen/types/abstract_tlv.rb

Overview

This class is an abstract class to define type-length-value data.

This class supersedes TLV class, which is not well defined on some corner cases.

Usage

To simply define a new TLV class, do:

MyTLV = PacketGen::Types::AbstractTLV.create
MyTLV.define_type_enum 'one' => 1, 'two' => 2

This will define a new MyTLV class, subclass of Fields. This class will define 3 fields:

  • #type, as a Int8Enum by default,

  • #length, as a Int8 by default,

  • and #value, as a String by default.

.define_type_enum is, here, necessary to define enum hash to be used for #type accessor, as this one is defined as an Enum.

This class may then be used as older TLV class:

tlv = MyTLV.new(type: 1, value: 'abcd')  # automagically set #length from value
tlv.type        #=> 1
tlv.human_type  #=> 'one'
tlv.length      #=> 4
tlv.value       #=> "abcd"

Advanced usage

Each field’s type may be changed at generating TLV class:

MyTLV = PacketGen::Types::AbstractTLV.create(type_class: PacketGen::Types::Int16,
                                             length_class: PacketGen::Types::Int16,
                                             value_class: PacketGen::Header::IP::Addr)
tlv = MyTLV.new(type: 1, value: '1.2.3.4')
tlv.type        #=> 1
tlv.length      #=> 4
tlv.value       #=> '1.2.3.4'
tlv.to_s        #=> "\x00\x01\x00\x04\x01\x02\x03\x04"

Some aliases may also be defined. For example, to create a TLV type whose type field should be named code:

MyTLV = PacketGen::Types::AbstractTLV.create(type_class: PacketGen::Types::Int16,
                                             length_class: PacketGen::Types::Int16,
                                             aliases: { code: :type })
tlv = MyTLV.new(code: 1, value: 'abcd')
tlv.code        #=> 1
tlv.type        #=> 1
tlv.length      #=> 4
tlv.value       #=> 'abcd'

Author:

  • Sylvain Daubert

Since:

Constant Summary collapse

FIELD_TYPES =

Since:

{ 'T' => :type, 'L' => :length, 'V' => :value }.freeze

Class Attribute Summary collapse

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Methods included from Fieldable

#format_inspect, #sz, #to_s, #type_name

Methods inherited from Fields

#[], #[]=, #bits_on, define_bit_fields_on, define_field, define_field_after, define_field_before, #fields, fields, inherited, #inspect, #offset_of, #optional?, #optional_fields, #present?, remove_bit_fields_on, remove_field, #sz, #to_h, #to_s, update_field

Constructor Details

#initialize(options = {}) ⇒ AbstractTLV

This method is abstract.

Should only be called on real TLV classes, created by create.

Returns a new instance of AbstractTLV.

Parameters:

  • options (Hash) (defaults to: {})

Options Hash (options):

  • :type (Integer)
  • :length (Integer)
  • :value (Object)

Since:



188
189
190
191
192
193
194
195
196
197
198
199
 
# File 'lib/packetgen/types/abstract_tlv.rb', line 188

def initialize(options={})
  @header_in_length = self.class.header_in_length
  @field_in_length = self.class.field_in_length
  self.class.aliases.each do |al, orig|
    options[orig] = options[al] if options.key?(al)
  end

  super
  # used #value= defined below, which set length if needed
  self.value = options[:value] if options[:value]
  calc_length unless options.key?(:length)
end

Class Attribute Details

.aliases ⇒ Hash

Returns:

  • (Hash)

Since:



69
70
71
 
# File 'lib/packetgen/types/abstract_tlv.rb', line 69

def aliases
  @aliases
end

.field_in_length ⇒ Object

Since:



73
74
75
 
# File 'lib/packetgen/types/abstract_tlv.rb', line 73

def field_in_length
  @field_in_length
end

.header_in_length ⇒ Object

Deprecated.

Since:



71
72
73
 
# File 'lib/packetgen/types/abstract_tlv.rb', line 71

def header_in_length
  @header_in_length
end

.length ⇒ Integer

This method is abstract.

Length attribute for real TLV class

Returns:

  • (Integer) 



# File 'lib/packetgen/types/abstract_tlv.rb', line 113

.type ⇒ Integer

This method is abstract.

Type attribute for real TLV class

Returns:

  • (Integer) 



# File 'lib/packetgen/types/abstract_tlv.rb', line 113

.value ⇒ Object

This method is abstract.

Value attribute for real TLV class

Returns:

  • (Object) 



# File 'lib/packetgen/types/abstract_tlv.rb', line 113

Instance Attribute Details

#length ⇒ Integer

This method is abstract.

Length

Returns:

  • (Integer) 



# File 'lib/packetgen/types/abstract_tlv.rb', line 173

#type ⇒ Integer

This method is abstract.

Type attribute

Returns:

  • (Integer) 



# File 'lib/packetgen/types/abstract_tlv.rb', line 173

#value ⇒ Object

This method is abstract.

Value attribute

Returns:

  • (Object) 



# File 'lib/packetgen/types/abstract_tlv.rb', line 173

Class Method Details

.create(type_class: Int8Enum, length_class: Int8, value_class: String, aliases: {}, header_in_length: false, field_order: 'TLV', field_in_length: 'V') ⇒ Class

Generate a TLV class

Parameters:

  • type_class (Class) (defaults to: Int8Enum) —

    Class to use for type

  • length_class (Class) (defaults to: Int8) —

    Class to use for length

  • value_class (Class) (defaults to: String) —

    Class to use for value

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

    if true , type and length fields are included in length. Deprecated, use field_in_length instead.

  • field_order (String) (defaults to: 'TLV') —

    give field order. Each character in [T,L,V] MUST be present once, in the desired order.

  • field_in_length (String) (defaults to: 'V') —

    give fields to compute length on.

Returns:

  • (Class)

Raises:

Since:

  • 3.1.4 Add header_in_length parameter

  • 3.3.1 Add field_order and +field_in_length’ parameters. Deprecate header_in_length parameter.



88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
 
# File 'lib/packetgen/types/abstract_tlv.rb', line 88

def create(type_class: Int8Enum, length_class: Int8, value_class: String,
           aliases: {}, header_in_length: false, field_order: 'TLV', field_in_length: 'V')
  Deprecation.deprecated_option(self, 'create', 'header_in_length', klass_method: true) if header_in_length
  raise Error, '.create cannot be called on a subclass of PacketGen::Types::AbstractTLV' unless self.equal?(AbstractTLV)

  klass = Class.new(self)
  klass.aliases = aliases
  klass.header_in_length = header_in_length
  klass.field_in_length = field_in_length

  check_field_in_length(field_in_length)
  check_field_order(field_order)
  generate_fields(klass, field_order, type_class, length_class, value_class)

  aliases.each do |al, orig|
    klass.instance_eval do
      alias_method al, orig if klass.method_defined?(orig)
      alias_method :"#{al}=", :"#{orig}=" if klass.method_defined?(:"#{orig}=")
    end
  end

  klass
end

.define_type_default(default) ⇒ void

This method is abstract.

Should only be called on real TLV classes, created by create.

This method returns an undefined value.

Set default value for #type field.

Parameters:

  • default (Integer, String, Symbol, nil) —

    default value from hsh for type

Since:

  • 3.4.0



137
138
139
 
# File 'lib/packetgen/types/abstract_tlv.rb', line 137

def define_type_default(default)
  field_defs[:type][:default] = default
end

.define_type_enum(hsh) ⇒ void

This method is abstract.

Should only be called on real TLV classes, created by create.

This method returns an undefined value.

Set enum hash for #type field.

Parameters:

  • hsh (Hash{String, Symbol => Integer}) —

    enum hash

Since:



127
128
129
130
 
# File 'lib/packetgen/types/abstract_tlv.rb', line 127

def define_type_enum(hsh)
  field_defs[:type][:enum].clear
  field_defs[:type][:enum].merge!(hsh)
end

Instance Method Details

#calc_length ⇒ void

This method returns an undefined value.

Calculate length

Since:

  • 3.4.0



253
254
255
256
257
258
259
260
261
262
 
# File 'lib/packetgen/types/abstract_tlv.rb', line 253

def calc_length
  fil = @field_in_length
  fil = 'TLV' if @header_in_length

  length = 0
  fil.each_char do |field_type|
    length += self[FIELD_TYPES[field_type]].sz
  end
  self.length = length
end

#human_type ⇒ String

This method is abstract.

Should only be called on real TLV class instances.

Get human-readable type

Returns:

Since:



239
240
241
 
# File 'lib/packetgen/types/abstract_tlv.rb', line 239

def human_type
  self[:type].to_human.to_s
end

#read(str) ⇒ Fields

This method is abstract.

Should only be called on real TLV class instances.

Populate object from a binary string

Parameters:

Returns:

Since:



205
206
207
208
209
210
211
212
213
214
215
216
217
 
# File 'lib/packetgen/types/abstract_tlv.rb', line 205

def read(str)
  return self if str.nil?

  idx = 0
  fields.each do |field_name|
    field = self[field_name]
    length = field_name == :value ? real_length : field.sz
    field.read(str[idx, length])
    idx += field.sz
  end

  self
end

#to_human ⇒ String

This method is abstract.

Should only be called on real TLV class instances.

Returns:

Since:



245
246
247
248
 
# File 'lib/packetgen/types/abstract_tlv.rb', line 245

def to_human
  my_value = self[:value].is_a?(String) ? self[:value].inspect : self[:value].to_human
  'type:%s,length:%u,value:%s' % [human_type, length, my_value]
end