Wireshark · Ethereal-dev: [ethereal-dev] Ethereal dissector developers notes

[Jeff Foster <jfoste@xxxxxxxxxxxx>]

Having just written a dissector and watched the requests on this list for
help, I decided to do this write-up of what it takes to add a dissector.  I
was surprised by the number of steps required.  Any comments that improve
this write-up are welcome

Jeff Foster
jfoste@xxxxxxxxxxxx



----------------------------------------------------------------------------
-----------



Building your file -


Add the copyright statement -

Add the copyright state below to the start of you file and change these
items -

MY_FILE =  The name of the file.  The defacto standard is
'packet_MY_PROTOCOL.c'
MY_PROTOCOL = The name of the protocol that you are dissecting
MY_NAME =  Your name of course.  You do want credit don't you.  It's the
only payment you will receive.
MY_EMAIL_ADDRESS =  Keep those cards and letters coming.
WHATEVER_FILE_YOU_USED = Add this line if you are using another file as a
starting point.

The '$Id$' will be update by the CVS or RCS when the file is checked in.


/* MY_FILE.c
 * Routines for MY_PROTOCOL dissection
 * Copyright 1999, MY_NAME <MY_EMAIL_ADDRESS>
 *
 * $Id$
 *
 * Ethereal - Network traffic analyzer
 * By Gerald Combs <gerald@xxxxxxxxxx>
 * Copyright 1998 Gerald Combs
 *
 * Copied from WHATEVER_FILE_YOU_USED
 * 
 * This program is free software; you can redistribute it and/or
 * modify it under the terms of the GNU General Public License
 * as published by the Free Software Foundation; either version 2
 * of the License, or (at your option) any later version.
 * 
 * This program is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU General Public License for more details.
 * 
 * You should have received a copy of the GNU General Public License
 * along with this program; if not, write to the Free Software
 * Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA  02111-1307,
USA.
 */



/* Add the includes needed to write your program.  Be sure to add the
config.h and */
/* packet.h includes.	*/

#ifdef HAVE_CONFIG_H
#  include "config.h"
#endif

#include "packet.h"



The function name dissect_XXX is the default standard naming convention.
And the fd and offset variable names are required for the END_OF_FRAME
macro. It's definition is
fd->cap_len - offset.


/*  The standard format function definition */

void dissect_MY_PROTOCOL(const u_char *pd, int offset, frame_data *fd,
		proto_tree *tree)

{/* decode the MY_PROTOCOL protocol */


   proto_tree      *local_tree = 0;
   proto_item      *ti;

   guint16			Temp16;
/* I needed this, you may not. */
   
 /* Do any decoding needed for the summary display here */
 
    Temp16 = GSHORT(pd, offset);

/* Add the Protocol name for the summary display */

	if (check_col(fd, COL_PROTOCOL))
		col_add_str(fd, COL_PROTOCOL, "MY_PROTOCOL");


/* Add the Protocol information for the summary display */

/* NOTE: If you want to display a formated string here use */
/* 	the col_add_fstr call.  It is like a printf call -   */
/*	col_add_fstr( fd, COL_INFO, MY_FORMAT_STRING, ...);	*/

	if (check_col(fd, COL_INFO))
		  col_add_str(fd, COL_INFO, "MY_PROTOCOL_INFORMATION"));


/* In the interest of speed don't do anything else unless the tree value is
*/
/* defined.  The stuff from here on is used to do a detailed decode for
display      */
/* in the details window.  You don't need to do this unless the user has
highlighted */
/* this packet in the summary window.
*/

    if (tree) {
	
/* Add your subtree for detail display */
	  ti = proto_tree_add_item(tree, proto_MY_PROTOCOL, offset, length,
NULL);
	  local_tree = proto_item_add_subtree(ti, ETT_MY_TREE_NAME);

/* NOTE: The offset and length values in the previous call to
proto_tree_add_item 	*/
/*	define what data bytes to highlight in the hex display window.
*/
/*
*/
/*	END_OF_FRAME is a handy way to highlight all data from the offset to
the end	*/
/*	the packet.  See the note above about your function definition if
you want to	*/
/*	use END_OF_FRAME	*/

/*	Also note the use of ETT_MY_TREE_NAME */


	
/* Add the first item for your subtree*/
        proto_tree_add_text( local_tree, offset, 2, "Op code: %u (%s)",
Temp16,
      	( Temp16 == 1 ? "Write Mail slot" : "Unknown"));

	
/* Add the other items for your subtree*/
    
     else {
	/* do any higher level decodes that are needed to display summary
information here */
    }



----------------------------------------------------------------------------
-----------


Update the packet.h file

Edit the packet.h file and add the function prototype for your dissector.
Look for 'Routines in packet-*.c'  to find the right location.

Add any subtree names you have to the enum of Tree types (look for 'Tree
types').  The defacto standard is ETT_MY_TREE_NAME.  If you have multiple
subtrees, ie. bit fields, you will have to add an enum value for each tree.


----------------------------------------------------------------------------
-----------


Registering the protocol  -

Add a static int in your code -
	proto_MY_PROTOCOL = -1;

Add a routine in your code that is a call to protocol_register

	void proto_register_MY_PROTOCOL( void) {

		 proto_MY_PROTOCOL = proto_register_protocol( NAME,
ABBREVIATION);
	}

----------------------------------------------------------------------------
-----------


Modify the proto.c file

1) Add a function prototype for your protocol register function in the top
of the file (look for 'void proto_register').

2) Edit the function proto_init and add a call to your protocol register
routine 

	proto_register_MY_PROTOCOL();


----------------------------------------------------------------------------
-----------


Modifying the lower level dissector to test for your new protocol -

You will have modify the lower level protocol dissector to add a test for
the protocol you are adding.  This change is highly dependent upon the lower
level protocol dissector; so I recommend that you examine the source code to
determine how you can add your change.  Or even better contact the original
code owner for help on this part.