User guide

Next a dissector reference that we'll initialise later.
Now we have the basics in place to interact with the main program, we had better fill in those miss-
ing functions. Let's start with register function.
First a call to proto_register_protocol that registers the protocol. We can give it three names that will
be used for display in various places. The full and short name are used in e.g. the "Preferences" and
"Enabled protocols" dialogs as well as the generated field name list in the documentation. The ab-
breviation is used as the display filter name.
Next we need a handoff routine.
Example 9.2. Dissector Handoff.
void
proto_reg_handoff_foo(void)
{
static gboolean initialized = FALSE;
if (!initialized) {
foo_handle = create_dissector_handle(dissect_foo, proto_foo);
dissector_add("udp.port", global_foo_port, foo_handle);
}
}
What's happening here? We are initialising the dissector if it hasn't been initialised yet. First we cre-
ate the dissector. This registers a routine to be called to do the actual dissecting. Then we associate it
with a UDP port number so that the main program will know to call us when it gets UDP traffic on
that port.
Now at last we get to write some dissecting code. For the moment we'll leave it as a basic placehold-
er.
Example 9.3. Dissection.
static void
dissect_foo(tvbuff_t *tvb, packet_info *pinfo, proto_tree *tree)
{
if (check_col(pinfo->cinfo, COL_PROTOCOL)) {
col_set_str(pinfo->cinfo, COL_PROTOCOL, "FOO");
}
/* Clear out stuff in the info column */
if (check_col(pinfo->cinfo,COL_INFO)) {
col_clear(pinfo->cinfo,COL_INFO);
}
}
This function is called to dissect the packets presented to it. The packet data is held in a special buf-
fer referenced here as tvb. We shall become fairly familiar with this as we get deeper into the details
of the protocol. The packet info structure contains general data about the protocol, and we can up-
date information here. The tree parameter is where the detail dissection takes place.
For now we'll do the minimum we can get away with. The first two lines check to see if the Protocol
column is being displayed in the UI. If it is, we set the text of this to our protocol, so everyone can
see it's been recognised. The only other thing we do is to clear out any data in the INFO column if
it's being displayed.
At this point we should have a basic dissector ready to compile and install. It doesn't do much at
present, other than identify the protocol and label it.
Packet dissection
102