5.3 - The header's length

This is a property that the library runtime requires for every header. It is an essential piece of information that is very very header specific. For some headers the length is constant, never changing and for others it is dynamic, can only be determined when from the packet's data.

Both cases have to be addressed.

Constant length headers

If the header's length is constant and is known ahead of time you simply declare it in the @Header(length = [constant]) annotation by specifying the length parameter and that it.

public class MyHeader {
 /* fields go here */

Here is a constant length header. The length of this header is 20 bytes.

Dynamic length headers

For dynamic header you must include a static method within the header that returns the header's length. Here is an example:

public class MyHeader {

  public static int headerLength(JBuffer buffer, int offset) {
    return (super.getUByte(offset) & 0x0F) * 4; // Ip4 style hlen

The name of the method is irrelevant, but for the sake of consistency please use the name "headerLength". The method is supplied with a buffer and offset within the buffer the header starts. Its up to your method to read and calculate the right header length. The example is a type of headerLength that Ip4 would use. Thas is read the hlen field and multiply it 4.

There is a reason why the header length getter method is static and why it only receives a raw JBuffer to work with. Both reasons are related. Having a static method that can figure out the length of a header directly out of the raw packet buffer buffer is very useful. It means that given a buffer of octets from any source, and as long as the offset of the header into this buffer is known, this method can determine the exact boundary within the buffer that the header occupies. It also means that the method can be called on from any place within jNetPcap, even low level part that only has access to a buffer. The method is normally called by the packet scanner when its discovering which headers exist in the packet. Although the scanner may already know, based on type value of the previous header, what the next header may be, it doesn't know the actual header boundary yet. That is actually the reason why its calling on this header length method. Once the length is determined then it knows how to peer a java header object with the packet buffer, it has the offset and length of the header.

Core protocol's are scanned by the native packet scanner. This scanner is able to peek into header's on its own and lookup header lengths. So core protocols, don't actually call on these static methods. Custom protocols that are not core protocols though, do need to provide this method. Once a header definition is registered with JRegistry, the header length method is noted and made available the scanner. The scanner will call on your static headerLength method at the appropriate time, to determine the length of the header.

Lastly a note about sub-headers. jNetPcap header definition can contain sub headers. That is, top level header may contain optional sub headers or even always present sub-headers. Sub header's are not scanned by packet scanner, but are actually determined at the time the top-level header is accessed for the first time. When a user peers a header to a packet, the peering process allows each header to decode any optional or complex portions of itself. It is then that sub-headers are scanned, by the header definition itself. Therefore all sub-headers will have to provide either the static header length in annotation form or a dynamic method for retrieving the header's length. This may be optimized differently in the future, making the header length optional.