packetgen 3.3.3 → 4.1.0

data/lib/packetgen/header/udp.rb

@@ -17,28 +17,30 @@ module PacketGen
     #   |             Length            |           Checksum            |
     #   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
     # A UDP header consists of:
-    # * a source port field ({#sport}, {Types::Int16} type),
-    # * a destination port field ({#dport}, +Int16+ type),
-    # * a UDP length field ({#length}, +Int16+ type),
-    # * a {#checksum} field (+Int16+ type),
+    # * a source port field ({#sport}, +BinStruct::Int16+ type),
+    # * a destination port field ({#dport}, +BinStruct:Int16+ type),
+    # * a UDP length field ({#length}, +BinStruct:Int16+ type),
+    # * a {#checksum} field (+BinStruct:Int16+ type),
     # * and a {#body}.
     #
-    # == Create a UDP header
+    # @example Create a UDP header
     #  # standalone
     #  udp = PacketGen::Header::UDP.new
     #  # in a packet
-    #  pkt = PAcketGen.gen('IP').eadd('UDP')
+    #  pkt = PacketGen.gen('IP').add('UDP')
     #  # access to IP header
-    #  pkt.udp    # => PacketGen::Header::UDP
+    #  pkt.udp.class    # => PacketGen::Header::UDP
     #
-    # == UDP attributes
+    # @example UDP attributes
+    #  udp = PacketGen::Header::UDP.new
     #  udp.sport = 65432
     #  udp.dport = 53
     #  udp.length = 43
     #  udp.checksum = 0xffff
-    #  udp.body.read 'this is a UDP body'
+    #  udp.body = 'this is a UDP body'
     #
     # @author Sylvain Daubert
+    # @author LemonTree55
     class UDP < Base
       # IP protocol number for UDP
       IP_PROTOCOL = 17
@@ -46,22 +48,23 @@ module PacketGen
       # @!attribute sport
       #  16-bit UDP source port
       #  @return [Integer]
-      define_field :sport, Types::Int16
+      define_attr :sport, BinStruct::Int16
       # @!attribute dport
       #  16-bit UDP destination port
       #  @return [Integer]
-      define_field :dport, Types::Int16
+      define_attr :dport, BinStruct::Int16
       # @!attribute length
       #  16-bit UDP length
       #  @return [Integer]
-      define_field :length, Types::Int16, default: 8
+      define_attr :length, BinStruct::Int16, default: 8
       # @!attribute checksum
       #  16-bit UDP checksum
       #  @return [Integer]
-      define_field :checksum, Types::Int16
+      define_attr :checksum, BinStruct::Int16
       # @!attribute body
-      #  @return [Types::String,Header::Base]
-      define_field :body, Types::String
+      #  UDP body
+      #  @return [BinStruct::String,Headerable]
+      define_attr :body, BinStruct::String
 
       alias source_port sport
       alias source_port= sport=
@@ -75,7 +78,7 @@ module PacketGen
         self.length += self[:body].sz if self[:body].sz.positive?
       end
 
-      # Compute checksum and set +checksum+ field
+      # Compute checksum and set {#checksum} field
       # @return [Integer]
       def calc_checksum
         ip = ip_header(self)
@@ -86,10 +89,10 @@ module PacketGen
         self.checksum = IP.reduce_checksum(sum)
       end
 
-      # Compute length and set +length+ field
+      # Compute length and set {#length} field
       # @return [Integer]
       def calc_length
-        Base.calculate_and_set_length self
+        Base.calculate_and_set_length(self)
       end
 
       # Invert source and destination port numbers
@@ -100,7 +103,6 @@ module PacketGen
         self
       end
     end
-
     self.add_class UDP
 
     IP.bind UDP, protocol: UDP::IP_PROTOCOL

data/lib/packetgen/header.rb

@@ -13,23 +13,28 @@ module PacketGen
   # This namespace handles all buitlin headers, such as {IP} or {TCP}.
   #
   # == Add a foreign header class
-  # PacketGen permits adding you own header classes.
-  # First, define the new header class. By example:
-  #  module MyModule
-  #    class MyHeader < PacketGen::Header::Base
-  #      define_field :field1, PacketGen::Types::Int32
-  #      define_field :field2, PacketGen::Types::Int32
-  #    end
+  # PacketGen permits adding your own header classes.
+  # First, define the new header class. Then, this class must be declared to PacketGen using {Header.add_class}.
+  # Finally, bindings must be declared.
+  #
+  # @example Foreign header class
+  #   # Define a new header
+  #   module MyModule
+  #     class MyHeader < PacketGen::Header::Base
+  #       define_attr :field1, BinStruct::Int32
+  #       define_attr :field2, BinStruct::Int32
+  #     end
   #   end
