6 This file is a HOWTO for Wireshark developers. It describes how to start coding
7 a Wireshark protocol dissector and the use of some of the important functions
10 This file is compiled to give in depth information on Wireshark.
11 It is by no means all inclusive and complete. Please feel free to send
12 remarks and patches to the developer mailing list.
16 Before starting to develop a new dissector, a "running" Wireshark build
17 environment is required - there's no such thing as a standalone "dissector
20 How to setup such an environment is platform dependent; detailed information
21 about these steps can be found in the "Developer's Guide" (available from:
22 http://www.wireshark.org) and in the INSTALL and README files of the sources
25 0.1. General README files.
27 You'll find additional information in the following README files:
29 - README.capture - the capture engine internals
30 - README.design - Wireshark software design - incomplete
31 - README.developer - this file
32 - README.display_filter - Display Filter Engine
33 - README.idl2wrs - CORBA IDL converter
34 - README.packaging - how to distribute a software package containing WS
35 - README.regression - regression testing of WS and TS
36 - README.stats_tree - a tree statistics counting specific packets
37 - README.tapping - "tap" a dissector to get protocol specific events
38 - README.xml-output - how to work with the PDML exported output
39 - wiretap/README.developer - how to add additional capture file types to
42 0.2. Dissector related README files.
44 You'll find additional dissector related information in the following README
47 - README.binarytrees - fast access to large data collections
48 - README.heuristic - what are heuristic dissectors and how to write them
49 - README.malloc - how to obtain "memory leak free" memory
50 - README.plugins - how to "pluginize" a dissector
51 - README.python - writing a dissector in PYTHON.
52 - README.request_response_tracking - how to track req./resp. times and such
56 James Coe <jammer[AT]cin.net>
57 Gilbert Ramirez <gram[AT]alumni.rice.edu>
58 Jeff Foster <jfoste[AT]woodward.com>
59 Olivier Abad <oabad[AT]cybercable.fr>
60 Laurent Deniel <laurent.deniel[AT]free.fr>
61 Gerald Combs <gerald[AT]wireshark.org>
62 Guy Harris <guy[AT]alum.mit.edu>
63 Ulf Lamping <ulf.lamping[AT]web.de>
65 1. Setting up your protocol dissector code.
67 This section provides skeleton code for a protocol dissector. It also explains
68 the basic functions needed to enter values in the traffic summary columns,
69 add to the protocol tree, and work with registered header fields.
73 [[ This section has been moved to the Wireshark Developer's Guide ]]
77 Wireshark requires certain things when setting up a protocol dissector.
78 Below is skeleton code for a dissector that you can copy to a file and
79 fill in. Your dissector should follow the naming convention of packet-
80 followed by the abbreviated name for the protocol. It is recommended
81 that where possible you keep to the IANA abbreviated name for the
82 protocol, if there is one, or a commonly-used abbreviation for the
85 Usually, you will put your newly created dissector file into the directory
86 epan/dissectors, just like all the other packet-....c files already in there.
88 Also, please add your dissector file to the corresponding makefiles,
89 described in section "1.9 Editing Makefile.common and CMakeLists.txt
90 to add your dissector" below.
92 Dissectors that use the dissector registration to register with a lower level
93 dissector don't need to define a prototype in the .h file. For other
94 dissectors the main dissector routine should have a prototype in a header
95 file whose name is "packet-", followed by the abbreviated name for the
96 protocol, followed by ".h"; any dissector file that calls your dissector
97 should be changed to include that file.
99 You may not need to include all the headers listed in the skeleton
100 below, and you may need to include additional headers. For example, the
109 is needed only if you are using a function from libpcre, e.g. the
110 "pcre_compile()" function.
112 The stdio.h, stdlib.h and string.h header files should be included only as needed.
115 The "$Id$" in the comment will be updated by Subversion when the file is
118 When creating a new file, it is fine to just write "$Id$" as Subversion will
119 automatically fill in the identifier at the time the file will be added to the
120 SVN repository (committed).
122 ------------------------------------Cut here------------------------------------
123 /* packet-PROTOABBREV.c
124 * Routines for PROTONAME dissection
125 * Copyright 201x, YOUR_NAME <YOUR_EMAIL_ADDRESS>
129 * Wireshark - Network traffic analyzer
130 * By Gerald Combs <gerald@wireshark.org>
131 * Copyright 1998 Gerald Combs
133 * Copied from WHATEVER_FILE_YOU_USED (where "WHATEVER_FILE_YOU_USED"
134 * is a dissector file; if you just copied this from README.developer,
135 * don't bother with the "Copied from" - you don't even need to put
136 * in a "Copied from" if you copied an existing dissector, especially
137 * if the bulk of the code in the new dissector is your code)
139 * This program is free software; you can redistribute it and/or modify
140 * it under the terms of the GNU General Public License as published by
141 * the Free Software Foundation; either version 2 of the License, or
142 * (at your option) any later version.
144 * This program is distributed in the hope that it will be useful,
145 * but WITHOUT ANY WARRANTY; without even the implied warranty of
146 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
147 * GNU General Public License for more details.
149 * You should have received a copy of the GNU General Public License along
150 * with this program; if not, write to the Free Software Foundation, Inc.,
151 * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
159 /* Include only as needed */
167 #include <epan/packet.h>
168 #include <epan/prefs.h>
170 /* IF PROTO exposes code to other dissectors, then it must be exported
171 in a header file. If not, a header file is not needed at all. */
172 #include "packet-PROTOABBREV.h"
174 /* Forward declaration we need below (if using proto_reg_handoff...
175 as a prefs callback) */
176 void proto_reg_handoff_PROTOABBREV(void);
178 /* Initialize the protocol and registered fields */
179 static int proto_PROTOABBREV = -1;
180 static int hf_PROTOABBREV_FIELDABBREV = -1;
182 /* Global sample preference ("controls" display of numbers) */
183 static gboolean gPREF_HEX = FALSE;
184 /* Global sample port pref */
185 static guint gPORT_PREF = 1234;
187 /* Initialize the subtree pointers */
188 static gint ett_PROTOABBREV = -1;
190 /* Code to actually dissect the packets */
192 dissect_PROTOABBREV(tvbuff_t *tvb, packet_info *pinfo, proto_tree *tree)
195 /* Set up structures needed to add the protocol subtree and manage it */
197 proto_tree *PROTOABBREV_tree;
199 /* First, if at all possible, do some heuristics to check if the packet cannot
200 * possibly belong to your protocol. This is especially important for
201 * protocols directly on top of TCP or UDP where port collisions are
202 * common place (e.g., even though your protocol uses a well known port,
203 * someone else may set up, for example, a web server on that port which,
204 * if someone analyzed that web server's traffic in Wireshark, would result
205 * in Wireshark handing an HTTP packet to your dissector). For example:
207 /* Check that there's enough data */
208 if (tvb_length(tvb) < /* your protocol's smallest packet size */)
211 /* Get some values from the packet header, probably using tvb_get_*() */
212 if ( /* these values are not possible in PROTONAME */ )
213 /* This packet does not appear to belong to PROTONAME.
214 * Return 0 to give another dissector a chance to dissect it.
218 /* Make entries in Protocol column and Info column on summary display */
219 col_set_str(pinfo->cinfo, COL_PROTOCOL, "PROTOABBREV");
221 /* This field shows up as the "Info" column in the display; you should use
222 it, if possible, to summarize what's in the packet, so that a user looking
223 at the list of packets can tell what type of packet it is. See section 1.5
224 for more information.
226 If you are setting the column to a constant string, use "col_set_str()",
227 as it's more efficient than the other "col_set_XXX()" calls.
229 If you're setting it to a string you've constructed, or will be
230 appending to the column later, use "col_add_str()".
232 "col_add_fstr()" can be used instead of "col_add_str()"; it takes
233 "printf()"-like arguments. Don't use "col_add_fstr()" with a format
234 string of "%s" - just use "col_add_str()" or "col_set_str()", as it's
235 more efficient than "col_add_fstr()".
237 If you will be fetching any data from the packet before filling in
238 the Info column, clear that column first, in case the calls to fetch
239 data from the packet throw an exception because they're fetching data
240 past the end of the packet, so that the Info column doesn't have data
241 left over from the previous dissector; do
243 col_clear(pinfo->cinfo, COL_INFO);
247 col_set_str(pinfo->cinfo, COL_INFO, "XXX Request");
249 /* A protocol dissector may be called in 2 different ways - with, or
250 without a non-null "tree" argument.
252 If the proto_tree argument is null, Wireshark does not need to use
253 the protocol tree information from your dissector, and therefore is
254 passing the dissector a null "tree" argument so that it doesn't
255 need to do work necessary to build the protocol tree.
257 In the interest of speed, if "tree" is NULL, avoid building a
258 protocol tree and adding stuff to it, or even looking at any packet
259 data needed only if you're building the protocol tree, if possible.
261 Note, however, that you must fill in column information, create
262 conversations, reassemble packets, build any other persistent state
263 needed for dissection, and call subdissectors regardless of whether
264 "tree" is NULL or not. This might be inconvenient to do without
265 doing most of the dissection work; the routines for adding items to
266 the protocol tree can be passed a null protocol tree pointer, in
267 which case they'll return a null item pointer, and
268 "proto_item_add_subtree()" returns a null tree pointer if passed a
269 null item pointer, so, if you're careful not to dereference any null
270 tree or item pointers, you can accomplish this by doing all the
271 dissection work. This might not be as efficient as skipping that
272 work if you're not building a protocol tree, but if the code would
273 have a lot of tests whether "tree" is null if you skipped that work,
274 you might still be better off just doing all that work regardless of
275 whether "tree" is null or not.
277 Note also that there is no guarantee, the first time the dissector is
278 called, whether "tree" will be null or not; your dissector must work
279 correctly, building or updating whatever state information is
280 necessary, in either case. */
283 /* NOTE: The offset and length values in the call to
284 "proto_tree_add_item()" define what data bytes to highlight in the hex
285 display window when the line in the protocol tree display
286 corresponding to that item is selected.
288 Supplying a length of -1 is the way to highlight all data from the
289 offset to the end of the packet. */
291 /* create display subtree for the protocol */
292 ti = proto_tree_add_item(tree, proto_PROTOABBREV, tvb, 0, -1, ENC_NA);
294 PROTOABBREV_tree = proto_item_add_subtree(ti, ett_PROTOABBREV);
296 /* add an item to the subtree, see section 1.6 for more information */
297 proto_tree_add_item(PROTOABBREV_tree,
298 hf_PROTOABBREV_FIELDABBREV, tvb, offset, len, ENC_xxx);
301 /* Continue adding tree items to process the packet here */
306 /* If this protocol has a sub-dissector call it here, see section 1.8 */
308 /* Return the amount of data this dissector was able to dissect */
309 return tvb_length(tvb);
313 /* Register the protocol with Wireshark */
315 /* this format is require because a script is used to build the C function
316 that calls all the protocol registration.
320 proto_register_PROTOABBREV(void)
322 module_t *PROTOABBREV_module;
324 /* Setup list of header fields See Section 1.6.1 for details*/
325 static hf_register_info hf[] = {
326 { &hf_PROTOABBREV_FIELDABBREV,
327 { "FIELDNAME", "PROTOABBREV.FIELDABBREV",
328 FIELDTYPE, FIELDDISPLAY, FIELDCONVERT, BITMASK,
329 "FIELDDESCR", HFILL }
333 /* Setup protocol subtree array */
334 static gint *ett[] = {
338 /* Register the protocol name and description */
339 proto_PROTOABBREV = proto_register_protocol("PROTONAME",
340 "PROTOSHORTNAME", "PROTOABBREV");
342 /* Required function calls to register the header fields and subtrees used */
343 proto_register_field_array(proto_PROTOABBREV, hf, array_length(hf));
344 proto_register_subtree_array(ett, array_length(ett));
346 /* Register preferences module (See Section 2.6 for more on preferences) */
347 /* (Registration of a prefs callback is not required if there are no */
348 /* prefs-dependent registration functions (eg: a port pref). */
349 /* See proto_reg_handoff below. */
350 /* If a prefs callback is not needed, use NULL instead of */
351 /* proto_reg_handoff_PROTOABBREV in the following). */
352 PROTOABBREV_module = prefs_register_protocol(proto_PROTOABBREV,
353 proto_reg_handoff_PROTOABBREV);
355 /* Register preferences module under preferences subtree.
356 Use this function instead of prefs_register_protocol if you want to group
357 preferences of several protocols under one preferences subtree.
358 Argument subtree identifies grouping tree node name, several subnodes can be
359 specified usign slash '/' (e.g. "OSI/X.500" - protocol preferences will be
360 accessible under Protocols->OSI->X.500-><PROTOSHORTNAME> preferences node.
362 PROTOABBREV_module = prefs_register_protocol_subtree(const char *subtree,
363 proto_PROTOABBREV, proto_reg_handoff_PROTOABBREV);
365 /* Register a sample preference */
366 prefs_register_bool_preference(PROTOABBREV_module, "show_hex",
367 "Display numbers in Hex",
368 "Enable to display numerical values in hexadecimal.",
371 /* Register a sample port preference */
372 prefs_register_uint_preference(PROTOABBREV_module, "tcp.port", "PROTOABBREV TCP Port",
373 " PROTOABBREV TCP port if other than the default",
378 /* If this dissector uses sub-dissector registration add a registration routine.
379 This exact format is required because a script is used to find these
380 routines and create the code that calls these routines.
382 If this function is registered as a prefs callback (see prefs_register_protocol
383 above) this function is also called by preferences whenever "Apply" is pressed;
384 In that case, it should accommodate being called more than once.
386 This form of the reg_handoff function is used if if you perform
387 registration functions which are dependent upon prefs. See below
388 for a simpler form which can be used if there are no
389 prefs-dependent registration functions.
392 proto_reg_handoff_PROTOABBREV(void)
394 static gboolean initialized = FALSE;
395 static dissector_handle_t PROTOABBREV_handle;
396 static int currentPort;
400 /* Use new_create_dissector_handle() to indicate that dissect_PROTOABBREV()
401 * returns the number of bytes it dissected (or 0 if it thinks the packet
402 * does not belong to PROTONAME).
404 PROTOABBREV_handle = new_create_dissector_handle(dissect_PROTOABBREV,
410 If you perform registration functions which are dependent upon
411 prefs the you should de-register everything which was associated
412 with the previous settings and re-register using the new prefs
413 settings here. In general this means you need to keep track of
414 the PROTOABBREV_handle and the value the preference had at the time
415 you registered. The PROTOABBREV_handle value and the value of the
416 preference can be saved using local statics in this
417 function (proto_reg_handoff).
420 dissector_delete("tcp.port", currentPort, PROTOABBREV_handle);
423 currentPort = gPORT_PREF;
425 dissector_add("tcp.port", currentPort, PROTOABBREV_handle);
430 /* Simple form of proto_reg_handoff_PROTOABBREV which can be used if there are
431 no prefs-dependent registration function calls.
435 proto_reg_handoff_PROTOABBREV(void)
437 dissector_handle_t PROTOABBREV_handle;
439 /* Use new_create_dissector_handle() to indicate that dissect_PROTOABBREV()
440 * returns the number of bytes it dissected (or 0 if it thinks the packet
441 * does not belong to PROTONAME).
443 PROTOABBREV_handle = new_create_dissector_handle(dissect_PROTOABBREV,
445 dissector_add("PARENT_SUBFIELD", ID_VALUE, PROTOABBREV_handle);
450 ------------------------------------Cut here------------------------------------
452 1.3 Explanation of needed substitutions in code skeleton.
454 In the above code block the following strings should be substituted with
457 YOUR_NAME Your name, of course. You do want credit, don't you?
458 It's the only payment you will receive....
459 YOUR_EMAIL_ADDRESS Keep those cards and letters coming.
460 WHATEVER_FILE_YOU_USED Add this line if you are using another file as a
462 PROTONAME The name of the protocol; this is displayed in the
463 top-level protocol tree item for that protocol.
464 PROTOSHORTNAME An abbreviated name for the protocol; this is displayed
465 in the "Preferences" dialog box if your dissector has
466 any preferences, in the dialog box of enabled protocols,
467 and in the dialog box for filter fields when constructing
469 PROTOABBREV A name for the protocol for use in filter expressions;
470 it shall contain only lower-case letters, digits, and
472 FIELDNAME The displayed name for the header field.
473 FIELDABBREV The abbreviated name for the header field. (NO SPACES)
474 FIELDTYPE FT_NONE, FT_BOOLEAN, FT_UINT8, FT_UINT16, FT_UINT24,
475 FT_UINT32, FT_UINT64, FT_INT8, FT_INT16, FT_INT24, FT_INT32,
476 FT_INT64, FT_FLOAT, FT_DOUBLE, FT_ABSOLUTE_TIME,
477 FT_RELATIVE_TIME, FT_STRING, FT_STRINGZ, FT_EBCDIC,
478 FT_UINT_STRING, FT_ETHER, FT_BYTES, FT_UINT_BYTES, FT_IPv4,
479 FT_IPv6, FT_IPXNET, FT_FRAMENUM, FT_PROTOCOL, FT_GUID, FT_OID
480 FIELDDISPLAY For FT_UINT{8,16,24,32,64} and FT_INT{8,16,24,32,64):
482 BASE_DEC, BASE_HEX, BASE_OCT, BASE_DEC_HEX, BASE_HEX_DEC,
483 or BASE_CUSTOM, possibly ORed with BASE_RANGE_STRING
485 For FT_ABSOLUTE_TIME:
487 ABSOLUTE_TIME_LOCAL, ABSOLUTE_TIME_UTC, or
488 ABSOLUTE_TIME_DOY_UTC
490 For FT_BOOLEAN if BITMASK is non-zero:
492 Number of bits in the field containing the FT_BOOLEAN
498 FIELDCONVERT VALS(x), RVALS(x), TFS(x), NULL
499 BITMASK Usually 0x0 unless using the TFS(x) field conversion.
500 FIELDDESCR A brief description of the field, or NULL. [Please do not use ""].
501 PARENT_SUBFIELD Lower level protocol field used for lookup, i.e. "tcp.port"
502 ID_VALUE Lower level protocol field value that identifies this protocol
503 For example the TCP or UDP port number
505 If, for example, PROTONAME is "Internet Bogosity Discovery Protocol",
506 PROTOSHORTNAME would be "IBDP", and PROTOABBREV would be "ibdp". Try to
507 conform with IANA names.
509 1.4 The dissector and the data it receives.
514 This is only needed if the dissector doesn't use self-registration to
515 register itself with the lower level dissector, or if the protocol dissector
516 wants/needs to expose code to other subdissectors.
518 The dissector must be declared exactly as follows in the file
519 packet-PROTOABBREV.h:
522 dissect_PROTOABBREV(tvbuff_t *tvb, packet_info *pinfo, proto_tree *tree);
525 1.4.2 Extracting data from packets.
527 NOTE: See the file /epan/tvbuff.h for more details.
529 The "tvb" argument to a dissector points to a buffer containing the raw
530 data to be analyzed by the dissector; for example, for a protocol
531 running atop UDP, it contains the UDP payload (but not the UDP header,
532 or any protocol headers above it). A tvbuffer is an opaque data
533 structure, the internal data structures are hidden and the data must be
534 accessed via the tvbuffer accessors.
538 Bit accessors for a maximum of 8-bits, 16-bits 32-bits and 64-bits:
540 guint8 tvb_get_bits8(tvbuff_t *tvb, gint bit_offset, gint no_of_bits);
541 guint16 tvb_get_bits16(tvbuff_t *tvb, gint bit_offset, gint no_of_bits,gboolean little_endian);
542 guint32 tvb_get_bits32(tvbuff_t *tvb, gint bit_offset, gint no_of_bits,gboolean little_endian);
543 guint64 tvb_get_bits64(tvbuff_t *tvb, gint bit_offset, gint no_of_bits,gboolean little_endian);
545 Single-byte accessor:
547 guint8 tvb_get_guint8(tvbuff_t*, gint offset);
549 Network-to-host-order accessors for 16-bit integers (guint16), 24-bit
550 integers, 32-bit integers (guint32), and 64-bit integers (guint64):
552 guint16 tvb_get_ntohs(tvbuff_t*, gint offset);
553 guint32 tvb_get_ntoh24(tvbuff_t*, gint offset);
554 guint32 tvb_get_ntohl(tvbuff_t*, gint offset);
555 guint64 tvb_get_ntoh64(tvbuff_t*, gint offset);
557 Network-to-host-order accessors for single-precision and
558 double-precision IEEE floating-point numbers:
560 gfloat tvb_get_ntohieee_float(tvbuff_t*, gint offset);
561 gdouble tvb_get_ntohieee_double(tvbuff_t*, gint offset);
563 Little-Endian-to-host-order accessors for 16-bit integers (guint16),
564 24-bit integers, 32-bit integers (guint32), and 64-bit integers
567 guint16 tvb_get_letohs(tvbuff_t*, gint offset);
568 guint32 tvb_get_letoh24(tvbuff_t*, gint offset);
569 guint32 tvb_get_letohl(tvbuff_t*, gint offset);
570 guint64 tvb_get_letoh64(tvbuff_t*, gint offset);
572 Little-Endian-to-host-order accessors for single-precision and
573 double-precision IEEE floating-point numbers:
575 gfloat tvb_get_letohieee_float(tvbuff_t*, gint offset);
576 gdouble tvb_get_letohieee_double(tvbuff_t*, gint offset);
578 Accessors for IPv4 and IPv6 addresses:
580 guint32 tvb_get_ipv4(tvbuff_t*, gint offset);
581 void tvb_get_ipv6(tvbuff_t*, gint offset, struct e_in6_addr *addr);
583 NOTE: IPv4 addresses are not to be converted to host byte order before
584 being passed to "proto_tree_add_ipv4()". You should use "tvb_get_ipv4()"
585 to fetch them, not "tvb_get_ntohl()" *OR* "tvb_get_letohl()" - don't,
586 for example, try to use "tvb_get_ntohl()", find that it gives you the
587 wrong answer on the PC on which you're doing development, and try
588 "tvb_get_letohl()" instead, as "tvb_get_letohl()" will give the wrong
589 answer on big-endian machines.
593 void tvb_get_ntohguid(tvbuff_t *, gint offset, e_guid_t *guid);
594 void tvb_get_letohguid(tvbuff_t *, gint offset, e_guid_t *guid);
598 guint8 *tvb_get_string(tvbuff_t*, gint offset, gint length);
599 guint8 *tvb_get_ephemeral_string(tvbuff_t*, gint offset, gint length);
600 guint8 *tvb_get_seasonal_string(tvbuff_t*, gint offset, gint length);
602 Returns a null-terminated buffer containing data from the specified
603 tvbuff, starting at the specified offset, and containing the specified
604 length worth of characters (the length of the buffer will be length+1,
605 as it includes a null character to terminate the string).
607 tvb_get_string() returns a buffer allocated by g_malloc() so you must
608 g_free() it when you are finished with the string. Failure to g_free() this
609 buffer will lead to memory leaks.
611 tvb_get_ephemeral_string() returns a buffer allocated from a special heap
612 with a lifetime until the next packet is dissected. You do not need to
613 free() this buffer, it will happen automatically once the next packet is
616 tvb_get_seasonal_string() returns a buffer allocated from a special heap
617 with a lifetime of the current capture session. You do not need to
618 free() this buffer, it will happen automatically once the a new capture or
621 guint8 *tvb_get_stringz(tvbuff_t *tvb, gint offset, gint *lengthp);
622 guint8 *tvb_get_ephemeral_stringz(tvbuff_t *tvb, gint offset, gint *lengthp);
623 guint8 *tvb_get_seasonal_stringz(tvbuff_t *tvb, gint offset, gint *lengthp);
625 Returns a null-terminated buffer, allocated with "g_malloc()",
626 containing data from the specified tvbuff, starting at the
627 specified offset, and containing all characters from the tvbuff up to
628 and including a terminating null character in the tvbuff. "*lengthp"
629 will be set to the length of the string, including the terminating null.
631 tvb_get_stringz() returns a buffer allocated by g_malloc() so you must
632 g_free() it when you are finished with the string. Failure to g_free() this
633 buffer will lead to memory leaks.
634 tvb_get_ephemeral_stringz() returns a buffer allocated from a special heap
635 with a lifetime until the next packet is dissected. You do not need to
636 free() this buffer, it will happen automatically once the next packet is
639 tvb_get_seasonal_stringz() returns a buffer allocated from a special heap
640 with a lifetime of the current capture session. You do not need to
641 free() this buffer, it will happen automatically once the a new capture or
644 guint8 *tvb_fake_unicode(tvbuff_t*, gint offset, gint length, gboolean little_endian);
645 guint8 *tvb_get_ephemeral_faked_unicode(tvbuff_t*, gint offset, gint length, gboolean little_endian);
647 Converts a 2-byte unicode string to an ASCII string.
648 Returns a null-terminated buffer containing data from the specified
649 tvbuff, starting at the specified offset, and containing the specified
650 length worth of characters (the length of the buffer will be length+1,
651 as it includes a null character to terminate the string).
653 tvb_fake_unicode() returns a buffer allocated by g_malloc() so you must
654 g_free() it when you are finished with the string. Failure to g_free() this
655 buffer will lead to memory leaks.
656 tvb_get_ephemeral_faked_unicode() returns a buffer allocated from a special
657 heap with a lifetime until the next packet is dissected. You do not need to
658 free() this buffer, it will happen automatically once the next packet is
661 Byte Array Accessors:
663 gchar *tvb_bytes_to_str(tvbuff_t *tvb, gint offset, gint len);
665 Formats a bunch of data from a tvbuff as bytes, returning a pointer
666 to the string with the data formatted as two hex digits for each byte.
667 The string pointed to is stored in an "ep_alloc'd" buffer which will be freed
668 before the next frame is dissected. The formatted string will contain the hex digits
669 for at most the first 16 bytes of the data. If len is greater than 16 bytes, a
670 trailing "..." will be added to the string.
672 gchar *tvb_bytes_to_str_punct(tvbuff_t *tvb, gint offset, gint len, gchar punct);
674 This function is similar to tvb_bytes_to_str(...) except that 'punct' is inserted
675 between the hex representation of each byte.
679 guint8* tvb_memcpy(tvbuff_t*, guint8* target, gint offset, gint length);
681 Copies into the specified target the specified length's worth of data
682 from the specified tvbuff, starting at the specified offset.
684 guint8* tvb_memdup(tvbuff_t*, gint offset, gint length);
685 guint8* ep_tvb_memdup(tvbuff_t*, gint offset, gint length);
687 Returns a buffer, allocated with "g_malloc()", containing the specified
688 length's worth of data from the specified tvbuff, starting at the
689 specified offset. The ephemeral variant is freed automatically after the
693 /* WARNING! This function is possibly expensive, temporarily allocating
694 * another copy of the packet data. Furthermore, it's dangerous because once
695 * this pointer is given to the user, there's no guarantee that the user will
696 * honor the 'length' and not overstep the boundaries of the buffer.
698 guint8* tvb_get_ptr(tvbuff_t*, gint offset, gint length);
700 The reason that tvb_get_ptr() might have to allocate a copy of its data
701 only occurs with TVBUFF_COMPOSITES, data that spans multiple tvbuffers.
702 If the user requests a pointer to a range of bytes that span the member
703 tvbuffs that make up the TVBUFF_COMPOSITE, the data will have to be
704 copied to another memory region to assure that all the bytes are
709 1.5 Functions to handle columns in the traffic summary window.
711 The topmost pane of the main window is a list of the packets in the
712 capture, possibly filtered by a display filter.
714 Each line corresponds to a packet, and has one or more columns, as
715 configured by the user.
717 Many of the columns are handled by code outside individual dissectors;
718 most dissectors need only specify the value to put in the "Protocol" and
721 Columns are specified by COL_ values; the COL_ value for the "Protocol"
722 field, typically giving an abbreviated name for the protocol (but not
723 the all-lower-case abbreviation used elsewhere) is COL_PROTOCOL, and the
724 COL_ value for the "Info" field, giving a summary of the contents of the
725 packet for that protocol, is COL_INFO.
727 The value for a column can be specified with one of several functions,
728 all of which take the 'fd' argument to the dissector as their first
729 argument, and the COL_ value for the column as their second argument.
731 1.5.1 The col_set_str function.
733 'col_set_str' takes a string as its third argument, and sets the value
734 for the column to that value. It assumes that the pointer passed to it
735 points to a string constant or a static "const" array, not to a
736 variable, as it doesn't copy the string, it merely saves the pointer
737 value; the argument can itself be a variable, as long as it always
738 points to a string constant or a static "const" array.
740 It is more efficient than 'col_add_str' or 'col_add_fstr'; however, if
741 the dissector will be using 'col_append_str' or 'col_append_fstr" to
742 append more information to the column, the string will have to be copied
743 anyway, so it's best to use 'col_add_str' rather than 'col_set_str' in
746 For example, to set the "Protocol" column
749 col_set_str(pinfo->cinfo, COL_PROTOCOL, "PROTOABBREV");
752 1.5.2 The col_add_str function.
754 'col_add_str' takes a string as its third argument, and sets the value
755 for the column to that value. It takes the same arguments as
756 'col_set_str', but copies the string, so that if the string is, for
757 example, an automatic variable that won't remain in scope when the
758 dissector returns, it's safe to use.
761 1.5.3 The col_add_fstr function.
763 'col_add_fstr' takes a 'printf'-style format string as its third
764 argument, and 'printf'-style arguments corresponding to '%' format
765 items in that string as its subsequent arguments. For example, to set
766 the "Info" field to "<XXX> request, <N> bytes", where "reqtype" is a
767 string containing the type of the request in the packet and "n" is an
768 unsigned integer containing the number of bytes in the request:
770 col_add_fstr(pinfo->cinfo, COL_INFO, "%s request, %u bytes",
773 Don't use 'col_add_fstr' with a format argument of just "%s" -
774 'col_add_str', or possibly even 'col_set_str' if the string that matches
775 the "%s" is a static constant string, will do the same job more
779 1.5.4 The col_clear function.
781 If the Info column will be filled with information from the packet, that
782 means that some data will be fetched from the packet before the Info
783 column is filled in. If the packet is so small that the data in
784 question cannot be fetched, the routines to fetch the data will throw an
785 exception (see the comment at the beginning about tvbuffers improving
786 the handling of short packets - the tvbuffers keep track of how much
787 data is in the packet, and throw an exception on an attempt to fetch
788 data past the end of the packet, so that the dissector won't process
789 bogus data), causing the Info column not to be filled in.
791 This means that the Info column will have data for the previous
792 protocol, which would be confusing if, for example, the Protocol column
793 had data for this protocol.
795 Therefore, before a dissector fetches any data whatsoever from the
796 packet (unless it's a heuristic dissector fetching data to determine
797 whether the packet is one that it should dissect, in which case it
798 should check, before fetching the data, whether there's any data to
799 fetch; if there isn't, it should return FALSE), it should set the
800 Protocol column and the Info column.
802 If the Protocol column will ultimately be set to, for example, a value
803 containing a protocol version number, with the version number being a
804 field in the packet, the dissector should, before fetching the version
805 number field or any other field from the packet, set it to a value
806 without a version number, using 'col_set_str', and should later set it
807 to a value with the version number after it's fetched the version
810 If the Info column will ultimately be set to a value containing
811 information from the packet, the dissector should, before fetching any
812 fields from the packet, clear the column using 'col_clear' (which is
813 more efficient than clearing it by calling 'col_set_str' or
814 'col_add_str' with a null string), and should later set it to the real
815 string after it's fetched the data to use when doing that.
818 1.5.5 The col_append_str function.
820 Sometimes the value of a column, especially the "Info" column, can't be
821 conveniently constructed at a single point in the dissection process;
822 for example, it might contain small bits of information from many of the
823 fields in the packet. 'col_append_str' takes, as arguments, the same
824 arguments as 'col_add_str', but the string is appended to the end of the
825 current value for the column, rather than replacing the value for that
826 column. (Note that no blank separates the appended string from the
827 string to which it is appended; if you want a blank there, you must add
828 it yourself as part of the string being appended.)
831 1.5.6 The col_append_fstr function.
833 'col_append_fstr' is to 'col_add_fstr' as 'col_append_str' is to
834 'col_add_str' - it takes, as arguments, the same arguments as
835 'col_add_fstr', but the formatted string is appended to the end of the
836 current value for the column, rather than replacing the value for that
839 1.5.7 The col_append_sep_str and col_append_sep_fstr functions.
841 In specific situations the developer knows that a column's value will be
842 created in a stepwise manner, where the appended values are listed. Both
843 'col_append_sep_str' and 'col_append_sep_fstr' functions will add an item
844 separator between two consecutive items, and will not add the separator at the
845 beginning of the column. The remainder of the work both functions do is
846 identical to what 'col_append_str' and 'col_append_fstr' do.
848 1.5.8 The col_set_fence and col_prepend_fence_fstr functions.
850 Sometimes a dissector may be called multiple times for different PDUs in the
851 same frame (for example in the case of SCTP chunk bundling: several upper
852 layer data packets may be contained in one SCTP packet). If the upper layer
853 dissector calls 'col_set_str()' or 'col_clear()' on the Info column when it
854 begins dissecting each of those PDUs then when the frame is fully dissected
855 the Info column would contain only the string from the last PDU in the frame.
856 The 'col_set_fence' function erects a "fence" in the column that prevents
857 subsequent 'col_...' calls from clearing the data currently in that column.
858 For example, the SCTP dissector calls 'col_set_fence' on the Info column
859 after it has called any subdissectors for that chunk so that subdissectors
860 of any subsequent chunks may only append to the Info column.
861 'col_prepend_fence_fstr' prepends data before a fence (moving it if
862 necessary). It will create a fence at the end of the prepended data if the
863 fence does not already exist.
866 1.5.9 The col_set_time function.
868 The 'col_set_time' function takes an nstime value as its third argument.
869 This nstime value is a relative value and will be added as such to the
870 column. The fourth argument is the filtername holding this value. This
871 way, rightclicking on the column makes it possible to build a filter
872 based on the time-value.
876 nstime_delta(&ts, &pinfo->fd->abs_ts, &tcpd->ts_first);
877 col_set_time(pinfo->cinfo, COL_REL_CONV_TIME, &ts, "tcp.time_relative");
880 1.6 Constructing the protocol tree.
882 The middle pane of the main window, and the topmost pane of a packet
883 popup window, are constructed from the "protocol tree" for a packet.
885 The protocol tree, or proto_tree, is a GNode, the N-way tree structure
886 available within GLIB. Of course the protocol dissectors don't care
887 what a proto_tree really is; they just pass the proto_tree pointer as an
888 argument to the routines which allow them to add items and new branches
891 When a packet is selected in the packet-list pane, or a packet popup
892 window is created, a new logical protocol tree (proto_tree) is created.
893 The pointer to the proto_tree (in this case, 'protocol tree'), is passed
894 to the top-level protocol dissector, and then to all subsequent protocol
895 dissectors for that packet, and then the GUI tree is drawn via
898 The logical proto_tree needs to know detailed information about the protocols
899 and fields about which information will be collected from the dissection
900 routines. By strictly defining (or "typing") the data that can be attached to a
901 proto tree, searching and filtering becomes possible. This means that for
902 every protocol and field (which I also call "header fields", since they are
903 fields in the protocol headers) which might be attached to a tree, some
904 information is needed.
906 Every dissector routine will need to register its protocols and fields
907 with the central protocol routines (in proto.c). At first I thought I
908 might keep all the protocol and field information about all the
909 dissectors in one file, but decentralization seemed like a better idea.
910 That one file would have gotten very large; one small change would have
911 required a re-compilation of the entire file. Also, by allowing
912 registration of protocols and fields at run-time, loadable modules of
913 protocol dissectors (perhaps even user-supplied) is feasible.
915 To do this, each protocol should have a register routine, which will be
916 called when Wireshark starts. The code to call the register routines is
917 generated automatically; to arrange that a protocol's register routine
918 be called at startup:
920 the file containing a dissector's "register" routine must be
921 added to "DISSECTOR_SRC" in "epan/dissectors/Makefile.common"
922 (and in "epan/CMakeLists.txt");
924 the "register" routine must have a name of the form
925 "proto_register_XXX";
927 the "register" routine must take no argument, and return no
930 the "register" routine's name must appear in the source file
931 either at the beginning of the line, or preceded only by "void "
932 at the beginning of the line (that would typically be the
933 definition) - other white space shouldn't cause a problem, e.g.:
935 void proto_register_XXX(void) {
944 proto_register_XXX( void )
951 and so on should work.
953 For every protocol or field that a dissector wants to register, a variable of
954 type int needs to be used to keep track of the protocol. The IDs are
955 needed for establishing parent/child relationships between protocols and
956 fields, as well as associating data with a particular field so that it
957 can be stored in the logical tree and displayed in the GUI protocol
960 Some dissectors will need to create branches within their tree to help
961 organize header fields. These branches should be registered as header
962 fields. Only true protocols should be registered as protocols. This is
963 so that a display filter user interface knows how to distinguish
964 protocols from fields.
966 A protocol is registered with the name of the protocol and its
969 Here is how the frame "protocol" is registered.
973 proto_frame = proto_register_protocol (
975 /* short name */ "Frame",
976 /* abbrev */ "frame" );
978 A header field is also registered with its name and abbreviation, but
979 information about its data type is needed. It helps to look at
980 the header_field_info struct to see what information is expected:
982 struct header_field_info {
995 A string representing the name of the field. This is the name
996 that will appear in the graphical protocol tree. It must be a non-empty
1001 A string with an abbreviation of the field. We concatenate the
1002 abbreviation of the parent protocol with an abbreviation for the field,
1003 using a period as a separator. For example, the "src" field in an IP packet
1004 would have "ip.src" as an abbreviation. It is acceptable to have
1005 multiple levels of periods if, for example, you have fields in your
1006 protocol that are then subdivided into subfields. For example, TRMAC
1007 has multiple error fields, so the abbreviations follow this pattern:
1008 "trmac.errors.iso", "trmac.errors.noniso", etc.
1010 The abbreviation is the identifier used in a display filter. If it is
1011 an empty string then the field will not be filterable.
1015 The type of value this field holds. The current field types are:
1017 FT_NONE No field type. Used for fields that
1018 aren't given a value, and that can only
1019 be tested for presence or absence; a
1020 field that represents a data structure,
1021 with a subtree below it containing
1022 fields for the members of the structure,
1023 or that represents an array with a
1024 subtree below it containing fields for
1025 the members of the array, might be an
1027 FT_PROTOCOL Used for protocols which will be placing
1028 themselves as top-level items in the
1029 "Packet Details" pane of the UI.
1030 FT_BOOLEAN 0 means "false", any other value means
1032 FT_FRAMENUM A frame number; if this is used, the "Go
1033 To Corresponding Frame" menu item can
1035 FT_UINT8 An 8-bit unsigned integer.
1036 FT_UINT16 A 16-bit unsigned integer.
1037 FT_UINT24 A 24-bit unsigned integer.
1038 FT_UINT32 A 32-bit unsigned integer.
1039 FT_UINT64 A 64-bit unsigned integer.
1040 FT_INT8 An 8-bit signed integer.
1041 FT_INT16 A 16-bit signed integer.
1042 FT_INT24 A 24-bit signed integer.
1043 FT_INT32 A 32-bit signed integer.
1044 FT_INT64 A 64-bit signed integer.
1045 FT_FLOAT A single-precision floating point number.
1046 FT_DOUBLE A double-precision floating point number.
1047 FT_ABSOLUTE_TIME Seconds (4 bytes) and nanoseconds (4 bytes)
1048 of time since January 1, 1970, midnight
1049 UTC, displayed as the date, followed by
1050 the time, as hours, minutes, and seconds
1051 with 9 digits after the decimal point.
1052 FT_RELATIVE_TIME Seconds (4 bytes) and nanoseconds (4 bytes)
1053 of time relative to an arbitrary time.
1054 displayed as seconds and 9 digits
1055 after the decimal point.
1056 FT_STRING A string of characters, not necessarily
1057 NUL-terminated, but possibly NUL-padded.
1058 This, and the other string-of-characters
1059 types, are to be used for text strings,
1060 not raw binary data.
1061 FT_STRINGZ A NUL-terminated string of characters.
1062 FT_EBCDIC A string of characters, not necessarily
1063 NUL-terminated, but possibly NUL-padded.
1064 The data from the packet is converted from
1065 EBCDIC to ASCII before displaying to the user.
1066 FT_UINT_STRING A counted string of characters, consisting
1067 of a count (represented as an integral value,
1068 of width given in the proto_tree_add_item()
1069 call) followed immediately by that number of
1071 FT_ETHER A six octet string displayed in
1072 Ethernet-address format.
1073 FT_BYTES A string of bytes with arbitrary values;
1074 used for raw binary data.
1075 FT_UINT_BYTES A counted string of bytes, consisting
1076 of a count (represented as an integral value,
1077 of width given in the proto_tree_add_item()
1078 call) followed immediately by that number of
1079 arbitrary values; used for raw binary data.
1080 FT_IPv4 A version 4 IP address (4 bytes) displayed
1081 in dotted-quad IP address format (4
1082 decimal numbers separated by dots).
1083 FT_IPv6 A version 6 IP address (16 bytes) displayed
1084 in standard IPv6 address format.
1085 FT_IPXNET An IPX address displayed in hex as a 6-byte
1086 network number followed by a 6-byte station
1088 FT_GUID A Globally Unique Identifier
1089 FT_OID An ASN.1 Object Identifier
1091 Some of these field types are still not handled in the display filter
1092 routines, but the most common ones are. The FT_UINT* variables all
1093 represent unsigned integers, and the FT_INT* variables all represent
1094 signed integers; the number on the end represent how many bits are used
1095 to represent the number.
1097 Some constraints are imposed on the header fields depending on the type
1098 (e.g. FT_BYTES) of the field. Fields of type FT_ABSOLUTE_TIME must use
1099 'ABSOLUTE_TIME_{LOCAL,UTC,DOY_UTC}, NULL, 0x0' as values for the
1100 'display, 'strings', and 'bitmask' fields, and all other non-integral
1101 types (i.e.. types that are _not_ FT_INT* and FT_UINT*) must use
1102 'BASE_NONE, NULL, 0x0' as values for the 'display', 'strings', 'bitmask'
1103 fields. The reason is simply that the type itself implictly defines the
1104 nature of 'display', 'strings', 'bitmask'.
1108 The display field has a couple of overloaded uses. This is unfortunate,
1109 but since we're using C as an application programming language, this sometimes
1110 makes for cleaner programs. Right now I still think that overloading
1111 this variable was okay.
1113 For integer fields (FT_UINT* and FT_INT*), this variable represents the
1114 base in which you would like the value displayed. The acceptable bases
1124 BASE_DEC, BASE_HEX, and BASE_OCT are decimal, hexadecimal, and octal,
1125 respectively. BASE_DEC_HEX and BASE_HEX_DEC display value in two bases
1126 (the 1st representation followed by the 2nd in parenthesis).
1128 BASE_CUSTOM allows one to specify a callback function pointer that will
1129 format the value. The function pointer of the same type as defined by
1130 custom_fmt_func_t in epan/proto.h, specifically:
1132 void func(gchar *, guint32);
1134 The first argument is a pointer to a buffer of the ITEM_LABEL_LENGTH size
1135 and the second argument is the value to be formatted.
1137 For FT_BOOLEAN fields that are also bitfields (i.e. 'bitmask' is non-zero),
1138 'display' is used to tell the proto_tree how wide the parent bitfield is.
1139 With integers this is not needed since the type of integer itself
1140 (FT_UINT8, FT_UINT16, FT_UINT24, FT_UINT32, etc.) tells the proto_tree how
1141 wide the parent bitfield is.
1143 For FT_ABSOLUTE_TIME fields, 'display' is used to indicate whether the
1144 time is to be displayed as a time in the time zone for the machine on
1145 which Wireshark/TShark is running or as UTC and, for UTC, whether the
1146 date should be displayed as "{monthname}, {month} {day_of_month},
1147 {year}" or as "{year/day_of_year}".
1149 Additionally, BASE_NONE is used for 'display' as a NULL-value. That is, for
1150 non-integers other than FT_ABSOLUTE_TIME fields, and non-bitfield
1151 FT_BOOLEANs, you'll want to use BASE_NONE in the 'display' field. You may
1152 not use BASE_NONE for integers.
1154 It is possible that in the future we will record the endianness of
1155 integers. If so, it is likely that we'll use a bitmask on the display field
1156 so that integers would be represented as BEND|BASE_DEC or LEND|BASE_HEX.
1157 But that has not happened yet; note that there are protocols for which
1158 no endianness is specified, such as the X11 protocol and the DCE RPC
1159 protocol, so it would not be possible to record the endianness of all
1165 Some integer fields, of type FT_UINT*, need labels to represent the true
1166 value of a field. You could think of those fields as having an
1167 enumerated data type, rather than an integral data type.
1169 A 'value_string' structure is a way to map values to strings.
1171 typedef struct _value_string {
1176 For fields of that type, you would declare an array of "value_string"s:
1178 static const value_string valstringname[] = {
1179 { INTVAL1, "Descriptive String 1" },
1180 { INTVAL2, "Descriptive String 2" },
1184 (the last entry in the array must have a NULL 'strptr' value, to
1185 indicate the end of the array). The 'strings' field would be set to
1186 'VALS(valstringname)'.
1188 If the field has a numeric rather than an enumerated type, the 'strings'
1189 field would be set to NULL.
1191 -- Extended value strings
1192 You can also use an extended version of the value_string for faster lookups.
1193 It requires a value_string as input.
1194 If all of a contiguous range of values from min to max are present in the array
1195 the value will be used as as a direct index into a value_string array.
1197 If the values in the array are not contiguous (ie: there are "gaps"), but are in assending order
1198 a binary search will be used.
1200 Note: "gaps" in a value_string array can be filled with "empty" entries eg: {value, "Unknown"} so that
1201 direct access to the array is is possible.
1203 The init macro (see below) will perform a check on the value string
1204 the first time it is used to determine which search algorithm fits and fall back to a linear search
1205 if the value_string does not meet the criteria above.
1207 Use this macro to initialise the extended value_string at comile time:
1209 static value_string_ext valstringname_ext = VALUE_STRING_EXT_INIT(valstringname);
1211 Extended value strings can be created at runtime by calling
1212 value_string_ext_new(<ptr to value_string array>,
1213 <total number of entries in the value_string_array>, /* include {0, NULL} entry */
1214 <value_string_name>);
1216 For hf[] array FT_(U)INT* fields that need a 'valstringname_ext' struct, the 'strings' field
1217 would be set to '&valstringname_ext)'. Furthermore, 'display' field must be
1218 ORed with 'BASE_EXT_STRING' (e.g. BASE_DEC|BASE_EXT_STRING).
1222 If the field has a numeric type that might logically fit in ranges of values
1223 one can use a range_string struct.
1225 Thus a 'range_string' structure is a way to map ranges to strings.
1227 typedef struct _range_string {
1230 const gchar *strptr;
1233 For fields of that type, you would declare an array of "range_string"s:
1235 static const range_string rvalstringname[] = {
1236 { INTVAL_MIN1, INTVALMAX1, "Descriptive String 1" },
1237 { INTVAL_MIN2, INTVALMAX2, "Descriptive String 2" },
1241 If INTVAL_MIN equals INTVAL_MAX for a given entry the range_string
1242 behavior collapses to the one of value_string.
1243 For FT_(U)INT* fields that need a 'range_string' struct, the 'strings' field
1244 would be set to 'RVALS(rvalstringname)'. Furthermore, 'display' field must be
1245 ORed with 'BASE_RANGE_STRING' (e.g. BASE_DEC|BASE_RANGE_STRING).
1248 FT_BOOLEANs have a default map of 0 = "False", 1 (or anything else) = "True".
1249 Sometimes it is useful to change the labels for boolean values (e.g.,
1250 to "Yes"/"No", "Fast"/"Slow", etc.). For these mappings, a struct called
1251 true_false_string is used.
1253 typedef struct true_false_string {
1256 } true_false_string;
1258 For Boolean fields for which "False" and "True" aren't the desired
1259 labels, you would declare a "true_false_string"s:
1261 static const true_false_string boolstringname = {
1266 Its two fields are pointers to the string representing truth, and the
1267 string representing falsehood. For FT_BOOLEAN fields that need a
1268 'true_false_string' struct, the 'strings' field would be set to
1269 'TFS(&boolstringname)'.
1271 If the Boolean field is to be displayed as "False" or "True", the
1272 'strings' field would be set to NULL.
1274 Wireshark predefines a whole range of ready made "true_false_string"s
1275 in tfs.h, included via packet.h.
1279 If the field is a bitfield, then the bitmask is the mask which will
1280 leave only the bits needed to make the field when ANDed with a value.
1281 The proto_tree routines will calculate 'bitshift' automatically
1282 from 'bitmask', by finding the rightmost set bit in the bitmask.
1283 This shift is applied before applying string mapping functions or
1285 If the field is not a bitfield, then bitmask should be set to 0.
1289 This is a string giving a proper description of the field. It should be
1290 at least one grammatically complete sentence, or NULL in which case the
1291 name field is used. (Please do not use "").
1292 It is meant to provide a more detailed description of the field than the
1293 name alone provides. This information will be used in the man page, and
1294 in a future GUI display-filter creation tool. We might also add tooltips
1295 to the labels in the GUI protocol tree, in which case the blurb would
1296 be used as the tooltip text.
1299 1.6.1 Field Registration.
1301 Protocol registration is handled by creating an instance of the
1302 header_field_info struct (or an array of such structs), and
1303 calling the registration function along with the registration ID of
1304 the protocol that is the parent of the fields. Here is a complete example:
1306 static int proto_eg = -1;
1307 static int hf_field_a = -1;
1308 static int hf_field_b = -1;
1310 static hf_register_info hf[] = {
1313 { "Field A", "proto.field_a", FT_UINT8, BASE_HEX, NULL,
1314 0xf0, "Field A represents Apples", HFILL }},
1317 { "Field B", "proto.field_b", FT_UINT16, BASE_DEC, VALS(vs),
1318 0x0, "Field B represents Bananas", HFILL }}
1321 proto_eg = proto_register_protocol("Example Protocol",
1323 proto_register_field_array(proto_eg, hf, array_length(hf));
1325 Be sure that your array of hf_register_info structs is declared 'static',
1326 since the proto_register_field_array() function does not create a copy
1327 of the information in the array... it uses that static copy of the
1328 information that the compiler created inside your array. Here's the
1329 layout of the hf_register_info struct:
1331 typedef struct hf_register_info {
1332 int *p_id; /* pointer to parent variable */
1333 header_field_info hfinfo;
1336 Also be sure to use the handy array_length() macro found in packet.h
1337 to have the compiler compute the array length for you at compile time.
1339 If you don't have any fields to register, do *NOT* create a zero-length
1340 "hf" array; not all compilers used to compile Wireshark support them.
1341 Just omit the "hf" array, and the "proto_register_field_array()" call,
1344 It is OK to have header fields with a different format be registered with
1345 the same abbreviation. For instance, the following is valid:
1347 static hf_register_info hf[] = {
1349 { &hf_field_8bit, /* 8-bit version of proto.field */
1350 { "Field (8 bit)", "proto.field", FT_UINT8, BASE_DEC, NULL,
1351 0x00, "Field represents FOO", HFILL }},
1353 { &hf_field_32bit, /* 32-bit version of proto.field */
1354 { "Field (32 bit)", "proto.field", FT_UINT32, BASE_DEC, NULL,
1355 0x00, "Field represents FOO", HFILL }}
1358 This way a filter expression can match a header field, irrespective of the
1359 representation of it in the specific protocol context. This is interesting
1360 for protocols with variable-width header fields.
1362 The HFILL macro at the end of the struct will set reasonable default values
1363 for internally used fields.
1365 1.6.2 Adding Items and Values to the Protocol Tree.
1367 A protocol item is added to an existing protocol tree with one of a
1368 handful of proto_XXX_DO_YYY() functions.
1370 Remember that it only makes sense to add items to a protocol tree if its
1371 proto_tree pointer is not null. Should you add an item to a NULL tree, then
1372 the proto_XXX_DO_YYY() function will immediately return. The cost of this
1373 function call can be avoided by checking for the tree pointer.
1375 Subtrees can be made with the proto_item_add_subtree() function:
1377 item = proto_tree_add_item(....);
1378 new_tree = proto_item_add_subtree(item, tree_type);
1380 This will add a subtree under the item in question; a subtree can be
1381 created under an item made by any of the "proto_tree_add_XXX" functions,
1382 so that the tree can be given an arbitrary depth.
1384 Subtree types are integers, assigned by
1385 "proto_register_subtree_array()". To register subtree types, pass an
1386 array of pointers to "gint" variables to hold the subtree type values to
1387 "proto_register_subtree_array()":
1389 static gint ett_eg = -1;
1390 static gint ett_field_a = -1;
1392 static gint *ett[] = {
1397 proto_register_subtree_array(ett, array_length(ett));
1399 in your "register" routine, just as you register the protocol and the
1400 fields for that protocol.
1402 There are several functions that the programmer can use to add either
1403 protocol or field labels to the proto_tree:
1406 proto_tree_add_item(tree, id, tvb, start, length, encoding);
1409 proto_tree_add_none_format(tree, id, tvb, start, length, format, ...);
1412 proto_tree_add_protocol_format(tree, id, tvb, start, length,
1416 proto_tree_add_bytes(tree, id, tvb, start, length, start_ptr);
1419 proto_tree_add_bytes_format(tree, id, tvb, start, length, start_ptr,
1423 proto_tree_add_bytes_format_value(tree, id, tvb, start, length,
1424 start_ptr, format, ...);
1427 proto_tree_add_time(tree, id, tvb, start, length, value_ptr);
1430 proto_tree_add_time_format(tree, id, tvb, start, length, value_ptr,
1434 proto_tree_add_time_format_value(tree, id, tvb, start, length,
1435 value_ptr, format, ...);
1438 proto_tree_add_ipxnet(tree, id, tvb, start, length, value);
1441 proto_tree_add_ipxnet_format(tree, id, tvb, start, length, value,
1445 proto_tree_add_ipxnet_format_value(tree, id, tvb, start, length,
1446 value, format, ...);
1449 proto_tree_add_ipv4(tree, id, tvb, start, length, value);
1452 proto_tree_add_ipv4_format(tree, id, tvb, start, length, value,
1456 proto_tree_add_ipv4_format_value(tree, id, tvb, start, length,
1457 value, format, ...);
1460 proto_tree_add_ipv6(tree, id, tvb, start, length, value_ptr);
1463 proto_tree_add_ipv6_format(tree, id, tvb, start, length, value_ptr,
1467 proto_tree_add_ipv6_format_value(tree, id, tvb, start, length,
1468 value_ptr, format, ...);
1471 proto_tree_add_ether(tree, id, tvb, start, length, value_ptr);
1474 proto_tree_add_ether_format(tree, id, tvb, start, length, value_ptr,
1478 proto_tree_add_ether_format_value(tree, id, tvb, start, length,
1479 value_ptr, format, ...);
1482 proto_tree_add_string(tree, id, tvb, start, length, value_ptr);
1485 proto_tree_add_string_format(tree, id, tvb, start, length, value_ptr,
1489 proto_tree_add_string_format_value(tree, id, tvb, start, length,
1490 value_ptr, format, ...);
1493 proto_tree_add_boolean(tree, id, tvb, start, length, value);
1496 proto_tree_add_boolean_format(tree, id, tvb, start, length, value,
1500 proto_tree_add_boolean_format_value(tree, id, tvb, start, length,
1501 value, format, ...);
1504 proto_tree_add_float(tree, id, tvb, start, length, value);
1507 proto_tree_add_float_format(tree, id, tvb, start, length, value,
1511 proto_tree_add_float_format_value(tree, id, tvb, start, length,
1512 value, format, ...);
1515 proto_tree_add_double(tree, id, tvb, start, length, value);
1518 proto_tree_add_double_format(tree, id, tvb, start, length, value,
1522 proto_tree_add_double_format_value(tree, id, tvb, start, length,
1523 value, format, ...);
1526 proto_tree_add_uint(tree, id, tvb, start, length, value);
1529 proto_tree_add_uint_format(tree, id, tvb, start, length, value,
1533 proto_tree_add_uint_format_value(tree, id, tvb, start, length,
1534 value, format, ...);
1537 proto_tree_add_uint64(tree, id, tvb, start, length, value);
1540 proto_tree_add_uint64_format(tree, id, tvb, start, length, value,
1544 proto_tree_add_uint64_format_value(tree, id, tvb, start, length,
1545 value, format, ...);
1548 proto_tree_add_int(tree, id, tvb, start, length, value);
1551 proto_tree_add_int_format(tree, id, tvb, start, length, value,
1555 proto_tree_add_int_format_value(tree, id, tvb, start, length,
1556 value, format, ...);
1559 proto_tree_add_int64(tree, id, tvb, start, length, value);
1562 proto_tree_add_int64_format(tree, id, tvb, start, length, value,
1566 proto_tree_add_int64_format_value(tree, id, tvb, start, length,
1567 value, format, ...);
1570 proto_tree_add_text(tree, tvb, start, length, format, ...);
1573 proto_tree_add_text_valist(tree, tvb, start, length, format, ap);
1576 proto_tree_add_guid(tree, id, tvb, start, length, value_ptr);
1579 proto_tree_add_guid_format(tree, id, tvb, start, length, value_ptr,
1583 proto_tree_add_guid_format_value(tree, id, tvb, start, length,
1584 value_ptr, format, ...);
1587 proto_tree_add_oid(tree, id, tvb, start, length, value_ptr);
1590 proto_tree_add_oid_format(tree, id, tvb, start, length, value_ptr,
1594 proto_tree_add_oid_format_value(tree, id, tvb, start, length,
1595 value_ptr, format, ...);
1598 proto_tree_add_bits_item(tree, id, tvb, bit_offset, no_of_bits,
1602 proto_tree_add_bits_ret_val(tree, id, tvb, bit_offset, no_of_bits,
1603 return_value, little_endian);
1606 proto_tree_add_bitmask(tree, tvb, start, header, ett, fields,
1610 proto_tree_add_bitmask_text(tree, tvb, offset, len, name, fallback,
1611 ett, fields, little_endian, flags);
1613 The 'tree' argument is the tree to which the item is to be added. The
1614 'tvb' argument is the tvbuff from which the item's value is being
1615 extracted; the 'start' argument is the offset from the beginning of that
1616 tvbuff of the item being added, and the 'length' argument is the length,
1617 in bytes, of the item, bit_offset is the offset in bits and no_of_bits
1618 is the length in bits.
1620 The length of some items cannot be determined until the item has been
1621 dissected; to add such an item, add it with a length of -1, and, when the
1622 dissection is complete, set the length with 'proto_item_set_len()':
1625 proto_item_set_len(ti, length);
1627 The "ti" argument is the value returned by the call that added the item
1628 to the tree, and the "length" argument is the length of the item.
1630 proto_tree_add_item()
1631 ---------------------
1632 proto_tree_add_item is used when you wish to do no special formatting.
1633 The item added to the GUI tree will contain the name (as passed in the
1634 proto_register_*() function) and a value. The value will be fetched
1635 from the tvbuff by proto_tree_add_item(), based on the type of the field
1636 and, for integral and Boolean fields, the byte order of the value; the
1637 byte order, for items for which that's relevant, is specified by the
1638 'encoding' argument, which is ENC_LITTLE_ENDIAN if the value is
1639 little-endian and ENC_BIG_ENDIAN if it is big-endian. If the byte order
1640 is not relevant, use ENC_NA (Not Applicable). In the future, other
1641 elements of the encoding, such as the character encoding for
1642 character strings, might be supported.
1644 Now that definitions of fields have detailed information about bitfield
1645 fields, you can use proto_tree_add_item() with no extra processing to
1646 add bitfield values to your tree. Here's an example. Take the Format
1647 Identifier (FID) field in the Transmission Header (TH) portion of the SNA
1648 protocol. The FID is the high nibble of the first byte of the TH. The
1649 FID would be registered like this:
1651 name = "Format Identifier"
1652 abbrev = "sna.th.fid"
1655 strings = sna_th_fid_vals
1658 The bitmask contains the value which would leave only the FID if bitwise-ANDed
1659 against the parent field, the first byte of the TH.
1661 The code to add the FID to the tree would be;
1663 proto_tree_add_item(bf_tree, hf_sna_th_fid, tvb, offset, 1,
1666 The definition of the field already has the information about bitmasking
1667 and bitshifting, so it does the work of masking and shifting for us!
1668 This also means that you no longer have to create value_string structs
1669 with the values bitshifted. The value_string for FID looks like this,
1670 even though the FID value is actually contained in the high nibble.
1671 (You'd expect the values to be 0x0, 0x10, 0x20, etc.)
1673 /* Format Identifier */
1674 static const value_string sna_th_fid_vals[] = {
1675 { 0x0, "SNA device <--> Non-SNA Device" },
1676 { 0x1, "Subarea Node <--> Subarea Node" },
1677 { 0x2, "Subarea Node <--> PU2" },
1678 { 0x3, "Subarea Node or SNA host <--> Subarea Node" },
1681 { 0xf, "Adjacent Subarea Nodes" },
1685 The final implication of this is that display filters work the way you'd
1686 naturally expect them to. You'd type "sna.th.fid == 0xf" to find Adjacent
1687 Subarea Nodes. The user does not have to shift the value of the FID to
1688 the high nibble of the byte ("sna.th.fid == 0xf0") as was necessary
1691 proto_tree_add_protocol_format()
1692 --------------------------------
1693 proto_tree_add_protocol_format is used to add the top-level item for the
1694 protocol when the dissector routine wants complete control over how the
1695 field and value will be represented on the GUI tree. The ID value for
1696 the protocol is passed in as the "id" argument; the rest of the
1697 arguments are a "printf"-style format and any arguments for that format.
1698 The caller must include the name of the protocol in the format; it is
1699 not added automatically as in proto_tree_add_item().
1701 proto_tree_add_none_format()
1702 ----------------------------
1703 proto_tree_add_none_format is used to add an item of type FT_NONE.
1704 The caller must include the name of the field in the format; it is
1705 not added automatically as in proto_tree_add_item().
1707 proto_tree_add_bytes()
1708 proto_tree_add_time()
1709 proto_tree_add_ipxnet()
1710 proto_tree_add_ipv4()
1711 proto_tree_add_ipv6()
1712 proto_tree_add_ether()
1713 proto_tree_add_string()
1714 proto_tree_add_boolean()
1715 proto_tree_add_float()
1716 proto_tree_add_double()
1717 proto_tree_add_uint()
1718 proto_tree_add_uint64()
1719 proto_tree_add_int()
1720 proto_tree_add_int64()
1721 proto_tree_add_guid()
1722 proto_tree_add_oid()
1723 ------------------------
1724 These routines are used to add items to the protocol tree if either:
1726 the value of the item to be added isn't just extracted from the
1727 packet data, but is computed from data in the packet;
1729 the value was fetched into a variable.
1731 The 'value' argument has the value to be added to the tree.
1733 NOTE: in all cases where the 'value' argument is a pointer, a copy is
1734 made of the object pointed to; if you have dynamically allocated a
1735 buffer for the object, that buffer will not be freed when the protocol
1736 tree is freed - you must free the buffer yourself when you don't need it
1739 For proto_tree_add_bytes(), the 'value_ptr' argument is a pointer to a
1742 For proto_tree_add_time(), the 'value_ptr' argument is a pointer to an
1743 "nstime_t", which is a structure containing the time to be added; it has
1744 'secs' and 'nsecs' members, giving the integral part and the fractional
1745 part of a time in units of seconds, with 'nsecs' being the number of
1746 nanoseconds. For absolute times, "secs" is a UNIX-style seconds since
1747 January 1, 1970, 00:00:00 GMT value.
1749 For proto_tree_add_ipxnet(), the 'value' argument is a 32-bit IPX
1752 For proto_tree_add_ipv4(), the 'value' argument is a 32-bit IPv4
1753 address, in network byte order.
1755 For proto_tree_add_ipv6(), the 'value_ptr' argument is a pointer to a
1756 128-bit IPv6 address.
1758 For proto_tree_add_ether(), the 'value_ptr' argument is a pointer to a
1761 For proto_tree_add_string(), the 'value_ptr' argument is a pointer to a
1764 For proto_tree_add_boolean(), the 'value' argument is a 32-bit integer.
1765 It is masked and shifted as defined by the field info after which zero
1766 means "false", and non-zero means "true".
1768 For proto_tree_add_float(), the 'value' argument is a 'float' in the
1769 host's floating-point format.
1771 For proto_tree_add_double(), the 'value' argument is a 'double' in the
1772 host's floating-point format.
1774 For proto_tree_add_uint(), the 'value' argument is a 32-bit unsigned
1775 integer value, in host byte order. (This routine cannot be used to add
1778 For proto_tree_add_uint64(), the 'value' argument is a 64-bit unsigned
1779 integer value, in host byte order.
1781 For proto_tree_add_int(), the 'value' argument is a 32-bit signed
1782 integer value, in host byte order. (This routine cannot be used to add
1785 For proto_tree_add_int64(), the 'value' argument is a 64-bit signed
1786 integer value, in host byte order.
1788 For proto_tree_add_guid(), the 'value_ptr' argument is a pointer to an
1791 For proto_tree_add_oid(), the 'value_ptr' argument is a pointer to an
1792 ASN.1 Object Identifier.
1794 proto_tree_add_bytes_format()
1795 proto_tree_add_time_format()
1796 proto_tree_add_ipxnet_format()
1797 proto_tree_add_ipv4_format()
1798 proto_tree_add_ipv6_format()
1799 proto_tree_add_ether_format()
1800 proto_tree_add_string_format()
1801 proto_tree_add_boolean_format()
1802 proto_tree_add_float_format()
1803 proto_tree_add_double_format()
1804 proto_tree_add_uint_format()
1805 proto_tree_add_uint64_format()
1806 proto_tree_add_int_format()
1807 proto_tree_add_int64_format()
1808 proto_tree_add_guid_format()
1809 proto_tree_add_oid_format()
1810 ----------------------------
1811 These routines are used to add items to the protocol tree when the
1812 dissector routine wants complete control over how the field and value
1813 will be represented on the GUI tree. The argument giving the value is
1814 the same as the corresponding proto_tree_add_XXX() function; the rest of
1815 the arguments are a "printf"-style format and any arguments for that
1816 format. The caller must include the name of the field in the format; it
1817 is not added automatically as in the proto_tree_add_XXX() functions.
1819 proto_tree_add_bytes_format_value()
1820 proto_tree_add_time_format_value()
1821 proto_tree_add_ipxnet_format_value()
1822 proto_tree_add_ipv4_format_value()
1823 proto_tree_add_ipv6_format_value()
1824 proto_tree_add_ether_format_value()
1825 proto_tree_add_string_format_value()
1826 proto_tree_add_boolean_format_value()
1827 proto_tree_add_float_format_value()
1828 proto_tree_add_double_format_value()
1829 proto_tree_add_uint_format_value()
1830 proto_tree_add_uint64_format_value()
1831 proto_tree_add_int_format_value()
1832 proto_tree_add_int64_format_value()
1833 proto_tree_add_guid_format_value()
1834 proto_tree_add_oid_format_value()
1835 ------------------------------------
1837 These routines are used to add items to the protocol tree when the
1838 dissector routine wants complete control over how the value will be
1839 represented on the GUI tree. The argument giving the value is the same
1840 as the corresponding proto_tree_add_XXX() function; the rest of the
1841 arguments are a "printf"-style format and any arguments for that format.
1842 With these routines, unlike the proto_tree_add_XXX_format() routines,
1843 the name of the field is added automatically as in the
1844 proto_tree_add_XXX() functions; only the value is added with the format.
1846 proto_tree_add_text()
1847 ---------------------
1848 proto_tree_add_text() is used to add a label to the GUI tree. It will
1849 contain no value, so it is not searchable in the display filter process.
1850 This function was needed in the transition from the old-style proto_tree
1851 to this new-style proto_tree so that Wireshark would still decode all
1852 protocols w/o being able to filter on all protocols and fields.
1853 Otherwise we would have had to cripple Wireshark's functionality while we
1854 converted all the old-style proto_tree calls to the new-style proto_tree
1855 calls. In other words, you should not use this in new code unless you've got
1856 a specific reason (see below).
1858 This can also be used for items with subtrees, which may not have values
1859 themselves - the items in the subtree are the ones with values.
1861 For a subtree, the label on the subtree might reflect some of the items
1862 in the subtree. This means the label can't be set until at least some
1863 of the items in the subtree have been dissected. To do this, use
1864 'proto_item_set_text()' or 'proto_item_append_text()':
1867 proto_item_set_text(proto_item *ti, ...);
1870 proto_item_append_text(proto_item *ti, ...);
1872 'proto_item_set_text()' takes as an argument the value returned by
1873 'proto_tree_add_text()', a 'printf'-style format string, and a set of
1874 arguments corresponding to '%' format items in that string, and replaces
1875 the text for the item created by 'proto_tree_add_text()' with the result
1876 of applying the arguments to the format string.
1878 'proto_item_append_text()' is similar, but it appends to the text for
1879 the item the result of applying the arguments to the format string.
1881 For example, early in the dissection, one might do:
1883 ti = proto_tree_add_text(tree, tvb, offset, length, <label>);
1887 proto_item_set_text(ti, "%s: %s", type, value);
1889 after the "type" and "value" fields have been extracted and dissected.
1890 <label> would be a label giving what information about the subtree is
1891 available without dissecting any of the data in the subtree.
1893 Note that an exception might be thrown when trying to extract the values of
1894 the items used to set the label, if not all the bytes of the item are
1895 available. Thus, one should create the item with text that is as
1896 meaningful as possible, and set it or append additional information to
1897 it as the values needed to supply that information are extracted.
1899 proto_tree_add_text_valist()
1900 ----------------------------
1901 This is like proto_tree_add_text(), but takes, as the last argument, a
1902 'va_list'; it is used to allow routines that take a printf-like
1903 variable-length list of arguments to add a text item to the protocol
1906 proto_tree_add_bits_item()
1907 --------------------------
1908 Adds a number of bits to the protocol tree which does not have to be byte
1909 aligned. The offset and length is in bits.
1912 ..10 1010 10.. .... "value" (formatted as FT_ indicates).
1914 proto_tree_add_bits_ret_val()
1915 -----------------------------
1916 Works in the same way but also returns the value of the read bits.
1918 proto_tree_add_bitmask() and proto_tree_add_bitmask_text()
1919 ----------------------------------------------------------
1920 This function provides an easy to use and convenient helper function
1921 to manage many types of common bitmasks that occur in protocols.
1923 This function will dissect a 1/2/3/4 byte large bitmask into its individual
1925 header is an integer type and must be of type FT_[U]INT{8|16|24|32} and
1926 represents the entire width of the bitmask.
1928 'header' and 'ett' are the hf fields and ett field respectively to create an
1929 expansion that covers the 1-4 bytes of the bitmask.
1931 'fields' is a NULL terminated array of pointers to hf fields representing
1932 the individual subfields of the bitmask. These fields must either be integers
1933 of the same byte width as 'header' or of the type FT_BOOLEAN.
1934 Each of the entries in 'fields' will be dissected as an item under the
1935 'header' expansion and also IF the field is a boolean and IF it is set to 1,
1936 then the name of that boolean field will be printed on the 'header' expansion
1937 line. For integer type subfields that have a value_string defined, the
1938 matched string from that value_string will be printed on the expansion line
1941 Example: (from the SCSI dissector)
1942 static int hf_scsi_inq_peripheral = -1;
1943 static int hf_scsi_inq_qualifier = -1;
1944 static int hf_scsi_inq_devtype = -1;
1946 static gint ett_scsi_inq_peripheral = -1;
1948 static const int *peripheal_fields[] = {
1949 &hf_scsi_inq_qualifier,
1950 &hf_scsi_inq_devtype,
1954 /* Qualifier and DeviceType */
1955 proto_tree_add_bitmask(tree, tvb, offset, hf_scsi_inq_peripheral,
1956 ett_scsi_inq_peripheral, peripheal_fields, FALSE);
1959 { &hf_scsi_inq_peripheral,
1960 {"Peripheral", "scsi.inquiry.preipheral", FT_UINT8, BASE_HEX,
1961 NULL, 0, NULL, HFILL}},
1962 { &hf_scsi_inq_qualifier,
1963 {"Qualifier", "scsi.inquiry.qualifier", FT_UINT8, BASE_HEX,
1964 VALS (scsi_qualifier_val), 0xE0, NULL, HFILL}},
1965 { &hf_scsi_inq_devtype,
1966 {"Device Type", "scsi.inquiry.devtype", FT_UINT8, BASE_HEX,
1967 VALS (scsi_devtype_val), SCSI_DEV_BITS, NULL, HFILL}},
1970 Which provides very pretty dissection of this one byte bitmask.
1972 Peripheral: 0x05, Qualifier: Device type is connected to logical unit, Device Type: CD-ROM
1973 000. .... = Qualifier: Device type is connected to logical unit (0x00)
1974 ...0 0101 = Device Type: CD-ROM (0x05)
1976 The proto_tree_add_bitmask_text() function is an extended version of
1977 the proto_tree_add_bitmask() function. In addition, it allows to:
1978 - Provide a leading text (e.g. "Flags: ") that will appear before
1979 the comma-separated list of field values
1980 - Provide a fallback text (e.g. "None") that will be appended if
1981 no fields warranted a change to the top-level title.
1982 - Using flags, specify which fields will affect the top-level title.
1984 There are the following flags defined:
1986 BMT_NO_APPEND - the title is taken "as-is" from the 'name' argument.
1987 BMT_NO_INT - only boolean flags are added to the title.
1988 BMT_NO_FALSE - boolean flags are only added to the title if they are set.
1989 BMT_NO_TFS - only add flag name to the title, do not use true_false_string
1991 The proto_tree_add_bitmask() behavior can be obtained by providing
1992 both 'name' and 'fallback' arguments as NULL, and a flags of
1993 (BMT_NO_FALSE|BMT_NO_TFS).
1995 PROTO_ITEM_SET_GENERATED()
1996 --------------------------
1997 PROTO_ITEM_SET_GENERATED is used to mark fields as not being read from the
1998 captured data directly, but inferred from one or more values.
2000 One of the primary uses of this is the presentation of verification of
2001 checksums. Every IP packet has a checksum line, which can present the result
2002 of the checksum verification, if enabled in the preferences. The result is
2003 presented as a subtree, where the result is enclosed in square brackets
2004 indicating a generated field.
2006 Header checksum: 0x3d42 [correct]
2010 PROTO_ITEM_SET_HIDDEN()
2011 -----------------------
2012 PROTO_ITEM_SET_HIDDEN is used to hide fields, which have already been added
2013 to the tree, from being visible in the displayed tree.
2015 NOTE that creating hidden fields is actually quite a bad idea from a UI design
2016 perspective because the user (someone who did not write nor has ever seen the
2017 code) has no way of knowing that hidden fields are there to be filtered on
2018 thus defeating the whole purpose of putting them there. A Better Way might
2019 be to add the fields (that might otherwise be hidden) to a subtree where they
2020 won't be seen unless the user opens the subtree--but they can be found if the
2023 One use for hidden fields (which would be better implemented using visible
2024 fields in a subtree) follows: The caller may want a value to be
2025 included in a tree so that the packet can be filtered on this field, but
2026 the representation of that field in the tree is not appropriate. An
2027 example is the token-ring routing information field (RIF). The best way
2028 to show the RIF in a GUI is by a sequence of ring and bridge numbers.
2029 Rings are 3-digit hex numbers, and bridges are single hex digits:
2031 RIF: 001-A-013-9-C0F-B-555
2033 In the case of RIF, the programmer should use a field with no value and
2034 use proto_tree_add_none_format() to build the above representation. The
2035 programmer can then add the ring and bridge values, one-by-one, with
2036 proto_tree_add_item() and hide them with PROTO_ITEM_SET_HIDDEN() so that the
2037 user can then filter on or search for a particular ring or bridge. Here's a
2038 skeleton of how the programmer might code this.
2041 rif = create_rif_string(...);
2043 proto_tree_add_none_format(tree, hf_tr_rif_label, ..., "RIF: %s", rif);
2045 for(i = 0; i < num_rings; i++) {
2048 pi = proto_tree_add_item(tree, hf_tr_rif_ring, ...,
2050 PROTO_ITEM_SET_HIDDEN(pi);
2052 for(i = 0; i < num_rings - 1; i++) {
2055 pi = proto_tree_add_item(tree, hf_tr_rif_bridge, ...,
2057 PROTO_ITEM_SET_HIDDEN(pi);
2060 The logical tree has these items:
2062 hf_tr_rif_label, text="RIF: 001-A-013-9-C0F-B-555", value = NONE
2063 hf_tr_rif_ring, hidden, value=0x001
2064 hf_tr_rif_bridge, hidden, value=0xA
2065 hf_tr_rif_ring, hidden, value=0x013
2066 hf_tr_rif_bridge, hidden, value=0x9
2067 hf_tr_rif_ring, hidden, value=0xC0F
2068 hf_tr_rif_bridge, hidden, value=0xB
2069 hf_tr_rif_ring, hidden, value=0x555
2071 GUI or print code will not display the hidden fields, but a display
2072 filter or "packet grep" routine will still see the values. The possible
2073 filter is then possible:
2075 tr.rif_ring eq 0x013
2079 PROTO_ITEM_SET_URL is used to mark fields as containing a URL. This can only
2080 be done with fields of type FT_STRING(Z). If these fields are presented they
2081 are underlined, as could be done in a browser. These fields are sensitive to
2082 clicks as well, launching the configured browser with this URL as parameter.
2084 1.7 Utility routines.
2086 1.7.1 match_strval, match_strval_ext, val_to_str and val_to_str_ext.
2088 A dissector may need to convert a value to a string, using a
2089 'value_string' structure, by hand, rather than by declaring a field with
2090 an associated 'value_string' structure; this might be used, for example,
2091 to generate a COL_INFO line for a frame.
2093 'match_strval()' will do that:
2096 match_strval(guint32 val, const value_string *vs)
2098 It will look up the value 'val' in the 'value_string' table pointed to
2099 by 'vs', and return either the corresponding string, or NULL if the
2100 value could not be found in the table. Note that, unless 'val' is
2101 guaranteed to be a value in the 'value_string' table ("guaranteed" as in
2102 "the code has already checked that it's one of those values" or "the
2103 table handles all possible values of the size of 'val'", not "the
2104 protocol spec says it has to be" - protocol specs do not prevent invalid
2105 packets from being put onto a network or into a purported packet capture
2106 file), you must check whether 'match_strval()' returns NULL, and arrange
2107 that its return value not be dereferenced if it's NULL. 'val_to_str()'
2108 can be used to generate a string for values not found in the table:
2111 val_to_str(guint32 val, const value_string *vs, const char *fmt)
2113 If the value 'val' is found in the 'value_string' table pointed to by
2114 'vs', 'val_to_str' will return the corresponding string; otherwise, it
2115 will use 'fmt' as an 'sprintf'-style format, with 'val' as an argument,
2116 to generate a string, and will return a pointer to that string.
2117 You can use it in a call to generate a COL_INFO line for a frame such as
2119 col_add_fstr(COL_INFO, ", %s", val_to_str(val, table, "Unknown %d"));
2121 The match_strval_ext and val_to_str_ext functions are "extended" versions
2122 of match_strval and val_to_str. They should be used for large value-string
2123 arrays which contain many entries. They implement value to string conversions
2124 which will do either a direct access or a binary search of the
2125 value string array if possible. See "Extended Value Strings" under
2126 section 1.6 "Constructing the protocol tree" for more information.
2128 See epan/value_string.h for detailed information on the various value_string
2132 1.7.2 match_strrval and rval_to_str.
2134 A dissector may need to convert a range of values to a string, using a
2135 'range_string' structure.
2137 'match_strrval()' will do that:
2140 match_strrval(guint32 val, const range_string *rs)
2142 It will look up the value 'val' in the 'range_string' table pointed to
2143 by 'rs', and return either the corresponding string, or NULL if the
2144 value could not be found in the table. Please note that its base
2145 behavior is inherited from match_strval().
2147 'rval_to_str()' can be used to generate a string for values not found in
2151 rval_to_str(guint32 val, const range_string *rs, const char *fmt)
2153 If the value 'val' is found in the 'range_string' table pointed to by
2154 'rs', 'rval_to_str' will return the corresponding string; otherwise, it
2155 will use 'fmt' as an 'sprintf'-style format, with 'val' as an argument,
2156 to generate a string, and will return a pointer to that string. Please
2157 note that its base behavior is inherited from match_strval().
2159 1.8 Calling Other Dissectors.
2161 As each dissector completes its portion of the protocol analysis, it
2162 is expected to create a new tvbuff of type TVBUFF_SUBSET which
2163 contains the payload portion of the protocol (that is, the bytes
2164 that are relevant to the next dissector).
2166 The syntax for creating a new TVBUFF_SUBSET is:
2168 next_tvb = tvb_new_subset(tvb, offset, length, reported_length)
2171 tvb is the tvbuff that the dissector has been working on. It
2172 can be a tvbuff of any type.
2174 next_tvb is the new TVBUFF_SUBSET.
2176 offset is the byte offset of 'tvb' at which the new tvbuff
2177 should start. The first byte is the 0th byte.
2179 length is the number of bytes in the new TVBUFF_SUBSET. A length
2180 argument of -1 says to use as many bytes as are available in
2183 reported_length is the number of bytes that the current protocol
2184 says should be in the payload. A reported_length of -1 says that
2185 the protocol doesn't say anything about the size of its payload.
2188 An example from packet-ipx.c -
2191 dissect_ipx(tvbuff_t *tvb, packet_info *pinfo, proto_tree *tree)
2194 int reported_length, available_length;
2197 /* Make the next tvbuff */
2199 /* IPX does have a length value in the header, so calculate report_length */
2200 Set this to -1 if there isn't any length information in the protocol
2202 reported_length = ipx_length - IPX_HEADER_LEN;
2204 /* Calculate the available data in the packet,
2205 set this to -1 to use all the data in the tv_buffer
2207 available_length = tvb_length(tvb) - IPX_HEADER_LEN;
2209 /* Create the tvbuffer for the next dissector */
2210 next_tvb = tvb_new_subset(tvb, IPX_HEADER_LEN,
2211 MIN(available_length, reported_length),
2214 /* call the next dissector */
2215 dissector_next( next_tvb, pinfo, tree);
2218 1.9 Editing Makefile.common and CMakeLists.txt to add your dissector.
2220 To arrange that your dissector will be built as part of Wireshark, you
2221 must add the name of the source file for your dissector to the
2222 'DISSECTOR_SRC' macro in the 'Makefile.common' file in the 'epan/dissectors'
2223 directory. (Note that this is for modern versions of UNIX, so there
2224 is no 14-character limitation on file names, and for modern versions of
2225 Windows, so there is no 8.3-character limitation on file names.)
2227 If your dissector also has its own header file or files, you must add
2228 them to the 'DISSECTOR_INCLUDES' macro in the 'Makefile.common' file in
2229 the 'epan/dissectors' directory, so that it's included when release source
2230 tarballs are built (otherwise, the source in the release tarballs won't
2233 In addition to the above, you should add your dissector source file name
2234 to the DISSECTOR_SRC section of epan/CMakeLists.txt
2237 1.10 Using the SVN source code tree.
2239 See <http://www.wireshark.org/develop.html>
2241 1.11 Submitting code for your new dissector.
2243 - VERIFY that your dissector code does not use prohibited or deprecated APIs
2245 perl <wireshark_root>/tools/checkAPIs.pl <source-filename(s)>
2247 - TEST YOUR DISSECTOR BEFORE SUBMITTING IT.
2248 Use fuzz-test.sh and/or randpkt against your dissector. These are
2249 described at <http://wiki.wireshark.org/FuzzTesting>.
2251 - Subscribe to <mailto:wireshark-dev[AT]wireshark.org> by sending an email to
2252 <mailto:wireshark-dev-request[AT]wireshark.org?body="help"> or visiting
2253 <http://www.wireshark.org/lists/>.
2255 - 'svn add' all the files of your new dissector.
2257 - 'svn diff' the workspace and save the result to a file.
2259 - Edit the diff file - remove any changes unrelated to your new dissector,
2260 e.g. changes in config.nmake
2262 - Submit a bug report to the Wireshark bug database, found at
2263 <http://bugs.wireshark.org>, qualified as an enhancement and attach your
2264 diff file there. Set the review request flag to '?' so it will pop up in
2265 the patch review list.
2267 - Create a Wiki page on the protocol at <http://wiki.wireshark.org>.
2268 A template is provided so it is easy to setup in a consistent style.
2269 See: <http://wiki.wireshark.org/HowToEdit>
2270 and <http://wiki.wireshark.org/ProtocolReference>
2272 - If possible, add sample capture files to the sample captures page at
2273 <http://wiki.wireshark.org/SampleCaptures>. These files are used by
2274 the automated build system for fuzz testing.
2276 - If you find that you are contributing a lot to wireshark on an ongoing
2277 basis you can request to become a committer which will allow you to
2278 commit files to subversion directly.
2280 2. Advanced dissector topics.
2284 Some of the advanced features are being worked on constantly. When using them
2285 it is wise to check the relevant header and source files for additional details.
2287 2.2 Following "conversations".
2289 In wireshark a conversation is defined as a series of data packets between two
2290 address:port combinations. A conversation is not sensitive to the direction of
2291 the packet. The same conversation will be returned for a packet bound from
2292 ServerA:1000 to ClientA:2000 and the packet from ClientA:2000 to ServerA:1000.
2294 2.2.1 Conversation Routines
2296 There are six routines that you will use to work with a conversation:
2297 conversation_new, find_conversation, conversation_add_proto_data,
2298 conversation_get_proto_data, conversation_delete_proto_data,
2299 and conversation_set_dissector.
2302 2.2.1.1 The conversation_init function.
2304 This is an internal routine for the conversation code. As such you
2305 will not have to call this routine. Just be aware that this routine is
2306 called at the start of each capture and before the packets are filtered
2307 with a display filter. The routine will destroy all stored
2308 conversations. This routine does NOT clean up any data pointers that are
2309 passed in the conversation_add_proto_data 'data' variable. You are
2310 responsible for this clean up if you pass a malloc'ed pointer
2313 See item 2.2.1.5 for more information about use of the 'data' pointer.
2316 2.2.1.2 The conversation_new function.
2318 This routine will create a new conversation based upon two address/port
2319 pairs. If you want to associate with the conversation a pointer to a
2320 private data structure you must use the conversation_add_proto_data
2321 function. The ptype variable is used to differentiate between
2322 conversations over different protocols, i.e. TCP and UDP. The options
2323 variable is used to define a conversation that will accept any destination
2324 address and/or port. Set options = 0 if the destination port and address
2325 are know when conversation_new is called. See section 2.4 for more
2326 information on usage of the options parameter.
2328 The conversation_new prototype:
2329 conversation_t *conversation_new(guint32 setup_frame, address *addr1,
2330 address *addr2, port_type ptype, guint32 port1, guint32 port2,
2334 guint32 setup_frame = The lowest numbered frame for this conversation
2335 address* addr1 = first data packet address
2336 address* addr2 = second data packet address
2337 port_type ptype = port type, this is defined in packet.h
2338 guint32 port1 = first data packet port
2339 guint32 port2 = second data packet port
2340 guint options = conversation options, NO_ADDR2 and/or NO_PORT2
2342 setup_frame indicates the first frame for this conversation, and is used to
2343 distinguish multiple conversations with the same addr1/port1 and addr2/port2
2344 pair that occur within the same capture session.
2346 "addr1" and "port1" are the first address/port pair; "addr2" and "port2"
2347 are the second address/port pair. A conversation doesn't have source
2348 and destination address/port pairs - packets in a conversation go in
2349 both directions - so "addr1"/"port1" may be the source or destination
2350 address/port pair; "addr2"/"port2" would be the other pair.
2352 If NO_ADDR2 is specified, the conversation is set up so that a
2353 conversation lookup will match only the "addr1" address; if NO_PORT2 is
2354 specified, the conversation is set up so that a conversation lookup will
2355 match only the "port1" port; if both are specified, i.e.
2356 NO_ADDR2|NO_PORT2, the conversation is set up so that the lookup will
2357 match only the "addr1"/"port1" address/port pair. This can be used if a
2358 packet indicates that, later in the capture, a conversation will be
2359 created using certain addresses and ports, in the case where the packet
2360 doesn't specify the addresses and ports of both sides.
2362 2.2.1.3 The find_conversation function.
2364 Call this routine to look up a conversation. If no conversation is found,
2365 the routine will return a NULL value.
2367 The find_conversation prototype:
2369 conversation_t *find_conversation(guint32 frame_num, address *addr_a,
2370 address *addr_b, port_type ptype, guint32 port_a, guint32 port_b,
2374 guint32 frame_num = a frame number to match
2375 address* addr_a = first address
2376 address* addr_b = second address
2377 port_type ptype = port type
2378 guint32 port_a = first data packet port
2379 guint32 port_b = second data packet port
2380 guint options = conversation options, NO_ADDR_B and/or NO_PORT_B
2382 frame_num is a frame number to match. The conversation returned is where
2383 (frame_num >= conversation->setup_frame
2384 && frame_num < conversation->next->setup_frame)
2385 Suppose there are a total of 3 conversations (A, B, and C) that match
2386 addr_a/port_a and addr_b/port_b, where the setup_frame used in
2387 conversation_new() for A, B and C are 10, 50, and 100 respectively. The
2388 frame_num passed in find_conversation is compared to the setup_frame of each
2389 conversation. So if (frame_num >= 10 && frame_num < 50), conversation A is
2390 returned. If (frame_num >= 50 && frame_num < 100), conversation B is returned.
2391 If (frame_num >= 100) conversation C is returned.
2393 "addr_a" and "port_a" are the first address/port pair; "addr_b" and
2394 "port_b" are the second address/port pair. Again, as a conversation
2395 doesn't have source and destination address/port pairs, so
2396 "addr_a"/"port_a" may be the source or destination address/port pair;
2397 "addr_b"/"port_b" would be the other pair. The search will match the
2398 "a" address/port pair against both the "1" and "2" address/port pairs,
2399 and match the "b" address/port pair against both the "2" and "1"
2400 address/port pairs; you don't have to worry about which side the "a" or
2401 "b" pairs correspond to.
2403 If the NO_ADDR_B flag was specified to "find_conversation()", the
2404 "addr_b" address will be treated as matching any "wildcarded" address;
2405 if the NO_PORT_B flag was specified, the "port_b" port will be treated
2406 as matching any "wildcarded" port. If both flags are specified, i.e.
2407 NO_ADDR_B|NO_PORT_B, the "addr_b" address will be treated as matching
2408 any "wildcarded" address and the "port_b" port will be treated as
2409 matching any "wildcarded" port.
2412 2.2.1.4 The find_or_create_conversation function.
2414 This convenience function will create find an existing conversation (by calling
2415 find_conversation()) and, if a conversation does not already exist, create a
2416 new conversation by calling conversation_new().
2418 The find_or_create_conversation prototype:
2420 extern conversation_t *find_or_create_conversation(packet_info *pinfo);
2423 packet_info *pinfo = the packet_info structure
2425 The frame number and the addresses necessary for find_conversation() and
2426 conversation_new() are taken from the pinfo structure (as is commonly done)
2427 and no 'options' are used.
2430 2.2.1.5 The conversation_add_proto_data function.
2432 Once you have created a conversation with conversation_new, you can
2433 associate data with it using this function.
2435 The conversation_add_proto_data prototype:
2437 void conversation_add_proto_data(conversation_t *conv, int proto,
2441 conversation_t *conv = the conversation in question
2442 int proto = registered protocol number
2443 void *data = dissector data structure
2445 "conversation" is the value returned by conversation_new. "proto" is a
2446 unique protocol number created with proto_register_protocol. Protocols
2447 are typically registered in the proto_register_XXXX section of your
2448 dissector. "data" is a pointer to the data you wish to associate with the
2449 conversation. "data" usually points to "se_alloc'd" memory; the
2450 memory will be automatically freed each time a new dissection begins
2451 and thus need not be managed (freed) by the dissector.
2452 Using the protocol number allows several dissectors to
2453 associate data with a given conversation.
2456 2.2.1.6 The conversation_get_proto_data function.
2458 After you have located a conversation with find_conversation, you can use
2459 this function to retrieve any data associated with it.
2461 The conversation_get_proto_data prototype:
2463 void *conversation_get_proto_data(conversation_t *conv, int proto);
2466 conversation_t *conv = the conversation in question
2467 int proto = registered protocol number
2469 "conversation" is the conversation created with conversation_new. "proto"
2470 is a unique protocol number created with proto_register_protocol,
2471 typically in the proto_register_XXXX portion of a dissector. The function
2472 returns a pointer to the data requested, or NULL if no data was found.
2475 2.2.1.7 The conversation_delete_proto_data function.
2477 After you are finished with a conversation, you can remove your association
2478 with this function. Please note that ONLY the conversation entry is
2479 removed. If you have allocated any memory for your data (other than with se_alloc),
2480 you must free it as well.
2482 The conversation_delete_proto_data prototype:
2484 void conversation_delete_proto_data(conversation_t *conv, int proto);
2487 conversation_t *conv = the conversation in question
2488 int proto = registered protocol number
2490 "conversation" is the conversation created with conversation_new. "proto"
2491 is a unique protocol number created with proto_register_protocol,
2492 typically in the proto_register_XXXX portion of a dissector.
2494 2.2.1.8 The conversation_set_dissector function
2496 This function sets the protocol dissector to be invoked whenever
2497 conversation parameters (addresses, port_types, ports, etc) are matched
2498 during the dissection of a packet.
2500 The conversation_set_dissector prototype:
2502 void conversation_set_dissector(conversation_t *conversation, const dissector_handle_t handle);
2505 conversation_t *conv = the conversation in question
2506 const dissector_handle_t handle = the dissector handle.
2509 2.2.2 Using timestamps relative to the conversation
2511 There is a framework to calculate timestamps relative to the start of the
2512 conversation. First of all the timestamp of the first packet that has been
2513 seen in the conversation must be kept in the protocol data to be able
2514 to calculate the timestamp of the current packet relative to the start
2515 of the conversation. The timestamp of the last packet that was seen in the
2516 conversation should also be kept in the protocol data. This way the
2517 delta time between the current packet and the previous packet in the
2518 conversation can be calculated.
2520 So add the following items to the struct that is used for the protocol data:
2525 The ts_prev value should only be set during the first run through the
2526 packets (ie pinfo->fd->flags.visited is false).
2528 Next step is to use the per-packet information (described in section 2.5)
2529 to keep the calculated delta timestamp, as it can only be calculated
2530 on the first run through the packets. This is because a packet can be
2531 selected in random order once the whole file has been read.
2533 After calculating the conversation timestamps, it is time to put them in
2534 the appropriate columns with the function 'col_set_time' (described in
2535 section 1.5.9). There are two columns for conversation timestamps:
2537 COL_REL_CONV_TIME, /* Relative time to beginning of conversation */
2538 COL_DELTA_CONV_TIME,/* Delta time to last frame in conversation */
2540 Last but not least, there MUST be a preference in each dissector that
2541 uses conversation timestamps that makes it possible to enable and
2542 disable the calculation of conversation timestamps. The main argument
2543 for this is that a higher level conversation is able to overwrite
2544 the values of lowel level conversations in these two columns. Being
2545 able to actively select which protocols may overwrite the conversation
2546 timestamp columns gives the user the power to control these columns.
2547 (A second reason is that conversation timestamps use the per-packet
2548 data structure which uses additional memory, which should be avoided
2549 if these timestamps are not needed)
2551 Have a look at the differences to packet-tcp.[ch] in SVN 22966 and
2552 SVN 23058 to see the implementation of conversation timestamps for
2556 2.2.3 The example conversation code using se_alloc'd memory.
2558 For a conversation between two IP addresses and ports you can use this as an
2559 example. This example uses se_alloc() to allocate memory and stores the data
2560 pointer in the conversation 'data' variable.
2562 /************************ Global values ************************/
2564 /* define your structure here */
2569 /* Registered protocol number */
2570 static int my_proto = -1;
2572 /********************* in the dissector routine *********************/
2574 /* the local variables in the dissector */
2576 conversation_t *conversation;
2577 my_entry_t *data_ptr;
2580 /* look up the conversation */
2582 conversation = find_conversation(pinfo->fd->num, &pinfo->src, &pinfo->dst,
2583 pinfo->ptype, pinfo->srcport, pinfo->destport, 0);
2585 /* if conversation found get the data pointer that you stored */
2587 data_ptr = (my_entry_t*)conversation_get_proto_data(conversation, my_proto);
2590 /* new conversation create local data structure */
2592 data_ptr = se_alloc(sizeof(my_entry_t));
2594 /*** add your code here to setup the new data structure ***/
2596 /* create the conversation with your data pointer */
2598 conversation = conversation_new(pinfo->fd->num, &pinfo->src, &pinfo->dst, pinfo->ptype,
2599 pinfo->srcport, pinfo->destport, 0);
2600 conversation_add_proto_data(conversation, my_proto, (void *)data_ptr);
2603 /* at this point the conversation data is ready */
2605 /***************** in the protocol register routine *****************/
2607 my_proto = proto_register_protocol("My Protocol", "My Protocol", "my_proto");
2610 2.2.4 An example conversation code that starts at a specific frame number.
2612 Sometimes a dissector has determined that a new conversation is needed that
2613 starts at a specific frame number, when a capture session encompasses multiple
2614 conversation that reuse the same src/dest ip/port pairs. You can use the
2615 conversation->setup_frame returned by find_conversation with
2616 pinfo->fd->num to determine whether or not there already exists a conversation
2617 that starts at the specific frame number.
2619 /* in the dissector routine */
2621 conversation = find_conversation(pinfo->fd->num, &pinfo->src, &pinfo->dst,
2622 pinfo->ptype, pinfo->srcport, pinfo->destport, 0);
2623 if (conversation == NULL || (conversation->setup_frame != pinfo->fd->num)) {
2624 /* It's not part of any conversation or the returned
2625 * conversation->setup_frame doesn't match the current frame
2628 conversation = conversation_new(pinfo->fd->num, &pinfo->src,
2629 &pinfo->dst, pinfo->ptype, pinfo->srcport, pinfo->destport,
2634 2.2.5 The example conversation code using conversation index field.
2636 Sometimes the conversation isn't enough to define a unique data storage
2637 value for the network traffic. For example if you are storing information
2638 about requests carried in a conversation, the request may have an
2639 identifier that is used to define the request. In this case the
2640 conversation and the identifier are required to find the data storage
2641 pointer. You can use the conversation data structure index value to
2642 uniquely define the conversation.
2644 See packet-afs.c for an example of how to use the conversation index. In
2645 this dissector multiple requests are sent in the same conversation. To store
2646 information for each request the dissector has an internal hash table based
2647 upon the conversation index and values inside the request packets.
2650 /* in the dissector routine */
2652 /* to find a request value, first lookup conversation to get index */
2653 /* then used the conversation index, and request data to find data */
2654 /* in the local hash table */
2656 conversation = find_or_create_conversation(pinfo);
2658 request_key.conversation = conversation->index;
2659 request_key.service = pntohs(&rxh->serviceId);
2660 request_key.callnumber = pntohl(&rxh->callNumber);
2662 request_val = (struct afs_request_val *)g_hash_table_lookup(
2663 afs_request_hash, &request_key);
2665 /* only allocate a new hash element when it's a request */
2667 if (!request_val && !reply)
2669 new_request_key = se_alloc(sizeof(struct afs_request_key));
2670 *new_request_key = request_key;
2672 request_val = se_alloc(sizeof(struct afs_request_val));
2673 request_val -> opcode = pntohl(&afsh->opcode);
2674 opcode = request_val->opcode;
2676 g_hash_table_insert(afs_request_hash, new_request_key,
2682 2.3 Dynamic conversation dissector registration.
2685 NOTE: This sections assumes that all information is available to
2686 create a complete conversation, source port/address and
2687 destination port/address. If either the destination port or
2688 address is know, see section 2.4 Dynamic server port dissector
2691 For protocols that negotiate a secondary port connection, for example
2692 packet-msproxy.c, a conversation can install a dissector to handle
2693 the secondary protocol dissection. After the conversation is created
2694 for the negotiated ports use the conversation_set_dissector to define
2695 the dissection routine.
2696 Before we create these conversations or assign a dissector to them we should
2697 first check that the conversation does not already exist and if it exists
2698 whether it is registered to our protocol or not.
2699 We should do this because it is uncommon but it does happen that multiple
2700 different protocols can use the same socketpair during different stages of
2701 an application cycle. By keeping track of the frame number a conversation
2702 was started in wireshark can still tell these different protocols apart.
2704 The second argument to conversation_set_dissector is a dissector handle,
2705 which is created with a call to create_dissector_handle or
2708 create_dissector_handle takes as arguments a pointer to the dissector
2709 function and a protocol ID as returned by proto_register_protocol;
2710 register_dissector takes as arguments a string giving a name for the
2711 dissector, a pointer to the dissector function, and a protocol ID.
2713 The protocol ID is the ID for the protocol dissected by the function.
2714 The function will not be called if the protocol has been disabled by the
2715 user; instead, the data for the protocol will be dissected as raw data.
2719 /* the handle for the dynamic dissector *
2720 static dissector_handle_t sub_dissector_handle;
2722 /* prototype for the dynamic dissector */
2723 static void sub_dissector(tvbuff_t *tvb, packet_info *pinfo,
2726 /* in the main protocol dissector, where the next dissector is setup */
2728 /* if conversation has a data field, create it and load structure */
2730 /* First check if a conversation already exists for this
2733 conversation = find_conversation(pinfo->fd->num,
2734 &pinfo->src, &pinfo->dst, protocol,
2735 src_port, dst_port, 0);
2737 /* If there is no such conversation, or if there is one but for
2738 someone else's protocol then we just create a new conversation
2739 and assign our protocol to it.
2741 if ( (conversation == NULL) ||
2742 (conversation->dissector_handle != sub_dissector_handle) ) {
2743 new_conv_info = se_alloc(sizeof(struct _new_conv_info));
2744 new_conv_info->data1 = value1;
2746 /* create the conversation for the dynamic port */
2747 conversation = conversation_new(pinfo->fd->num,
2748 &pinfo->src, &pinfo->dst, protocol,
2749 src_port, dst_port, new_conv_info, 0);
2751 /* set the dissector for the new conversation */
2752 conversation_set_dissector(conversation, sub_dissector_handle);
2757 proto_register_PROTOABBREV(void)
2761 sub_dissector_handle = create_dissector_handle(sub_dissector,
2767 2.4 Dynamic server port dissector registration.
2769 NOTE: While this example used both NO_ADDR2 and NO_PORT2 to create a
2770 conversation with only one port and address set, this isn't a
2771 requirement. Either the second port or the second address can be set
2772 when the conversation is created.
2774 For protocols that define a server address and port for a secondary
2775 protocol, a conversation can be used to link a protocol dissector to
2776 the server port and address. The key is to create the new
2777 conversation with the second address and port set to the "accept
2780 Some server applications can use the same port for different protocols during
2781 different stages of a transaction. For example it might initially use SNMP
2782 to perform some discovery and later switch to use TFTP using the same port.
2783 In order to handle this properly we must first check whether such a
2784 conversation already exists or not and if it exists we also check whether the
2785 registered dissector_handle for that conversation is "our" dissector or not.
2786 If not we create a new conversation on top of the previous one and set this new
2787 conversation to use our protocol.
2788 Since wireshark keeps track of the frame number where a conversation started
2789 wireshark will still be able to keep the packets apart even though they do use
2790 the same socketpair.
2791 (See packet-tftp.c and packet-snmp.c for examples of this)
2793 There are two support routines that will allow the second port and/or
2794 address to be set later.
2796 conversation_set_port2( conversation_t *conv, guint32 port);
2797 conversation_set_addr2( conversation_t *conv, address addr);
2799 These routines will change the second address or port for the
2800 conversation. So, the server port conversation will be converted into a
2801 more complete conversation definition. Don't use these routines if you
2802 want to create a conversation between the server and client and retain the
2803 server port definition, you must create a new conversation.
2808 /* the handle for the dynamic dissector *
2809 static dissector_handle_t sub_dissector_handle;
2813 /* in the main protocol dissector, where the next dissector is setup */
2815 /* if conversation has a data field, create it and load structure */
2817 new_conv_info = se_alloc(sizeof(struct _new_conv_info));
2818 new_conv_info->data1 = value1;
2820 /* create the conversation for the dynamic server address and port */
2821 /* NOTE: The second address and port values don't matter because the */
2822 /* NO_ADDR2 and NO_PORT2 options are set. */
2824 /* First check if a conversation already exists for this
2827 conversation = find_conversation(pinfo->fd->num,
2828 &server_src_addr, 0, protocol,
2829 server_src_port, 0, NO_ADDR2 | NO_PORT_B);
2830 /* If there is no such conversation, or if there is one but for
2831 someone else's protocol then we just create a new conversation
2832 and assign our protocol to it.
2834 if ( (conversation == NULL) ||
2835 (conversation->dissector_handle != sub_dissector_handle) ) {
2836 conversation = conversation_new(pinfo->fd->num,
2837 &server_src_addr, 0, protocol,
2838 server_src_port, 0, new_conv_info, NO_ADDR2 | NO_PORT2);
2840 /* set the dissector for the new conversation */
2841 conversation_set_dissector(conversation, sub_dissector_handle);
2844 2.5 Per-packet information.
2846 Information can be stored for each data packet that is processed by the
2847 dissector. The information is added with the p_add_proto_data function and
2848 retrieved with the p_get_proto_data function. The data pointers passed into
2849 the p_add_proto_data are not managed by the proto_data routines. If you use
2850 malloc or any other dynamic memory allocation scheme, you must release the
2851 data when it isn't required.
2854 p_add_proto_data(frame_data *fd, int proto, void *proto_data)
2856 p_get_proto_data(frame_data *fd, int proto)
2859 fd - The fd pointer in the pinfo structure, pinfo->fd
2860 proto - Protocol id returned by the proto_register_protocol call
2861 during initialization
2862 proto_data - pointer to the dissector data.
2865 2.6 User Preferences.
2867 If the dissector has user options, there is support for adding these preferences
2868 to a configuration dialog.
2870 You must register the module with the preferences routine with -
2872 module_t *prefs_register_protocol(proto_id, void (*apply_cb)(void))
2874 module_t *prefs_register_protocol_subtree(const char *subtree, int id,
2875 void (*apply_cb)(void));
2878 Where: proto_id - the value returned by "proto_register_protocol()" when
2879 the protocol was registered.
2880 apply_cb - Callback routine that is called when preferences are
2881 applied. It may be NULL, which inhibits the callback.
2882 subtree - grouping preferences tree node name (several protocols can
2883 be grouped under one preferences subtree)
2885 Then you can register the fields that can be configured by the user with these
2888 /* Register a preference with an unsigned integral value. */
2889 void prefs_register_uint_preference(module_t *module, const char *name,
2890 const char *title, const char *description, guint base, guint *var);
2892 /* Register a preference with an Boolean value. */
2893 void prefs_register_bool_preference(module_t *module, const char *name,
2894 const char *title, const char *description, gboolean *var);
2896 /* Register a preference with an enumerated value. */
2897 void prefs_register_enum_preference(module_t *module, const char *name,
2898 const char *title, const char *description, gint *var,
2899 const enum_val_t *enumvals, gboolean radio_buttons)
2901 /* Register a preference with a character-string value. */
2902 void prefs_register_string_preference(module_t *module, const char *name,
2903 const char *title, const char *description, char **var)
2905 /* Register a preference with a range of unsigned integers (e.g.,
2908 void prefs_register_range_preference(module_t *module, const char *name,
2909 const char *title, const char *description, range_t *var,
2912 Where: module - Returned by the prefs_register_protocol routine
2913 name - This is appended to the name of the protocol, with a
2914 "." between them, to construct a name that identifies
2915 the field in the preference file; the name itself
2916 should not include the protocol name, as the name in
2917 the preference file will already have it
2918 title - Field title in the preferences dialog
2919 description - Comments added to the preference file above the
2921 var - pointer to the storage location that is updated when the
2922 field is changed in the preference dialog box. Note that
2923 with string preferences the given pointer is overwritten
2924 with a pointer to a new copy of the string during the
2925 preference registration. The passed-in string may be
2926 freed, but you must keep another pointer to the string
2927 in order to free it.
2928 base - Base that the unsigned integer is expected to be in,
2930 enumvals - an array of enum_val_t structures. This must be
2931 NULL-terminated; the members of that structure are:
2933 a short name, to be used with the "-o" flag - it
2934 should not contain spaces or upper-case letters,
2935 so that it's easier to put in a command line;
2937 a description, which is used in the GUI (and
2938 which, for compatibility reasons, is currently
2939 what's written to the preferences file) - it can
2940 contain spaces, capital letters, punctuation,
2943 the numerical value corresponding to that name
2945 radio_buttons - TRUE if the field is to be displayed in the
2946 preferences dialog as a set of radio buttons,
2947 FALSE if it is to be displayed as an option
2949 max_value - The maximum allowed value for a range (0 is the minimum).
2951 An example from packet-beep.c -
2953 proto_beep = proto_register_protocol("Blocks Extensible Exchange Protocol",
2958 /* Register our configuration options for BEEP, particularly our port */
2960 beep_module = prefs_register_protocol(proto_beep, proto_reg_handoff_beep);
2962 prefs_register_uint_preference(beep_module, "tcp.port", "BEEP TCP Port",
2963 "Set the port for BEEP messages (if other"
2964 " than the default of 10288)",
2965 10, &global_beep_tcp_port);
2967 prefs_register_bool_preference(beep_module, "strict_header_terminator",
2968 "BEEP Header Requires CRLF",
2969 "Specifies that BEEP requires CRLF as a "
2970 "terminator, and not just CR or LF",
2971 &global_beep_strict_term);
2973 This will create preferences "beep.tcp.port" and
2974 "beep.strict_header_terminator", the first of which is an unsigned
2975 integer and the second of which is a Boolean.
2977 Note that a warning will pop up if you've saved such preference to the
2978 preference file and you subsequently take the code out. The way to make
2979 a preference obsolete is to register it as such:
2981 /* Register a preference that used to be supported but no longer is. */
2982 void prefs_register_obsolete_preference(module_t *module,
2985 2.7 Reassembly/desegmentation for protocols running atop TCP.
2987 There are two main ways of reassembling a Protocol Data Unit (PDU) which
2988 spans across multiple TCP segments. The first approach is simpler, but
2989 assumes you are running atop of TCP when this occurs (but your dissector
2990 might run atop of UDP, too, for example), and that your PDUs consist of a
2991 fixed amount of data that includes enough information to determine the PDU
2992 length, possibly followed by additional data. The second method is more
2993 generic but requires more code and is less efficient.
2995 2.7.1 Using tcp_dissect_pdus().
2997 For the first method, you register two different dissection methods, one
2998 for the TCP case, and one for the other cases. It is a good idea to
2999 also have a dissect_PROTO_common function which will parse the generic
3000 content that you can find in all PDUs which is called from
3001 dissect_PROTO_tcp when the reassembly is complete and from
3002 dissect_PROTO_udp (or dissect_PROTO_other).
3004 To register the distinct dissector functions, consider the following
3005 example, stolen from packet-dns.c:
3007 dissector_handle_t dns_udp_handle;
3008 dissector_handle_t dns_tcp_handle;
3009 dissector_handle_t mdns_udp_handle;
3011 dns_udp_handle = create_dissector_handle(dissect_dns_udp,
3013 dns_tcp_handle = create_dissector_handle(dissect_dns_tcp,
3015 mdns_udp_handle = create_dissector_handle(dissect_mdns_udp,
3018 dissector_add("udp.port", UDP_PORT_DNS, dns_udp_handle);
3019 dissector_add("tcp.port", TCP_PORT_DNS, dns_tcp_handle);
3020 dissector_add("udp.port", UDP_PORT_MDNS, mdns_udp_handle);
3021 dissector_add("tcp.port", TCP_PORT_MDNS, dns_tcp_handle);
3023 The dissect_dns_udp function does very little work and calls
3024 dissect_dns_common, while dissect_dns_tcp calls tcp_dissect_pdus with a
3025 reference to a callback which will be called with reassembled data:
3028 dissect_dns_tcp(tvbuff_t *tvb, packet_info *pinfo, proto_tree *tree)
3030 tcp_dissect_pdus(tvb, pinfo, tree, dns_desegment, 2,
3031 get_dns_pdu_len, dissect_dns_tcp_pdu);
3034 (The dissect_dns_tcp_pdu function acts similarly to dissect_dns_udp.)
3035 The arguments to tcp_dissect_pdus are:
3037 the tvbuff pointer, packet_info pointer, and proto_tree pointer
3038 passed to the dissector;
3040 a gboolean flag indicating whether desegmentation is enabled for
3043 the number of bytes of PDU data required to determine the length
3046 a routine that takes as arguments a packet_info pointer, a tvbuff
3047 pointer and an offset value representing the offset into the tvbuff
3048 at which a PDU begins and should return - *without* throwing an
3049 exception (it is guaranteed that the number of bytes specified by the
3050 previous argument to tcp_dissect_pdus is available, but more data
3051 might not be available, so don't refer to any data past that) - the
3052 total length of the PDU, in bytes;
3054 a routine that's passed a tvbuff pointer, packet_info pointer,
3055 and proto_tree pointer, with the tvbuff containing a
3056 possibly-reassembled PDU, and that should dissect that PDU.
3058 2.7.2 Modifying the pinfo struct.
3060 The second reassembly mode is preferred when the dissector cannot determine
3061 how many bytes it will need to read in order to determine the size of a PDU.
3062 It may also be useful if your dissector needs to support reassembly from
3063 protocols other than TCP.
3065 Your dissect_PROTO will initially be passed a tvbuff containing the payload of
3066 the first packet. It should dissect as much data as it can, noting that it may
3067 contain more than one complete PDU. If the end of the provided tvbuff coincides
3068 with the end of a PDU then all is well and your dissector can just return as
3069 normal. (If it is a new-style dissector, it should return the number of bytes
3070 successfully processed.)
3072 If the dissector discovers that the end of the tvbuff does /not/ coincide with
3073 the end of a PDU, (ie, there is half of a PDU at the end of the tvbuff), it can
3074 indicate this to the parent dissector, by updating the pinfo struct. The
3075 desegment_offset field is the offset in the tvbuff at which the dissector will
3076 continue processing when next called. The desegment_len field should contain
3077 the estimated number of additional bytes required for completing the PDU. Next
3078 time your dissect_PROTO is called, it will be passed a tvbuff composed of the
3079 end of the data from the previous tvbuff together with desegment_len more bytes.
3081 If the dissector cannot tell how many more bytes it will need, it should set
3082 desegment_len=DESEGMENT_ONE_MORE_SEGMENT; it will then be called again as soon
3083 as any more data becomes available. Dissectors should set the desegment_len to a
3084 reasonable value when possible rather than always setting
3085 DESEGMENT_ONE_MORE_SEGMENT as it will generally be more efficient. Also, you
3086 *must not* set desegment_len=1 in this case, in the hope that you can change
3087 your mind later: once you return a positive value from desegment_len, your PDU
3088 boundary is set in stone.
3090 static hf_register_info hf[] = {
3092 {"C String", "c.string", FT_STRING, BASE_NONE, NULL, 0x0,
3098 * Dissect a buffer containing C strings.
3100 * @param tvb The buffer to dissect.
3101 * @param pinfo Packet Info.
3102 * @param tree The protocol tree.
3104 static void dissect_cstr(tvbuff_t * tvb, packet_info * pinfo, proto_tree * tree)
3107 while(offset < tvb_reported_length(tvb)) {
3108 gint available = tvb_reported_length_remaining(tvb, offset);
3109 gint len = tvb_strnlen(tvb, offset, available);
3112 /* we ran out of data: ask for more */
3113 pinfo->desegment_offset = offset;
3114 pinfo->desegment_len = DESEGMENT_ONE_MORE_SEGMENT;
3118 col_set_str(pinfo->cinfo, COL_INFO, "C String");
3120 len += 1; /* Add one for the '\0' */
3123 proto_tree_add_item(tree, hf_cstring, tvb, offset, len,
3126 offset += (guint)len;
3129 /* if we get here, then the end of the tvb coincided with the end of a
3130 string. Happy days. */
3133 This simple dissector will repeatedly return DESEGMENT_ONE_MORE_SEGMENT
3134 requesting more data until the tvbuff contains a complete C string. The C string
3135 will then be added to the protocol tree. Note that there may be more
3136 than one complete C string in the tvbuff, so the dissection is done in a
3141 The ptvcursor API allows a simpler approach to writing dissectors for
3142 simple protocols. The ptvcursor API works best for protocols whose fields
3143 are static and whose format does not depend on the value of other fields.
3144 However, even if only a portion of your protocol is statically defined,
3145 then that portion could make use of ptvcursors.
3147 The ptvcursor API lets you extract data from a tvbuff, and add it to a
3148 protocol tree in one step. It also keeps track of the position in the
3149 tvbuff so that you can extract data again without having to compute any
3150 offsets --- hence the "cursor" name of the API.
3152 The three steps for a simple protocol are:
3153 1. Create a new ptvcursor with ptvcursor_new()
3154 2. Add fields with multiple calls of ptvcursor_add()
3155 3. Delete the ptvcursor with ptvcursor_free()
3157 ptvcursor offers the possibility to add subtrees in the tree as well. It can be
3158 done in very simple steps :
3159 1. Create a new subtree with ptvcursor_push_subtree(). The old subtree is
3160 pushed in a stack and the new subtree will be used by ptvcursor.
3161 2. Add fields with multiple calls of ptvcursor_add(). The fields will be
3162 added in the new subtree created at the previous step.
3163 3. Pop the previous subtree with ptvcursor_pop_subtree(). The previous
3164 subtree is again used by ptvcursor.
3165 Note that at the end of the parsing of a packet you must have popped each
3166 subtree you pushed. If it's not the case, the dissector will generate an error.
3168 To use the ptvcursor API, include the "ptvcursor.h" file. The PGM dissector
3169 is an example of how to use it. You don't need to look at it as a guide;
3170 instead, the API description here should be good enough.
3172 2.8.1 ptvcursor API.
3175 ptvcursor_new(proto_tree* tree, tvbuff_t* tvb, gint offset)
3176 This creates a new ptvcursor_t object for iterating over a tvbuff.
3177 You must call this and use this ptvcursor_t object so you can use the
3181 ptvcursor_add(ptvcursor_t* ptvc, int hf, gint length, gboolean endianness)
3182 This will extract 'length' bytes from the tvbuff and place it in
3183 the proto_tree as field 'hf', which is a registered header_field. The
3184 pointer to the proto_item that is created is passed back to you. Internally,
3185 the ptvcursor advances its cursor so the next call to ptvcursor_add
3186 starts where this call finished. The 'endianness' parameter matters for
3187 FT_UINT* and FT_INT* fields.
3190 ptvcursor_add_no_advance(ptvcursor_t* ptvc, int hf, gint length, gboolean endianness)
3191 Like ptvcursor_add, but does not advance the internal cursor.
3194 ptvcursor_advance(ptvcursor_t* ptvc, gint length)
3195 Advances the internal cursor without adding anything to the proto_tree.
3198 ptvcursor_free(ptvcursor_t* ptvc)
3199 Frees the memory associated with the ptvcursor. You must call this
3200 after your dissection with the ptvcursor API is completed.
3204 ptvcursor_push_subtree(ptvcursor_t* ptvc, proto_item* it, gint ett_subtree)
3205 Pushes the current subtree in the tree stack of the cursor, creates a new
3206 one and sets this one as the working tree.
3209 ptvcursor_pop_subtree(ptvcursor_t* ptvc);
3210 Pops a subtree in the tree stack of the cursor
3213 ptvcursor_add_with_subtree(ptvcursor_t* ptvc, int hfindex, gint length,
3214 gboolean little_endian, gint ett_subtree);
3215 Adds an item to the tree and creates a subtree.
3216 If the length is unknown, length may be defined as SUBTREE_UNDEFINED_LENGTH.
3217 In this case, at the next pop, the item length will be equal to the advancement
3218 of the cursor since the creation of the subtree.
3221 ptvcursor_add_text_with_subtree(ptvcursor_t* ptvc, gint length,
3222 gint ett_subtree, const char* format, ...);
3223 Add a text node to the tree and create a subtree.
3224 If the length is unknown, length may be defined as SUBTREE_UNDEFINED_LENGTH.
3225 In this case, at the next pop, the item length will be equal to the advancement
3226 of the cursor since the creation of the subtree.
3228 2.8.2 Miscellaneous functions.
3231 ptvcursor_tvbuff(ptvcursor_t* ptvc)
3232 Returns the tvbuff associated with the ptvcursor.
3235 ptvcursor_current_offset(ptvcursor_t* ptvc)
3236 Returns the current offset.
3239 ptvcursor_tree(ptvcursor_t* ptvc)
3240 Returns the proto_tree associated with the ptvcursor.
3243 ptvcursor_set_tree(ptvcursor_t* ptvc, proto_tree *tree)
3244 Sets a new proto_tree for the ptvcursor.
3247 ptvcursor_set_subtree(ptvcursor_t* ptvc, proto_item* it, gint ett_subtree);
3248 Creates a subtree and adds it to the cursor as the working tree but does
3249 not save the old working tree.