doc/packet-PROTOABBREV.c

   1 /* packet-PROTOABBREV.c
   2  * Routines for PROTONAME dissection
   3  * Copyright 201x, YOUR_NAME <YOUR_EMAIL_ADDRESS>
   4  *
   5  * $Id$
   6  *
   7  * Wireshark - Network traffic analyzer
   8  * By Gerald Combs <gerald@wireshark.org>
   9  * Copyright 1998 Gerald Combs
  10  *
  11  * This program is free software; you can redistribute it and/or modify
  12  * it under the terms of the GNU General Public License as published by
  13  * the Free Software Foundation; either version 2 of the License, or
  14  * (at your option) any later version.
  15  *
  16  * This program is distributed in the hope that it will be useful,
  17  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  18  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  19  * GNU General Public License for more details.
  20  *
  21  * You should have received a copy of the GNU General Public License along
  22  * with this program; if not, write to the Free Software Foundation, Inc.,
  23  * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
  24  */
  25
  26 #include "config.h"
  27
  28 #if 0
  29 /* Include only as needed */
  30 #include <stdio.h>
  31 #include <stdlib.h>
  32 #include <string.h>
  33 #endif
  34
  35 #include <glib.h>
  36
  37 #include <epan/packet.h>
  38 #include <epan/expert.h>
  39 #include <epan/prefs.h>
  40
  41 #if 0
  42 /* IF AND ONLY IF your protocol dissector exposes code to other dissectors
  43  * (which most dissectors don't need to do) then the 'public' prototypes and
  44  * data structures can go in the header file packet-PROTOABBREV.h. If not, then
  45  * a header file is not needed at all and this #include statement can be
  46  * removed. */
  47 #include "packet-PROTOABBREV.h"
  48 #endif
  49
  50 /* Forward declaration that is needed below if using the
  51  * proto_reg_handoff_PROTOABBREV function as a callback for when protocol
  52  * preferences get changed. */
  53 void proto_reg_handoff_PROTOABBREV(void);
  54
  55 /* Initialize the protocol and registered fields */
  56 static int proto_PROTOABBREV = -1;
  57 static int hf_PROTOABBREV_FIELDABBREV = -1;
  58 static expert_field ei_PROTOABBREV_EXPERTABBREV = EI_INIT;
  59
  60 /* Global sample preference ("controls" display of numbers) */
  61 static gboolean gPREF_HEX = FALSE;
  62 /* Global sample port preference - real port preferences should generally
  63  * default to 0 unless there is an IANA-registered (or equivalent) port for your
  64  * protocol. */
  65 static guint gPORT_PREF = 1234;
  66
  67 /* Initialize the subtree pointers */
  68 static gint ett_PROTOABBREV = -1;
  69
  70 /* A sample #define of the minimum length (in bytes) of the protocol data.
  71  * If data is received with fewer than this many bytes it is rejected by
  72  * the current dissector. */
  73 #define PROTOABBREV_MIN_LENGTH 8
  74
  75 /* Code to actually dissect the packets */
  76 static int
  77 dissect_PROTOABBREV(tvbuff_t *tvb, packet_info *pinfo, proto_tree *tree,
  78         void *data _U_)
  79 {
  80     /* Set up structures needed to add the protocol subtree and manage it */
  81     proto_item *ti, *expert_ti;
  82     proto_tree *PROTOABBREV_tree;
  83     /* Other misc. local variables. */
  84     guint offset = 0;
  85
  86     /*** HEURISTICS ***/
  87
  88     /* First, if at all possible, do some heuristics to check if the packet
  89      * cannot possibly belong to your protocol.  This is especially important
  90      * for protocols directly on top of TCP or UDP where port collisions are
  91      * common place (e.g., even though your protocol uses a well known port,
  92      * someone else may set up, for example, a web server on that port which,
  93      * if someone analyzed that web server's traffic in Wireshark, would result
  94      * in Wireshark handing an HTTP packet to your dissector).
  95      *
  96      * For example:
  97      */
  98
  99     /* Check that there's enough data */
 100     if (tvb_length(tvb) < PROTOABBREV_MIN_LENGTH)
 101         return 0;
 102
 103     /* Fetch some values from the packet header using tvb_get_*(). If these
 104      * values are not valid/possible in your protocol then return 0 to give
 105      * some other dissector a chance to dissect it.
 106      */
 107     if ( /* these values are not possible in PROTONAME */ )
 108         return 0;
 109
 110     /*** COLUMN DATA ***/
 111
 112     /* There are two normal columns to fill in: the 'Protocol' column which
 113      * is narrow and generally just contains the constant string 'PROTOABBREV',
 114      * and the 'Info' column which can be much wider and contain misc. summary
 115      * information (for example, the port number for TCP packets).
 116      *
 117      * If you are setting the column to a constant string, use "col_set_str()",
 118      * as it's more efficient than the other "col_set_XXX()" calls.
 119      *
 120      * If
 121      * - you may be appending to the column later OR
 122      * - you have constructed the string locally OR
 123      * - the string was returned from a call to val_to_str()
 124      * then use "col_add_str()" instead, as that takes a copy of the string.
 125      *
 126      * The function "col_add_fstr()" can be used instead of "col_add_str()"; it
 127      * takes "printf()"-like arguments. Don't use "col_add_fstr()" with a format
 128      * string of "%s" - just use "col_add_str()" or "col_set_str()", as it's
 129      * more efficient than "col_add_fstr()".
 130      *
 131      * For full details see section 1.4 of README.dissector.
 132      */
 133
 134     /* Set the Protocol column to the constant string of PROTOABBREV */
 135     col_set_str(pinfo->cinfo, COL_PROTOCOL, "PROTOABBREV");
 136
 137 #if 0
 138     /* If you will be fetching any data from the packet before filling in
 139      * the Info column, clear that column first in case the calls to fetch
 140      * data from the packet throw an exception so that the Info column doesn't
 141      * contain data left over from the previous dissector: */
 142     col_clear(pinfo->cinfo, COL_INFO);
 143 #endif
 144
 145     col_set_str(pinfo->cinfo, COL_INFO, "XXX Request");
 146
 147     /*** PROTOCOL TREE ***/
 148
 149     /* Now we will create a sub-tree for our protocol and start adding fields
 150      * to display under that sub-tree. Most of the time the only functions you
 151      * will need are proto_tree_add_item() and proto_item_add_subtree().
 152      *
 153      * NOTE: The offset and length values in the call to proto_tree_add_item()
 154      * define what data bytes to highlight in the hex display window when the
 155      * line in the protocol tree display corresponding to that item is selected.
 156      *
 157      * Supplying a length of -1 tells Wireshark to highlight all data from the
 158      * offset to the end of the packet.
 159      */
 160
 161     /* create display subtree for the protocol */
 162     ti = proto_tree_add_item(tree, proto_PROTOABBREV, tvb, 0, -1, ENC_NA);
 163
 164     PROTOABBREV_tree = proto_item_add_subtree(ti, ett_PROTOABBREV);
 165
 166     /* Add an item to the subtree, see section 1.5 of README.dissector for more
 167      * information. */
 168     expert_ti = proto_tree_add_item(PROTOABBREV_tree, hf_PROTOABBREV_FIELDABBREV, tvb,
 169             offset, len, ENC_xxx);
 170     offset += len;
 171     /* Some fields or situations may require "expert" analysis that can be
 172      * specifically highlighted. */
 173     if ( /* value of hf_PROTOABBREV_FIELDABBREV isn't what's expected */ )
 174         expert_add_info(pinfo, expert_ti, &ei_PROTOABBREV_EXPERTABBREV);
 175
 176     /* Continue adding tree items to process the packet here... */
 177
 178     /* If this protocol has a sub-dissector call it here, see section 1.8 of
 179      * README.dissector for more information. */
 180
 181     /* Return the amount of data this dissector was able to dissect (which may
 182      * or may not be the entire packet as we return here). */
 183     return tvb_length(tvb);
 184 }
 185
 186 /* Register the protocol with Wireshark.
 187  *
 188  * This format is require because a script is used to build the C function that
 189  * calls all the protocol registration.
 190  */
 191 void
 192 proto_register_PROTOABBREV(void)
 193 {
 194     module_t *PROTOABBREV_module;
 195     expert_module_t* expert_PROTOABBREV;
 196
 197     /* Setup list of header fields  See Section 1.5 of README.dissector for
 198      * details. */
 199     static hf_register_info hf[] = {
 200         { &hf_PROTOABBREV_FIELDABBREV,
 201             { "FIELDNAME", "PROTOABBREV.FIELDABBREV",
 202                FIELDTYPE, FIELDDISPLAY, FIELDCONVERT, BITMASK,
 203               "FIELDDESCR", HFILL }
 204         }
 205     };
 206
 207     /* Setup protocol subtree array */
 208     static gint *ett[] = {
 209         &ett_PROTOABBREV
 210     };
 211
 212     /* Setup protocol expert items */
 213     static ei_register_info ei[] = {
 214         { &ei_PROTOABBREV_EXPERTABBREV, { "PROTOABBREV.EXPERTABBREV", PI_SEVERITY, PI_GROUP, "EXPERTDESCR", EXPFILL }},
 215     };
 216
 217     /* Register the protocol name and description */
 218     proto_PROTOABBREV = proto_register_protocol("PROTONAME",
 219             "PROTOSHORTNAME", "PROTOABBREV");
 220
 221     /* Required function calls to register the header fields and subtrees */
 222     proto_register_field_array(proto_PROTOABBREV, hf, array_length(hf));
 223     proto_register_subtree_array(ett, array_length(ett));
 224     /* Required function calls to register expert items */
 225     expert_PROTOABBREV = expert_register_protocol(proto_PROTOABBREV);
 226     expert_register_field_array(expert_PROTOABBREV, ei, array_length(ei));
 227
 228     /* Register a preferences module (see section 2.6 of README.dissector
 229      * for more details). Registration of a prefs callback is not required
 230      * if there are no preferences that affect protocol registration (an example
 231      * of a preference that would affect registration is a port preference).
 232      * If the prefs callback is not needed, use NULL instead of
 233      * proto_reg_handoff_PROTOABBREV in the following.
 234      */
 235     PROTOABBREV_module = prefs_register_protocol(proto_PROTOABBREV,
 236             proto_reg_handoff_PROTOABBREV);
 237
 238     /* Register a preferences module under the preferences subtree.
 239      * Only use this function instead of prefs_register_protocol (above) if you
 240      * want to group preferences of several protocols under one preferences
 241      * subtree.
 242      *
 243      * Argument subtree identifies grouping tree node name, several subnodes can
 244      * be specified using slash '/' (e.g. "OSI/X.500" - protocol preferences
 245      * will be accessible under Protocols->OSI->X.500-><PROTOSHORTNAME>
 246      * preferences node.
 247      */
 248     PROTOABBREV_module = prefs_register_protocol_subtree(const char *subtree,
 249             proto_PROTOABBREV, proto_reg_handoff_PROTOABBREV);
 250
 251     /* Register a simple example preference */
 252     prefs_register_bool_preference(PROTOABBREV_module, "show_hex",
 253             "Display numbers in Hex",
 254             "Enable to display numerical values in hexadecimal.",
 255             &gPREF_HEX);
 256
 257     /* Register an example port preference */
 258     prefs_register_uint_preference(PROTOABBREV_module, "tcp.port", "PROTOABBREV TCP Port",
 259             " PROTOABBREV TCP port if other than the default",
 260             10, &gPORT_PREF);
 261 }
 262
 263 /* If this dissector uses sub-dissector registration add a registration routine.
 264  * This exact format is required because a script is used to find these
 265  * routines and create the code that calls these routines.
 266  *
 267  * If this function is registered as a prefs callback (see
 268  * prefs_register_protocol above) this function is also called by Wireshark's
 269  * preferences manager whenever "Apply" or "OK" are pressed. In that case, it
 270  * should accommodate being called more than once by use of the static
 271  * 'initialized' variable included below.
 272  *
 273  * This form of the reg_handoff function is used if if you perform registration
 274  * functions which are dependent upon prefs. See below this function for a
 275  * simpler form which can be used if there are no prefs-dependent registration
 276  * functions.
 277  */
 278 void
 279 proto_reg_handoff_PROTOABBREV(void)
 280 {
 281     static gboolean initialized = FALSE;
 282     static dissector_handle_t PROTOABBREV_handle;
 283     static int currentPort;
 284
 285     if (!initialized) {
 286         /* Use new_create_dissector_handle() to indicate that
 287          * dissect_PROTOABBREV() returns the number of bytes it dissected (or 0
 288          * if it thinks the packet does not belong to PROTONAME).
 289          */
 290         PROTOABBREV_handle = new_create_dissector_handle(dissect_PROTOABBREV,
 291                 proto_PROTOABBREV);
 292         initialized = TRUE;
 293
 294     } else {
 295         /* If you perform registration functions which are dependent upon
 296          * prefs then you should de-register everything which was associated
 297          * with the previous settings and re-register using the new prefs
 298          * settings here. In general this means you need to keep track of
 299          * the PROTOABBREV_handle and the value the preference had at the time
 300          * you registered.  The PROTOABBREV_handle value and the value of the
 301          * preference can be saved using local statics in this
 302          * function (proto_reg_handoff).
 303          */
 304         dissector_delete_uint("tcp.port", currentPort, PROTOABBREV_handle);
 305     }
 306
 307     currentPort = gPORT_PREF;
 308
 309     dissector_add_uint("tcp.port", currentPort, PROTOABBREV_handle);
 310 }
 311
 312 #if 0
 313 /* Simpler form of proto_reg_handoff_PROTOABBREV which can be used if there are
 314  * no prefs-dependent registration function calls. */
 315 void
 316 proto_reg_handoff_PROTOABBREV(void)
 317 {
 318     dissector_handle_t PROTOABBREV_handle;
 319
 320     /* Use new_create_dissector_handle() to indicate that dissect_PROTOABBREV()
 321      * returns the number of bytes it dissected (or 0 if it thinks the packet
 322      * does not belong to PROTONAME).
 323      */
 324     PROTOABBREV_handle = new_create_dissector_handle(dissect_PROTOABBREV,
 325             proto_PROTOABBREV);
 326     dissector_add_uint("PARENT_SUBFIELD", ID_VALUE, PROTOABBREV_handle);
 327 }
 328 #endif
 329
 330 /*
 331  * Editor modelines  -  http://www.wireshark.org/tools/modelines.html
 332  *
 333  * Local variables:
 334  * c-basic-offset: 4
 335  * tab-width: 8
 336  * indent-tabs-mode: nil
 337  * End:
 338  *
 339  * vi: set shiftwidth=4 tabstop=8 expandtab:
 340  * :indentSize=4:tabSize=8:noTabs=true:
 341  */