-  # Then, class must be declared to PacketGen:
-  #  PacketGen::Header.add_class MyModule::MyHeader
-  # Finally, bindings must be declared:
-  #  # bind MyHeader as IP protocol number 254 (needed by Packet#parse and Packet#add)
-  #  PacketGen::Header::IP.bind_header MyModule::MyHeader, protocol: 254
-  # And use it:
-  #  pkt = Packet.gen('IP').add('MyHeader', field1: 0x12345678)
-  #  pkt.myheader.field2.read 0x01
+  #
+  #   # Declare the new header to PacketGen
+  #   PacketGen::Header.add_class(MyModule::MyHeader)
+  #   # bind it as IP protocol number 254 (needed by Packet#parse and Packet#add)
+  #   PacketGen::Header::IP.bind(MyModule::MyHeader, protocol: 254)
+  #
+  #   # Use it
+  #   pkt = PacketGen.gen('IP').add('MyModule::MyHeader', field1: 0x12345678, field3: 0x87654321)
   # @author Sylvain Daubert
+  # @author LemonTree55
   module Header
     @added_header_classes = {}
 
@@ -54,7 +59,7 @@ module PacketGen
         @header_classes = nil
       end
 
-      # Remove a foreign header (previously added by {.add_header_class}
+      # Remove a foreign header previously added by {.add_class}
       # from known header classes.
       # @param [Class] klass
       # @return [void]
@@ -70,8 +75,8 @@ module PacketGen
       # @return [Class,nil]
       # @since 1.1.0
       def get_header_class_by_name(name)
-        if Header.const_defined? name
-          Header.const_get name
+        if Header.const_defined?(name)
+          Header.const_get(name)
         else
           @added_header_classes[name]
         end

data/lib/packetgen/headerable.rb

@@ -9,7 +9,13 @@
 module PacketGen
   # This mixin module defines minimal API for a class to act as a header
   # in {Packet}.
+  #
+  # Some others methods may optionally be defined by a {Headerable} object:
+  # * +#calc_length+ to calculate length from content. It should be defined if header as a length attribute.
+  # * +#calc_checksum+ to calculate checksum. It should be defined if header as a checksum attriibute.
+  # * +#reply+ to invert fields in header for a reply.
   # @author Sylvain Daubert
+  # @author LemonTree55
   # @since 3.0.2
   module Headerable
     # This modules handles class methods for {Headerable headerable classes}.
@@ -33,7 +39,7 @@ module PacketGen
     # @param [Class] klass
     # @return [void]
     def self.included(klass)
-      klass.extend ClassMethods
+      klass.extend(ClassMethods)
     end
 
     # Return header protocol name
@@ -51,7 +57,7 @@ module PacketGen
     end
 
     # @abstract Should be redefined by subclasses. This method should check invariant
-    #   fields from header.
+    #   attributes from header.
     # Called by {Packet#parse} when guessing first header to check if header is correct
     # @return [Boolean]
     def parse?
@@ -65,7 +71,7 @@ module PacketGen
     end
 
     # @api private
-    # Set packet to which this header belongs
+    # Set packet to which this header belongs to
     # @param [Packet] packet
     # @return [Packet] packet
     def packet=(packet)
@@ -74,8 +80,8 @@ module PacketGen
       @packet
     end
 
-    # @abstract This method is called when a header is added to a packet.
-    #   This base method does nothing but may be overriden by subclasses.
+    # @abstract This base method does nothing but may be overriden by subclasses.
+    # This method is called when a header is added to a packet.
     # @param [Packet] packet packet to which self is added
     # @return [void]
     def added_to_packet(packet) end
@@ -91,5 +97,15 @@ module PacketGen
 
       super
     end
+
+    # @abstract This method MUST be redefined by subclasses.
+    # Generate binary string from header
+    # @return [String]
+    # @raise [NotImplementedError]
+    def to_s
+      raise NotImplementedError, "#{self.class} should implement #to_s" if method(:to_s).super_method.nil?
+
+      super
+    end
   end
 end

data/lib/packetgen/inspect.rb

@@ -61,24 +61,19 @@ module PacketGen
       str << Inspect::FMT_ATTR % [type, attr, value]
     end
 
-    # Format an attribute for +#inspect+.
-    # 3 cases are handled:
-    # * attribute value is a {Types::Int}: show value as integer and in
-    #   hexdecimal format,
-    # * attribute value responds to +#to_human+: call it,
-    # * else, +#to_s+ is used to format attribute value.
+    # Format an attribute for +#inspect+. Call +#format_inspect} on +value+.
     # @param [Symbol] attr attribute name
     # @param [Object] value attribute value
     # @param [Integer] level
     # @return [String]
     def self.inspect_attribute(attr, value, level=1)
-      type = value.class.to_s.sub(/.*::/, '')
+      type = value.type_name
       self.format(type, attr, value.format_inspect, level)
     end
 
     # Format a ASN.1 attribute for +#inspect+.
     # 4 cases are handled:
-    # * attribute value is a =RANS1::Types::Enumerated+: show named value and
+    # * attribute value is a =RANS1::BinStruct::Enumerated+: show named value and
     #   its integer value as hexdecimal format,
     # * attribute value is a +RASN1::Types::Integer+: show value as integer and in
     #   hexdecimal format,