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.

python-libtrace (plt) provides Python access to libtrace objects via a set of Python classes. Each class has methods that provide access to various libtrace functions, and to fields in libtrace's 'decodes.' Trace objects read or write libtrace python-libtrace Packets; the Trace class functions only specify details of the trace itself. From the Packet object, the classes are arranged in an inheritance hierarchy, as shown in the diagram below.

	Trace

	Packet

	Layer2

Layer3			Internet

	IP	IP6

Transport			TCP	UDP	ICMP, ICMP6

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 and 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 Python will later have to garbage-collect.

Nevil Brownlee
Mon, 6 Jan 14 (NZDT)