Class Hierarchy

libtrace is a C API, i.e.a library of functions that allow you to create Traces and Packets, to read Packets, and to extract 'decodes' for various parts of the Packets, e.g. IP (i.e. IPv4), TDP and UDP headers, etc. That means that in C, you need to keep pointers to each part of the Packet you're interested in.

ruby-libtrace provides Ruby access to libtrace objects via a set of Ruby classes. Each class has methods that provide access to various libtrace functions, and to fields in libtrace's 'decodes.' Within ruby-libtrace the classes are arranged in an inheritance hierarchy, as shown in the diagram below.

	Trace

	Packet

	Data

	Layer2

Layer3			Internet

	IP	IP6

Transport			TCP	UDP	ICMP

The important thing about this is that classes at lower levels in the Hierarchy can use all the methods in any of their predecessor classes, i.e. any that can be reached by tracing up the black lines in the diagram.

For example:

Packet provides .wire_len (on-the-wire packet length in bytes)
Internet provides .src_prefix (IPv4 or IPv6 source address)
TCP provides .src_port (TCP source port)

Therefore, classes IP, IPv6, TCP, UDP amd ICMP can all use .wire_len and .src_prefix.

If you are writing methods that work on a TCP object, you should use the higher-level methods within your own methods. Doing that means that you don't have to make, for example, an IP6 object within your method - which Ruby will later have to garbage-collect.

Nevil Brownlee
Thu, 20 Nov 08 (CST)