To create a custom header definition you need to define 2 things:

1. Header class file
2. Header to Header binding

A header definition before it can be used, has to be registered with JRegistry. Once registered the class can be used like any other header file.

Lets take a look at the most basic possible header definition. This one has no headers, its 0 length, no bindings defined to other headers but is a complete header definition that can be registered.

@Header(length=0)
public class ZeroLengthHeader extends JHeader {
}

---

What else can we put in a header file? The only mandatory annotation is the @Header applied to a java class. All the rest of annotations are optional. Most of the remaining annotations are only there to help JFormatter to generate textual output. That is they are there to convert a header definition with its runtime information to a hierarchy of header/field objects that can be generically inspected or printed out.

Header files can contain anything any normal class file can contain. Since the programmer has direct access to all the public functions of a header file, it is really up to the header definition designer as to what to put in the file, which fields to export through accessor methods, etc. Constants, protocol specific utility methods, static and instance methods. Anything can be placed inside a header definition.

There are some rules when you start to apply annotations. Lets look at a slightly more practical header example and go through each of its elements. This example uses standard Ethernet header definition, since it is one of the simpler definitions supplied with jNetPcpap.

@Header(length=14)
public class Ethernet extends JHeader {

  @Field(offset = 0, length = 48, format = "#mac#", description = "destination MAC address")
  public byte[] destination() {
    return super.getByteArray(0, 6);
  }

  @Field(offset = 6 * 8, length = 48, format = "#mac#", description = "source MAC address")
  public byte[] source() {
    return super.getByteArray(6, 6);
  }

  @Field(offset = 12 * 8, length = 16, format = "%d")
  public int type() {
    return super.getUShort(12);
  }
}

This is a complete header definition for Ethernet protocol. @Field annotation marks a method as a header field. The name of the method acts as the name of the field. The @Field annotation takes several parameters, all of which are optional. The offset and length are offset into the buffer starting at start of this header. The length fields specifies how long this field is. Both values are in bits. The description parameter is a static description string that will be printed out along side the field value. Parameter format specifies how to format the returned data for output. There are a number of predefined value formats.

So this definition has 3 fields. This was easy since all the fields are static in length and always appear at the same offset into the header. The header is also of static length, 14 bytes.

Of course, not all headers are that simple. Some headers are variable in length, have optional sub headers and fields. Fields have sub fields as well.