1 This file is a HOWTO for Wireshark developers interested in writing or working
2 on Wireshark protocol dissectors. It describes expected code patterns and the
3 use of some of the important functions and variables.
5 This file is compiled to give in depth information on Wireshark.
6 It is by no means all inclusive and complete. Please feel free to send
7 remarks and patches to the developer mailing list.
9 If you haven't read README.developer, read that first!
13 Before starting to develop a new dissector, a "running" Wireshark build
14 environment is required - there's no such thing as a standalone "dissector
17 How to setup such an environment is platform dependent; detailed
18 information about these steps can be found in the "Developer's Guide"
19 (available from: https://www.wireshark.org) and in the INSTALL and
20 README.md files of the sources root dir.
22 0.1. Dissector related README files.
24 You'll find additional dissector related information in the following README
27 - README.heuristic - what are heuristic dissectors and how to write them
28 - README.plugins - how to "pluginize" a dissector
29 - README.request_response_tracking - how to track req./resp. times and such
30 - README.wmem - how to obtain "memory leak free" memory
34 James Coe <jammer[AT]cin.net>
35 Gilbert Ramirez <gram[AT]alumni.rice.edu>
36 Jeff Foster <jfoste[AT]woodward.com>
37 Olivier Abad <oabad[AT]cybercable.fr>
38 Laurent Deniel <laurent.deniel[AT]free.fr>
39 Gerald Combs <gerald[AT]wireshark.org>
40 Guy Harris <guy[AT]alum.mit.edu>
41 Ulf Lamping <ulf.lamping[AT]web.de>
42 Barbu Paul - Gheorghe <barbu.paul.gheorghe[AT]gmail.com>
44 1. Setting up your protocol dissector code.
46 This section provides skeleton code for a protocol dissector. It also explains
47 the basic functions needed to enter values in the traffic summary columns,
48 add to the protocol tree, and work with registered header fields.
52 Wireshark requires certain things when setting up a protocol dissector.
53 We provide basic skeleton code for a dissector that you can copy to a new file
54 and fill in. Your dissector should follow the naming convention of "packet-"
55 followed by the abbreviated name for the protocol. It is recommended that where
56 possible you keep to the IANA abbreviated name for the protocol, if there is
57 one, or a commonly-used abbreviation for the protocol, if any.
59 The skeleton code lives in the file "packet-PROTOABBREV.c" in the same source
60 directory as this README.
62 If instead of using the skeleton you base your dissector on an existing real
63 dissector, please put a little note in the copyright header indicating which
64 dissector you started with.
66 Usually, you will put your newly created dissector file into the directory
67 epan/dissectors/, just like all the other packet-*.c files already in there.
69 Also, please add your dissector file to the corresponding makefiles,
70 described in section "1.8 Editing CMakeLists.txt to add your dissector" below.
72 Dissectors that use the dissector registration API to register with a lower
73 level protocol (this is the vast majority) don't need to define a prototype in
74 their .h file. For other dissectors the main dissector routine should have a
75 prototype in a header file whose name is "packet-", followed by the abbreviated
76 name for the protocol, followed by ".h"; any dissector file that calls your
77 dissector should be changed to include that file.
79 You may not need to include all the headers listed in the skeleton, and you may
80 need to include additional headers.
82 1.2 Explanation of needed substitutions in code skeleton.
84 In the skeleton sample code the following strings should be substituted with
87 YOUR_NAME Your name, of course. You do want credit, don't you?
88 It's the only payment you will receive....
89 YOUR_EMAIL_ADDRESS Keep those cards and letters coming.
90 PROTONAME The name of the protocol; this is displayed in the
91 top-level protocol tree item for that protocol.
92 PROTOSHORTNAME An abbreviated name for the protocol; this is displayed
93 in the "Preferences" dialog box if your dissector has
94 any preferences, in the dialog box of enabled protocols,
95 and in the dialog box for filter fields when constructing
97 PROTOABBREV A name for the protocol for use in filter expressions;
98 it may contain only lower-case letters, digits, and hyphens,
99 underscores, and periods.
100 FIELDNAME The displayed name for the header field.
101 FIELDABBREV The abbreviated name for the header field; it may contain
102 only letters, digits, hyphens, underscores, and periods.
103 FIELDTYPE FT_NONE, FT_BOOLEAN, FT_CHAR, FT_UINT8, FT_UINT16, FT_UINT24,
104 FT_UINT32, FT_UINT40, FT_UINT48, FT_UINT56, FT_UINT64,
105 FT_INT8, FT_INT16, FT_INT24, FT_INT32, FT_INT40, FT_INT48,
106 FT_INT56, FT_INT64, FT_FLOAT, FT_DOUBLE, FT_ABSOLUTE_TIME,
107 FT_RELATIVE_TIME, FT_STRING, FT_STRINGZ, FT_EUI64,
108 FT_UINT_STRING, FT_ETHER, FT_BYTES, FT_UINT_BYTES, FT_IPv4,
109 FT_IPv6, FT_IPXNET, FT_FRAMENUM, FT_PROTOCOL, FT_GUID, FT_OID,
110 FT_REL_OID, FT_AX25, FT_VINES, FT_SYSTEM_ID, FT_FC, FT_FCWWN
111 FIELDDISPLAY --For FT_UINT{8,16,24,32,40,48,56,64} and
112 FT_INT{8,16,24,32,40,48,56,64):
114 BASE_DEC, BASE_HEX, BASE_OCT, BASE_DEC_HEX, BASE_HEX_DEC,
115 BASE_CUSTOM, or BASE_NONE, possibly ORed with
116 BASE_RANGE_STRING, BASE_EXT_STRING, BASE_VAL64_STRING,
117 BASE_ALLOW_ZERO, BASE_UNIT_STRING, BASE_SPECIAL_VALS or
118 BASE_NO_DISPLAY_VALUE
120 BASE_NONE may be used with a non-NULL FIELDCONVERT when the
121 numeric value of the field itself is not of significance to
122 the user (for example, the number is a generated field).
123 When this is the case the numeric value is not shown to the
124 user in the protocol decode nor is it used when preparing
125 filters for the field in question.
127 BASE_NO_DISPLAY_VALUE will just display the field name with
128 no value. It is intended for byte arrays (FT_BYTES) or
129 header fields above a subtree. The value will still be
130 filterable, just not displayed.
134 BASE_PT_UDP, BASE_PT_TCP, BASE_PT_DCCP or BASE_PT_SCTP
141 BASE_HEX, BASE_OCT, BASE_CUSTOM, or BASE_NONE, possibly
142 ORed with BASE_RANGE_STRING, BASE_EXT_STRING or
145 BASE_NONE can be used in the same way as with FT_UINT8.
147 --For FT_ABSOLUTE_TIME:
149 ABSOLUTE_TIME_LOCAL, ABSOLUTE_TIME_UTC, or
150 ABSOLUTE_TIME_DOY_UTC
154 if BITMASK is non-zero:
155 Number of bits in the field containing the FT_BOOLEAN
160 --For FT_STRING, FT_STRINGZ and FT_UINT_STRING:
162 STR_ASCII or STR_UNICODE
166 SEP_DOT, SEP_DASH, SEP_COLON, or SEP_SPACE to provide
167 a separator between bytes.
168 BASE_NONE has no separator between bytes
169 BASE_ALLOW_ZERO displays <none> instead of <MISSING> for zero sized byte array
173 BASE_NETMASK - Used for IPv4 address that should never
174 attempted to be resolved (like netmasks)
178 --For all other types:
181 FIELDCONVERT VALS(x), VALS64(x), RVALS(x), TFS(x), CF_FUNC(x), NULL
182 BITMASK Used to mask a field not 8-bit aligned or with a size other
183 than a multiple of 8 bits
184 FIELDDESCR A brief description of the field, or NULL. [Please do not use ""].
186 If, for example, PROTONAME is "Internet Bogosity Discovery Protocol",
187 PROTOSHORTNAME would be "IBDP", and PROTOABBREV would be "ibdp". Try to
188 conform with IANA names.
190 1.3 The dissector and the data it receives.
195 This is only needed if the dissector doesn't use self-registration to
196 register itself with the lower level dissector, or if the protocol dissector
197 wants/needs to expose code to other subdissectors.
199 The dissector must be declared exactly as follows in the file
200 packet-PROTOABBREV.h:
203 dissect_PROTOABBREV(tvbuff_t *tvb, packet_info *pinfo, proto_tree *tree);
206 1.3.2 Extracting data from packets.
208 NOTE: See the file /epan/tvbuff.h for more details.
210 The "tvb" argument to a dissector points to a buffer containing the raw
211 data to be analyzed by the dissector; for example, for a protocol
212 running atop UDP, it contains the UDP payload (but not the UDP header,
213 or any protocol headers above it). A tvbuffer is an opaque data
214 structure, the internal data structures are hidden and the data must be
215 accessed via the tvbuffer accessors.
219 Bit accessors for a maximum of 8-bits, 16-bits 32-bits and 64-bits:
221 guint8 tvb_get_bits8(tvbuff_t *tvb, gint bit_offset, const gint no_of_bits);
222 guint16 tvb_get_bits16(tvbuff_t *tvb, guint bit_offset, const gint no_of_bits, const guint encoding);
223 guint32 tvb_get_bits32(tvbuff_t *tvb, guint bit_offset, const gint no_of_bits, const guint encoding);
224 guint64 tvb_get_bits64(tvbuff_t *tvb, guint bit_offset, const gint no_of_bits, const guint encoding);
226 Single-byte accessor:
228 guint8 tvb_get_guint8(tvbuff_t *tvb, const gint offset);
230 Network-to-host-order accessors for 16-bit integers (guint16), 24-bit
231 integers, 32-bit integers (guint32), 40-bit integers, 48-bit integers,
232 56-bit integers and 64-bit integers (guint64):
234 guint16 tvb_get_ntohs(tvbuff_t *tvb, const gint offset);
235 guint32 tvb_get_ntoh24(tvbuff_t *tvb, const gint offset);
236 guint32 tvb_get_ntohl(tvbuff_t *tvb, const gint offset);
237 guint64 tvb_get_ntoh40(tvbuff_t *tvb, const gint offset);
238 guint64 tvb_get_ntoh48(tvbuff_t *tvb, const gint offset);
239 guint64 tvb_get_ntoh56(tvbuff_t *tvb, const gint offset);
240 guint64 tvb_get_ntoh64(tvbuff_t *tvb, const gint offset);
242 Network-to-host-order accessors for single-precision and
243 double-precision IEEE floating-point numbers:
245 gfloat tvb_get_ntohieee_float(tvbuff_t *tvb, const gint offset);
246 gdouble tvb_get_ntohieee_double(tvbuff_t *tvb, const gint offset);
248 Little-Endian-to-host-order accessors for 16-bit integers (guint16),
249 24-bit integers, 32-bit integers (guint32), 40-bit integers, 48-bit
250 integers, 56-bit integers, and 64-bit integers (guint64):
252 guint16 tvb_get_letohs(tvbuff_t *tvb, const gint offset);
253 guint32 tvb_get_letoh24(tvbuff_t *tvb, const gint offset);
254 guint32 tvb_get_letohl(tvbuff_t *tvb, const gint offset);
255 guint64 tvb_get_letoh40(tvbuff_t *tvb, const gint offset);
256 guint64 tvb_get_letoh48(tvbuff_t *tvb, const gint offset);
257 guint64 tvb_get_letoh56(tvbuff_t *tvb, const gint offset);
258 guint64 tvb_get_letoh64(tvbuff_t *tvb, const gint offset);
260 Little-Endian-to-host-order accessors for single-precision and
261 double-precision IEEE floating-point numbers:
263 gfloat tvb_get_letohieee_float(tvbuff_t *tvb, const gint offset);
264 gdouble tvb_get_letohieee_double(tvbuff_t *tvb, const gint offset);
266 Encoding-to_host-order accessors for 16-bit integers (guint16),
267 24-bit integers, 32-bit integers (guint32), 40-bit integers, 48-bit
268 integers, 56-bit integers, and 64-bit integers (guint64):
270 guint16 tvb_get_guint16(tvbuff_t *tvb, const gint offset, const guint encoding);
271 guint32 tvb_get_guint24(tvbuff_t *tvb, const gint offset, const guint encoding);
272 guint32 tvb_get_guint32(tvbuff_t *tvb, const gint offset, const guint encoding);
273 guint64 tvb_get_guint40(tvbuff_t *tvb, const gint offset, const guint encoding);
274 gint64 tvb_get_gint40(tvbuff_t *tvb, const gint offset, const guint encoding);
275 guint64 tvb_get_guint48(tvbuff_t *tvb, const gint offset, const guint encoding);
276 gint64 tvb_get_gint48(tvbuff_t *tvb, const gint offset, const guint encoding);
277 guint64 tvb_get_guint56(tvbuff_t *tvb, const gint offset, const guint encoding);
278 gint64 tvb_get_gint56(tvbuff_t *tvb, const gint offset, const guint encoding);
279 guint64 tvb_get_guint64(tvbuff_t *tvb, const gint offset, const guint encoding);
281 "encoding" should be ENC_BIG_ENDIAN for Network-to-host-order and ENC_LITTLE_ENDIAN
282 for Little-Endian-to-host-order.
284 Endian-to-host-order accessors for single-precision and
285 double-precision IEEE floating-point numbers:
287 gfloat tvb_get_ieee_float(tvbuff_t *tvb, const gint offset, const guint encoding);
288 gdouble tvb_get_ieee_double(tvbuff_t *tvb, const gint offset, const guint encoding);
290 Just as above, "encoding" should be ENC_BIG_ENDIAN for Network-to-host-order and
291 ENC_LITTLE_ENDIAN for Little-Endian-to-host-order.
293 Accessors for IPv4 and IPv6 addresses:
295 guint32 tvb_get_ipv4(tvbuff_t *tvb, const gint offset);
296 void tvb_get_ipv6(tvbuff_t *tvb, const gint offset, ws_in6_addr *addr);
298 NOTE: IPv4 addresses are not to be converted to host byte order before
299 being passed to "proto_tree_add_ipv4()". You should use "tvb_get_ipv4()"
300 to fetch them, not "tvb_get_ntohl()" *OR* "tvb_get_letohl()" - don't,
301 for example, try to use "tvb_get_ntohl()", find that it gives you the
302 wrong answer on the PC on which you're doing development, and try
303 "tvb_get_letohl()" instead, as "tvb_get_letohl()" will give the wrong
304 answer on big-endian machines.
306 gchar *tvb_ip_to_str(tvbuff_t *tvb, const gint offset)
307 gchar *tvb_ip6_to_str(tvbuff_t *tvb, const gint offset)
309 Returns a null-terminated buffer containing a string with IPv4 or IPv6 Address
310 from the specified tvbuff, starting at the specified offset.
314 void tvb_get_ntohguid(tvbuff_t *tvb, const gint offset, e_guid_t *guid);
315 void tvb_get_letohguid(tvbuff_t *tvb, const gint offset, e_guid_t *guid);
316 void tvb_get_guid(tvbuff_t *tvb, const gint offset, e_guid_t *guid, const guint encoding);
320 guint8 *tvb_get_string_enc(wmem_allocator_t *scope, tvbuff_t *tvb, const gint offset, const gint length, const guint encoding);
322 Returns a null-terminated buffer allocated from the specified scope, containing
323 data from the specified tvbuff, starting at the specified offset, and containing
324 the specified length worth of characters. Reads data in the specified encoding
325 and produces UTF-8 in the buffer. See below for a list of input encoding values.
327 The buffer is allocated in the given wmem scope (see README.wmem for more
330 guint8 *tvb_get_stringz_enc(wmem_allocator_t *scope, tvbuff_t *tvb, const gint offset, gint *lengthp, const guint encoding);
332 Returns a null-terminated buffer allocated from the specified scope,
333 containing data from the specified tvbuff, starting at the specified
334 offset, and containing all characters from the tvbuff up to and
335 including a terminating null character in the tvbuff. Reads data in the
336 specified encoding and produces UTF-8 in the buffer. See below for a
337 list of input encoding values. "*lengthp" will be set to the length of
338 the string, including the terminating null.
340 The buffer is allocated in the given wmem scope (see README.wmem for more
343 const guint8 *tvb_get_const_stringz(tvbuff_t *tvb, const gint offset, gint *lengthp);
345 Returns a null-terminated const buffer containing data from the
346 specified tvbuff, starting at the specified offset, and containing all
347 bytes from the tvbuff up to and including a terminating null character
348 in the tvbuff. "*lengthp" will be set to the length of the string,
349 including the terminating null.
351 You do not need to free() this buffer; it will happen automatically once
352 the next packet is dissected. This function is slightly more efficient
353 than the others because it does not allocate memory and copy the string,
354 but it does not do any mapping to UTF-8 or checks for valid octet
357 gint tvb_get_nstringz(tvbuff_t *tvb, const gint offset, const guint bufsize, guint8* buffer);
358 gint tvb_get_nstringz0(tvbuff_t *tvb, const gint offset, const guint bufsize, guint8* buffer);
360 Copies bufsize bytes, including the terminating NULL, to buffer. If a NULL
361 terminator is found before reaching bufsize, only the bytes up to and including
362 the NULL are copied. Returns the number of bytes copied (not including
363 terminating NULL), or -1 if the string was truncated in the buffer due to
364 not having reached the terminating NULL. In this case, the resulting
365 buffer is not NULL-terminated.
366 tvb_get_nstringz0() works like tvb_get_nstringz(), but never returns -1 since
367 the string is guaranteed to have a terminating NULL. If the string was truncated
368 when copied into buffer, a NULL is placed at the end of buffer to terminate it.
370 gchar *tvb_get_ts_23_038_7bits_string(wmem_allocator_t *scope, tvbuff_t *tvb,
371 const gint bit_offset, gint no_of_chars);
373 tvb_get_ts_23_038_7bits_string() returns a string of a given number of
374 characters and encoded according to 3GPP TS 23.038 7 bits alphabet.
376 The buffer is allocated in the given wmem scope (see README.wmem for more
379 Byte Array Accessors:
381 gchar *tvb_bytes_to_str(wmem_allocator_t *scope, tvbuff_t *tvb, const gint offset, const gint len);
383 Formats a bunch of data from a tvbuff as bytes, returning a pointer
384 to the string with the data formatted as two hex digits for each byte.
385 The string pointed to is stored in an "wmem_alloc'd" buffer which will be freed
386 depending on its scope (typically wmem_packet_scope which is freed after the frame).
387 The formatted string will contain the hex digits for at most the first 16 bytes of
388 the data. If len is greater than 16 bytes, a trailing "..." will be added to the string.
390 gchar *tvb_bytes_to_str_punct(wmem_allocator_t *scope, tvbuff_t *tvb,
391 const gint offset, const gint len, const gchar punct);
393 This function is similar to tvb_bytes_to_str(...) except that 'punct' is inserted
394 between the hex representation of each byte.
396 GByteArray *tvb_get_string_bytes(tvbuff_t *tvb, const gint offset, const gint length,
397 const guint encoding, GByteArray* bytes, gint *endoff)
399 Given a tvbuff, an offset into the tvbuff, and a length that starts
400 at that offset (which may be -1 for "all the way to the end of the
401 tvbuff"), fetch the hex-decoded byte values of the tvbuff into the
402 passed-in 'bytes' array, based on the passed-in encoding. In other
403 words, convert from a hex-ascii string in tvbuff, into the supplied
406 gchar *tvb_bcd_dig_to_wmem_packet_str(tvbuff_t *tvb, const gint offset, const gint len, dgt_set_t *dgt, gboolean skip_first);
408 Given a tvbuff, an offset into the tvbuff, and a length that starts
409 at that offset (which may be -1 for "all the way to the end of the
410 tvbuff"), fetch BCD encoded digits from a tvbuff starting from either
411 the low or high half byte, formatting the digits according to an input digit set,
412 if NUll a default digit set of 0-9 returning "?" for overdecadic digits will be used.
413 A pointer to the packet scope allocated string will be returned.
414 Note: a tvbuff content of 0xf is considered a 'filler' and will end the conversion.
417 void* tvb_memcpy(tvbuff_t *tvb, void* target, const gint offset, size_t length);
419 Copies into the specified target the specified length's worth of data
420 from the specified tvbuff, starting at the specified offset.
422 void *tvb_memdup(wmem_allocator_t *scope, tvbuff_t *tvb, const gint offset, size_t length);
424 Returns a buffer containing a copy of the given TVB bytes. The buffer is
425 allocated in the given wmem scope (see README.wmem for more information).
428 /* WARNING! Don't use this function. There is almost always a better way.
429 * It's dangerous because once this pointer is given to the user, there's
430 * no guarantee that the user will honor the 'length' and not overstep the
431 * boundaries of the buffer. Also see the warning in the Portability section.
433 const guint8* tvb_get_ptr(tvbuff_t *tvb, const gint offset, const gint length);
436 Get amount of captured data in the buffer (which is *NOT* necessarily the
437 length of the packet). You probably want tvb_reported_length instead:
439 guint tvb_captured_length(const tvbuff_t *tvb);
441 Get reported length of buffer:
443 guint tvb_reported_length(const tvbuff_t *tvb);
446 1.4 Functions to handle columns in the traffic summary window.
448 The topmost pane of the main window is a list of the packets in the
449 capture, possibly filtered by a display filter.
451 Each line corresponds to a packet, and has one or more columns, as
452 configured by the user.
454 Many of the columns are handled by code outside individual dissectors;
455 most dissectors need only specify the value to put in the "Protocol" and
458 Columns are specified by COL_ values; the COL_ value for the "Protocol"
459 field, typically giving an abbreviated name for the protocol (but not
460 the all-lower-case abbreviation used elsewhere) is COL_PROTOCOL, and the
461 COL_ value for the "Info" field, giving a summary of the contents of the
462 packet for that protocol, is COL_INFO.
464 The value for a column can be specified with one of several functions,
465 all of which take the 'fd' argument to the dissector as their first
466 argument, and the COL_ value for the column as their second argument.
468 1.4.1 The col_set_str function.
470 'col_set_str' takes a string as its third argument, and sets the value
471 for the column to that value. It assumes that the pointer passed to it
472 points to a string constant or a static "const" array, not to a
473 variable, as it doesn't copy the string, it merely saves the pointer
474 value; the argument can itself be a variable, as long as it always
475 points to a string constant or a static "const" array.
477 It is more efficient than 'col_add_str' or 'col_add_fstr'; however, if
478 the dissector will be using 'col_append_str' or 'col_append_fstr" to
479 append more information to the column, the string will have to be copied
480 anyway, so it's best to use 'col_add_str' rather than 'col_set_str' in
483 For example, to set the "Protocol" column
486 col_set_str(pinfo->cinfo, COL_PROTOCOL, "PROTOABBREV");
489 1.4.2 The col_add_str function.
491 'col_add_str' takes a string as its third argument, and sets the value
492 for the column to that value. It takes the same arguments as
493 'col_set_str', but copies the string, so that if the string is, for
494 example, an automatic variable that won't remain in scope when the
495 dissector returns, it's safe to use.
498 1.4.3 The col_add_fstr function.
500 'col_add_fstr' takes a 'printf'-style format string as its third
501 argument, and 'printf'-style arguments corresponding to '%' format
502 items in that string as its subsequent arguments. For example, to set
503 the "Info" field to "<XXX> request, <N> bytes", where "reqtype" is a
504 string containing the type of the request in the packet and "n" is an
505 unsigned integer containing the number of bytes in the request:
507 col_add_fstr(pinfo->cinfo, COL_INFO, "%s request, %u bytes",
510 Don't use 'col_add_fstr' with a format argument of just "%s" -
511 'col_add_str', or possibly even 'col_set_str' if the string that matches
512 the "%s" is a static constant string, will do the same job more
516 1.4.4 The col_clear function.
518 If the Info column will be filled with information from the packet, that
519 means that some data will be fetched from the packet before the Info
520 column is filled in. If the packet is so small that the data in
521 question cannot be fetched, the routines to fetch the data will throw an
522 exception (see the comment at the beginning about tvbuffers improving
523 the handling of short packets - the tvbuffers keep track of how much
524 data is in the packet, and throw an exception on an attempt to fetch
525 data past the end of the packet, so that the dissector won't process
526 bogus data), causing the Info column not to be filled in.
528 This means that the Info column will have data for the previous
529 protocol, which would be confusing if, for example, the Protocol column
530 had data for this protocol.
532 Therefore, before a dissector fetches any data whatsoever from the
533 packet (unless it's a heuristic dissector fetching data to determine
534 whether the packet is one that it should dissect, in which case it
535 should check, before fetching the data, whether there's any data to
536 fetch; if there isn't, it should return FALSE), it should set the
537 Protocol column and the Info column.
539 If the Protocol column will ultimately be set to, for example, a value
540 containing a protocol version number, with the version number being a
541 field in the packet, the dissector should, before fetching the version
542 number field or any other field from the packet, set it to a value
543 without a version number, using 'col_set_str', and should later set it
544 to a value with the version number after it's fetched the version
547 If the Info column will ultimately be set to a value containing
548 information from the packet, the dissector should, before fetching any
549 fields from the packet, clear the column using 'col_clear' (which is
550 more efficient than clearing it by calling 'col_set_str' or
551 'col_add_str' with a null string), and should later set it to the real
552 string after it's fetched the data to use when doing that.
555 1.4.5 The col_append_str function.
557 Sometimes the value of a column, especially the "Info" column, can't be
558 conveniently constructed at a single point in the dissection process;
559 for example, it might contain small bits of information from many of the
560 fields in the packet. 'col_append_str' takes, as arguments, the same
561 arguments as 'col_add_str', but the string is appended to the end of the
562 current value for the column, rather than replacing the value for that
563 column. (Note that no blank separates the appended string from the
564 string to which it is appended; if you want a blank there, you must add
565 it yourself as part of the string being appended.)
568 1.4.6 The col_append_fstr function.
570 'col_append_fstr' is to 'col_add_fstr' as 'col_append_str' is to
571 'col_add_str' - it takes, as arguments, the same arguments as
572 'col_add_fstr', but the formatted string is appended to the end of the
573 current value for the column, rather than replacing the value for that
576 1.4.7 The col_append_sep_str and col_append_sep_fstr functions.
578 In specific situations the developer knows that a column's value will be
579 created in a stepwise manner, where the appended values are listed. Both
580 'col_append_sep_str' and 'col_append_sep_fstr' functions will add an item
581 separator between two consecutive items, and will not add the separator at the
582 beginning of the column. The remainder of the work both functions do is
583 identical to what 'col_append_str' and 'col_append_fstr' do.
585 1.4.8 The col_set_fence and col_prepend_fence_fstr functions.
587 Sometimes a dissector may be called multiple times for different PDUs in the
588 same frame (for example in the case of SCTP chunk bundling: several upper
589 layer data packets may be contained in one SCTP packet). If the upper layer
590 dissector calls 'col_set_str()' or 'col_clear()' on the Info column when it
591 begins dissecting each of those PDUs then when the frame is fully dissected
592 the Info column would contain only the string from the last PDU in the frame.
593 The 'col_set_fence' function erects a "fence" in the column that prevents
594 subsequent 'col_...' calls from clearing the data currently in that column.
595 For example, the SCTP dissector calls 'col_set_fence' on the Info column
596 after it has called any subdissectors for that chunk so that subdissectors
597 of any subsequent chunks may only append to the Info column.
598 'col_prepend_fence_fstr' prepends data before a fence (moving it if
599 necessary). It will create a fence at the end of the prepended data if the
600 fence does not already exist.
603 1.4.9 The col_set_time function.
605 The 'col_set_time' function takes an nstime value as its third argument.
606 This nstime value is a relative value and will be added as such to the
607 column. The fourth argument is the filtername holding this value. This
608 way, rightclicking on the column makes it possible to build a filter
609 based on the time-value.
613 col_set_time(pinfo->cinfo, COL_REL_TIME, &ts, "s4607.ploc.time");
616 1.5 Constructing the protocol tree.
618 The middle pane of the main window, and the topmost pane of a packet
619 popup window, are constructed from the "protocol tree" for a packet.
621 The protocol tree, or proto_tree, is a GNode, the N-way tree structure
622 available within GLIB. Of course the protocol dissectors don't care
623 what a proto_tree really is; they just pass the proto_tree pointer as an
624 argument to the routines which allow them to add items and new branches
627 When a packet is selected in the packet-list pane, or a packet popup
628 window is created, a new logical protocol tree (proto_tree) is created.
629 The pointer to the proto_tree (in this case, 'protocol tree'), is passed
630 to the top-level protocol dissector, and then to all subsequent protocol
631 dissectors for that packet, and then the GUI tree is drawn via
634 The logical proto_tree needs to know detailed information about the protocols
635 and fields about which information will be collected from the dissection
636 routines. By strictly defining (or "typing") the data that can be attached to a
637 proto tree, searching and filtering becomes possible. This means that for
638 every protocol and field (which I also call "header fields", since they are
639 fields in the protocol headers) which might be attached to a tree, some
640 information is needed.
642 Every dissector routine will need to register its protocols and fields
643 with the central protocol routines (in proto.c). At first I thought I
644 might keep all the protocol and field information about all the
645 dissectors in one file, but decentralization seemed like a better idea.
646 That one file would have gotten very large; one small change would have
647 required a re-compilation of the entire file. Also, by allowing
648 registration of protocols and fields at run-time, loadable modules of
649 protocol dissectors (perhaps even user-supplied) is feasible.
651 To do this, each protocol should have a register routine, which will be
652 called when Wireshark starts. The code to call the register routines is
653 generated automatically; to arrange that a protocol's register routine
654 be called at startup:
656 the file containing a dissector's "register" routine must be
657 added to "DISSECTOR_SRC" in "epan/dissectors/CMakeLists.txt";
659 the "register" routine must have a name of the form
660 "proto_register_XXX";
662 the "register" routine must take no argument, and return no
665 the "register" routine's name must appear in the source file
666 either at the beginning of the line, or preceded only by "void "
667 at the beginning of the line (that would typically be the
668 definition) - other white space shouldn't cause a problem, e.g.:
670 void proto_register_XXX(void) {
679 proto_register_XXX( void )
686 and so on should work.
688 For every protocol or field that a dissector wants to register, a variable of
689 type int needs to be used to keep track of the protocol. The IDs are
690 needed for establishing parent/child relationships between protocols and
691 fields, as well as associating data with a particular field so that it
692 can be stored in the logical tree and displayed in the GUI protocol
695 Some dissectors will need to create branches within their tree to help
696 organize header fields. These branches should be registered as header
697 fields. Only true protocols should be registered as protocols. This is
698 so that a display filter user interface knows how to distinguish
699 protocols from fields.
701 A protocol is registered with the name of the protocol and its
704 Here is how the frame "protocol" is registered.
708 proto_frame = proto_register_protocol (
710 /* short name */ "Frame",
711 /* abbrev */ "frame" );
713 A header field is also registered with its name and abbreviation, but
714 information about its data type is needed. It helps to look at
715 the header_field_info struct to see what information is expected:
717 struct header_field_info {
730 A string representing the name of the field. This is the name
731 that will appear in the graphical protocol tree. It must be a non-empty
736 A string with an abbreviation of the field. The abbreviation should start
737 with the abbreviation of the parent protocol followed by a period as a
738 separator. For example, the "src" field in an IP packet would have "ip.src"
739 as an abbreviation. It is acceptable to have multiple levels of periods if,
740 for example, you have fields in your protocol that are then subdivided into
741 subfields. For example, TRMAC has multiple error fields, so the abbreviations
742 follow this pattern: "trmac.errors.iso", "trmac.errors.noniso", etc.
744 The abbreviation is the identifier used in a display filter. As such it
745 cannot be an empty string.
749 The type of value this field holds. The current field types are:
751 FT_NONE No field type. Used for fields that
752 aren't given a value, and that can only
753 be tested for presence or absence; a
754 field that represents a data structure,
755 with a subtree below it containing
756 fields for the members of the structure,
757 or that represents an array with a
758 subtree below it containing fields for
759 the members of the array, might be an
761 FT_PROTOCOL Used for protocols which will be placing
762 themselves as top-level items in the
763 "Packet Details" pane of the UI.
764 FT_BOOLEAN 0 means "false", any other value means
766 FT_FRAMENUM A frame number; if this is used, the "Go
767 To Corresponding Frame" menu item can
769 FT_CHAR An 8-bit ASCII character. It's treated similarly to an
770 FT_UINT8, but is displayed as a C-style character
772 FT_UINT8 An 8-bit unsigned integer.
773 FT_UINT16 A 16-bit unsigned integer.
774 FT_UINT24 A 24-bit unsigned integer.
775 FT_UINT32 A 32-bit unsigned integer.
776 FT_UINT40 A 40-bit unsigned integer.
777 FT_UINT48 A 48-bit unsigned integer.
778 FT_UINT56 A 56-bit unsigned integer.
779 FT_UINT64 A 64-bit unsigned integer.
780 FT_INT8 An 8-bit signed integer.
781 FT_INT16 A 16-bit signed integer.
782 FT_INT24 A 24-bit signed integer.
783 FT_INT32 A 32-bit signed integer.
784 FT_INT40 A 40-bit signed integer.
785 FT_INT48 A 48-bit signed integer.
786 FT_INT56 A 56-bit signed integer.
787 FT_INT64 A 64-bit signed integer.
788 FT_FLOAT A single-precision floating point number.
789 FT_DOUBLE A double-precision floating point number.
790 FT_ABSOLUTE_TIME An absolute time from some fixed point in time,
791 displayed as the date, followed by the time, as
792 hours, minutes, and seconds with 9 digits after
794 FT_RELATIVE_TIME Seconds (4 bytes) and nanoseconds (4 bytes)
795 of time relative to an arbitrary time.
796 displayed as seconds and 9 digits
797 after the decimal point.
798 FT_STRING A string of characters, not necessarily
799 NULL-terminated, but possibly NULL-padded.
800 This, and the other string-of-characters
801 types, are to be used for text strings,
803 FT_STRINGZ A NULL-terminated string of characters.
804 The string length is normally the length
805 given in the proto_tree_add_item() call.
806 However if the length given in the call
807 is -1, then the length used is that
808 returned by calling tvb_strsize().
809 FT_UINT_STRING A counted string of characters, consisting
810 of a count (represented as an integral value,
811 of width given in the proto_tree_add_item()
812 call) followed immediately by that number of
814 FT_ETHER A six octet string displayed in
815 Ethernet-address format.
816 FT_BYTES A string of bytes with arbitrary values;
817 used for raw binary data.
818 FT_UINT_BYTES A counted string of bytes, consisting
819 of a count (represented as an integral value,
820 of width given in the proto_tree_add_item()
821 call) followed immediately by that number of
822 arbitrary values; used for raw binary data.
823 FT_IPv4 A version 4 IP address (4 bytes) displayed
824 in dotted-quad IP address format (4
825 decimal numbers separated by dots).
826 FT_IPv6 A version 6 IP address (16 bytes) displayed
827 in standard IPv6 address format.
828 FT_IPXNET An IPX address displayed in hex as a 6-byte
829 network number followed by a 6-byte station
831 FT_GUID A Globally Unique Identifier
832 FT_OID An ASN.1 Object Identifier
833 FT_REL_OID An ASN.1 Relative Object Identifier
834 FT_EUI64 A EUI-64 Address
835 FT_AX25 A AX-25 Address
836 FT_VINES A Vines Address
837 FT_SYSTEM_ID An OSI System-ID
838 FT_FCWWN A Fibre Channel WWN Address
840 Some of these field types are still not handled in the display filter
841 routines, but the most common ones are. The FT_UINT* variables all
842 represent unsigned integers, and the FT_INT* variables all represent
843 signed integers; the number on the end represent how many bits are used
844 to represent the number.
846 Some constraints are imposed on the header fields depending on the type
847 (e.g. FT_BYTES) of the field. Fields of type FT_ABSOLUTE_TIME must use
848 'ABSOLUTE_TIME_{LOCAL,UTC,DOY_UTC}, NULL, 0x0' as values for the
849 'display, 'strings', and 'bitmask' fields, and all other non-integral
850 types (i.e.. types that are _not_ FT_INT* and FT_UINT*) must use
851 'BASE_NONE, NULL, 0x0' as values for the 'display', 'strings', 'bitmask'
852 fields. The reason is simply that the type itself implicitly defines the
853 nature of 'display', 'strings', 'bitmask'.
855 display (FIELDDISPLAY)
856 ----------------------
857 The display field has a couple of overloaded uses. This is unfortunate,
858 but since we're using C as an application programming language, this sometimes
859 makes for cleaner programs. Right now I still think that overloading
860 this variable was okay.
862 For integer fields (FT_UINT* and FT_INT*), this variable represents the
863 base in which you would like the value displayed. The acceptable bases
873 BASE_DEC, BASE_HEX, and BASE_OCT are decimal, hexadecimal, and octal,
874 respectively. BASE_DEC_HEX and BASE_HEX_DEC display value in two bases
875 (the 1st representation followed by the 2nd in parenthesis).
877 BASE_CUSTOM allows one to specify a callback function pointer that will
880 For 32-bit and smaller values, custom_fmt_func_t can be used to declare
881 the callback function pointer. Specifically, this is defined as:
883 void func(gchar *, guint32);
885 For values larger than 32-bits, custom_fmt_func_64_t can be used to declare
886 the callback function pointer. Specifically, this is defined as:
888 void func(gchar *, guint64);
890 The first argument is a pointer to a buffer of the ITEM_LABEL_LENGTH size
891 and the second argument is the value to be formatted.
893 Both custom_fmt_func_t and custom_fmt_func_64_t are defined in epan/proto.h.
895 For FT_UINT16 'display' can be used to select a transport layer protocol using one
896 of BASE_PT_UDP, BASE_PT_TCP, BASE_PT_DCCP or BASE_PT_SCTP. If transport name
897 resolution is enabled the port field label is displayed in decimal and as a well-known
898 service name (if one is available).
900 For FT_BOOLEAN fields that are also bitfields (i.e., 'bitmask' is non-zero),
901 'display' is used specify a "field-width" (i.e., tell the proto_tree how
902 wide the parent bitfield is). (If the FT_BOOLEAN 'bitmask' is zero, then
903 'display' must be BASE_NONE).
905 For integer fields a "field-width" is not needed since the type of
906 integer itself (FT_UINT8, FT_UINT16, FT_UINT24, FT_UINT32, FT_UINT40,
907 FT_UINT48, FT_UINT56, FT_UINT64, etc) tells the proto_tree how wide the
908 parent bitfield is. The same is true of FT_CHAR, as it's an 8-bit
911 For FT_ABSOLUTE_TIME fields, 'display' is used to indicate whether the
912 time is to be displayed as a time in the time zone for the machine on
913 which Wireshark/TShark is running or as UTC and, for UTC, whether the
914 date should be displayed as "{monthname} {day_of_month}, {year}" or as
915 "{year/day_of_year}".
917 Additionally, BASE_NONE is used for 'display' as a NULL-value. That is, for
918 non-integers other than FT_ABSOLUTE_TIME fields, and non-bitfield
919 FT_BOOLEANs, you'll want to use BASE_NONE in the 'display' field. You may
920 not use BASE_NONE for integers.
922 It is possible that in the future we will record the endianness of
923 integers. If so, it is likely that we'll use a bitmask on the display field
924 so that integers would be represented as BEND|BASE_DEC or LEND|BASE_HEX.
925 But that has not happened yet; note that there are protocols for which
926 no endianness is specified, such as the X11 protocol and the DCE RPC
927 protocol, so it would not be possible to record the endianness of all
930 strings (FIELDCONVERT)
931 ----------------------
933 Some integer fields, of type FT_UINT*, need labels to represent the true
934 value of a field. You could think of those fields as having an
935 enumerated data type, rather than an integral data type.
937 A 'value_string' structure is a way to map values to strings.
939 typedef struct _value_string {
944 For fields of that type, you would declare an array of "value_string"s:
946 static const value_string valstringname[] = {
947 { INTVAL1, "Descriptive String 1" },
948 { INTVAL2, "Descriptive String 2" },
952 (the last entry in the array must have a NULL 'strptr' value, to
953 indicate the end of the array). The 'strings' field would be set to
954 'VALS(valstringname)'.
956 If the field has a numeric rather than an enumerated type, the 'strings'
957 field would be set to NULL.
959 If BASE_SPECIAL_VALS is also applied to the display bitmask, then if the
960 numeric value of a field doesn't match any values in the value_string
961 then just the numeric value is displayed (i.e. no "Unknown"). This is
962 intended for use when the value_string only gives special names for
963 certain field values and values not in the value_string are expected.
965 -- Extended value strings
966 You can also use an extended version of the value_string for faster lookups.
967 It requires a value_string array as input.
968 If all of a contiguous range of values from min to max are present in the array
969 in ascending order the value will be used as a direct index into a value_string array.
971 If the values in the array are not contiguous (ie: there are "gaps"), but are
972 in ascending order a binary search will be used.
974 Note: "gaps" in a value_string array can be filled with "empty" entries eg:
975 {value, "Unknown"} so that direct access to the array is is possible.
977 Note: the value_string array values are *unsigned*; IOW: -1 is greater than 0.
979 { -2, -1, 1, 2 }; wrong: linear search will be used (note gap)
980 { 1, 2, -2, -1 }; correct: binary search will be used
983 { -2, -1, 0, 1, 2 }; OK: direct(indexed) access will be used (note no gap)
985 The init macro (see below) will perform a check on the value string the first
986 time it is used to determine which search algorithm fits and fall back to a
987 linear search if the value_string does not meet the criteria above.
989 Use this macro to initialize the extended value_string at compile time:
991 static value_string_ext valstringname_ext = VALUE_STRING_EXT_INIT(valstringname);
993 Extended value strings can be created at run time by calling
994 value_string_ext_new(<ptr to value_string array>,
995 <total number of entries in the value_string_array>, /* include {0, NULL} entry */
996 <value_string_name>);
998 For hf[] array FT_(U)INT* fields that need a 'valstringname_ext' struct, the
999 'strings' field would be set to '&valstringname_ext'. Furthermore, the 'display'
1000 field must be ORed with 'BASE_EXT_STRING' (e.g. BASE_DEC|BASE_EXT_STRING).
1004 val64_strings are like value_strings, except that the integer type
1005 used is a guint64 (instead of guint32). Instead of using the VALS()
1006 macro for the 'strings' field in the header_field_info struct array,
1009 BASE_SPECIAL_VALS can also be used for val64_string.
1013 val64_string_ext is like value_string_ext, except that the integer type
1014 used is a guint64 (instead of guint32).
1016 Use this macro to initialize the extended val64_string at compile time:
1018 static val64_string_ext val64stringname_ext = VAL64_STRING_EXT_INIT(val64stringname);
1020 Extended val64 strings can be created at run time by calling
1021 val64_string_ext_new(<ptr to val64_string array>,
1022 <total number of entries in the val64_string_array>, /* include {0, NULL} entry */
1023 <val64_string_name>);
1025 For hf[] array FT_(U)INT* fields that need a 'val64stringname_ext' struct, the
1026 'strings' field would be set to '&val64stringname_ext'. Furthermore, the 'display'
1027 field must be ORed with both 'BASE_EXT_STRING' and 'BASE_VAL64_STRING'
1028 (e.g. BASE_DEC|BASE_EXT_STRING|BASE_VAL64_STRING).
1031 Some integer fields, of type FT_UINT* and float fields, of type FT_FLOAT
1032 or FT_DOUBLE, need units of measurement to help convey the field value.
1034 A 'unit_name_string' structure is a way to add a unit suffix to a field.
1036 typedef struct unit_name_string {
1037 char *singular; /* name to use for 1 unit */
1038 char *plural; /* name to use for < 1 or > 1 units */
1041 For fields with that unit name, you would declare a "unit_name_string":
1043 static const unit_name_string unitname[] =
1044 { "single item name" , "multiple item name" };
1046 (the second entry can be NULL if there is no plural form of the unit name.
1047 This is typically the case when abbreviations are used instead of full words.)
1049 There are several "common" unit name structures already defined in
1050 epan/unit_strings.h. Dissector authors may choose to add the unit name
1051 structure there rather than locally in a dissector.
1053 For hf[] array FT_(U)INT*, FT_FlOAT and FT_DOUBLE fields that need a
1054 'unit_name_string' struct, the 'strings' field would be set to
1055 '&units_second_seconds'. Furthermore, the 'display' field must be ORed
1056 with 'BASE_UNIT_STRING' (e.g. BASE_DEC|BASE_UNIT_STRING).
1059 If the field has a numeric type that might logically fit in ranges of values
1060 one can use a range_string struct.
1062 Thus a 'range_string' structure is a way to map ranges to strings.
1064 typedef struct _range_string {
1067 const gchar *strptr;
1070 For fields of that type, you would declare an array of "range_string"s:
1072 static const range_string rvalstringname[] = {
1073 { INTVAL_MIN1, INTVALMAX1, "Descriptive String 1" },
1074 { INTVAL_MIN2, INTVALMAX2, "Descriptive String 2" },
1078 If INTVAL_MIN equals INTVAL_MAX for a given entry the range_string
1079 behavior collapses to the one of value_string.
1080 For FT_(U)INT* fields that need a 'range_string' struct, the 'strings' field
1081 would be set to 'RVALS(rvalstringname)'. Furthermore, 'display' field must be
1082 ORed with 'BASE_RANGE_STRING' (e.g. BASE_DEC|BASE_RANGE_STRING).
1085 FT_BOOLEANs have a default map of 0 = "False", 1 (or anything else) = "True".
1086 Sometimes it is useful to change the labels for boolean values (e.g.,
1087 to "Yes"/"No", "Fast"/"Slow", etc.). For these mappings, a struct called
1088 true_false_string is used.
1090 typedef struct true_false_string {
1093 } true_false_string;
1095 For Boolean fields for which "False" and "True" aren't the desired
1096 labels, you would declare a "true_false_string"s:
1098 static const true_false_string boolstringname = {
1103 Its two fields are pointers to the string representing truth, and the
1104 string representing falsehood. For FT_BOOLEAN fields that need a
1105 'true_false_string' struct, the 'strings' field would be set to
1106 'TFS(&boolstringname)'.
1108 If the Boolean field is to be displayed as "False" or "True", the
1109 'strings' field would be set to NULL.
1111 Wireshark predefines a whole range of ready made "true_false_string"s
1112 in tfs.h, included via packet.h.
1115 Custom fields (BASE_CUSTOM) should use CF_FUNC(&custom_format_func) for the
1118 -- Note to plugin authors
1119 Data cannot get exported from DLLs. For this reason plugin authors cannot use
1120 existing fieldconvert strings (e.g. from existing dissectors or those from
1121 epan/unit_strings.h). Plugins must define value_strings, unit_name_strings,
1122 range_strings and true_false_strings locally.
1126 If the field is a bitfield, then the bitmask is the mask which will
1127 leave only the bits needed to make the field when ANDed with a value.
1128 The proto_tree routines will calculate 'bitshift' automatically
1129 from 'bitmask', by finding the rightmost set bit in the bitmask.
1130 This shift is applied before applying string mapping functions or
1133 If the field is not a bitfield, then bitmask should be set to 0.
1137 This is a string giving a proper description of the field. It should be
1138 at least one grammatically complete sentence, or NULL in which case the
1139 name field is used. (Please do not use "").
1141 It is meant to provide a more detailed description of the field than the
1142 name alone provides. This information will be used in the man page, and
1143 in a future GUI display-filter creation tool. We might also add tooltips
1144 to the labels in the GUI protocol tree, in which case the blurb would
1145 be used as the tooltip text.
1148 1.5.1 Field Registration.
1150 Protocol registration is handled by creating an instance of the
1151 header_field_info struct (or an array of such structs), and
1152 calling the registration function along with the registration ID of
1153 the protocol that is the parent of the fields. Here is a complete example:
1155 static int proto_eg = -1;
1156 static int hf_field_a = -1;
1157 static int hf_field_b = -1;
1159 static hf_register_info hf[] = {
1162 { "Field A", "proto.field_a", FT_UINT8, BASE_HEX, NULL,
1163 0xf0, "Field A represents Apples", HFILL }},
1166 { "Field B", "proto.field_b", FT_UINT16, BASE_DEC, VALS(vs),
1167 0x0, "Field B represents Bananas", HFILL }}
1170 proto_eg = proto_register_protocol("Example Protocol",
1172 proto_register_field_array(proto_eg, hf, array_length(hf));
1174 Be sure that your array of hf_register_info structs is declared 'static',
1175 since the proto_register_field_array() function does not create a copy
1176 of the information in the array... it uses that static copy of the
1177 information that the compiler created inside your array. Here's the
1178 layout of the hf_register_info struct:
1180 typedef struct hf_register_info {
1181 int *p_id; /* pointer to parent variable */
1182 header_field_info hfinfo;
1185 Also be sure to use the handy array_length() macro found in packet.h
1186 to have the compiler compute the array length for you at compile time.
1188 If you don't have any fields to register, do *NOT* create a zero-length
1189 "hf" array; not all compilers used to compile Wireshark support them.
1190 Just omit the "hf" array, and the "proto_register_field_array()" call,
1193 It is OK to have header fields with a different format be registered with
1194 the same abbreviation. For instance, the following is valid:
1196 static hf_register_info hf[] = {
1198 { &hf_field_8bit, /* 8-bit version of proto.field */
1199 { "Field (8 bit)", "proto.field", FT_UINT8, BASE_DEC, NULL,
1200 0x00, "Field represents FOO", HFILL }},
1202 { &hf_field_32bit, /* 32-bit version of proto.field */
1203 { "Field (32 bit)", "proto.field", FT_UINT32, BASE_DEC, NULL,
1204 0x00, "Field represents FOO", HFILL }}
1207 This way a filter expression can match a header field, irrespective of the
1208 representation of it in the specific protocol context. This is interesting
1209 for protocols with variable-width header fields.
1211 Note that the formats used must all belong to the same group as defined below:
1212 - FT_INT8, FT_INT16, FT_INT24 and FT_INT32
1213 - FT_CHAR, FT_UINT8, FT_UINT16, FT_UINT24, FT_UINT32, FT_IPXNET and FT_FRAMENUM
1214 - FT_INT40, FT_INT48, FT_INT56 and FT_INT64
1215 - FT_UINT40, FT_UINT48, FT_UINT56, FT_UINT64 and FT_EUI64
1216 - FT_ABSOLUTE_TIME and FT_RELATIVE_TIME
1217 - FT_STRING, FT_STRINGZ, FT_UINT_STRING and FT_STRINGZPAD
1218 - FT_FLOAT and FT_DOUBLE
1219 - FT_BYTES, FT_UINT_BYTES, FT_ETHER, FT_AX25, FT_VINES and FT_FCWWN
1220 - FT_OID, FT_REL_OID and FT_SYSTEM_ID
1222 Any field not in a grouping above should *NOT* be used in duplicate field
1223 abbreviations. The current code does not prevent it, but someday in the future
1226 The HFILL macro at the end of the struct will set reasonable default values
1227 for internally used fields.
1229 1.5.2 Adding Items and Values to the Protocol Tree.
1231 A protocol item is added to an existing protocol tree with one of a
1232 handful of proto_XXX_DO_YYY() functions.
1234 Subtrees can be made with the proto_item_add_subtree() function:
1236 item = proto_tree_add_item(....);
1237 new_tree = proto_item_add_subtree(item, tree_type);
1239 This will add a subtree under the item in question; a subtree can be
1240 created under an item made by any of the "proto_tree_add_XXX" functions,
1241 so that the tree can be given an arbitrary depth.
1243 Subtree types are integers, assigned by
1244 "proto_register_subtree_array()". To register subtree types, pass an
1245 array of pointers to "gint" variables to hold the subtree type values to
1246 "proto_register_subtree_array()":
1248 static gint ett_eg = -1;
1249 static gint ett_field_a = -1;
1251 static gint *ett[] = {
1256 proto_register_subtree_array(ett, array_length(ett));
1258 in your "register" routine, just as you register the protocol and the
1259 fields for that protocol.
1261 The ett_ variables identify particular type of subtree so that if you expand
1262 one of them, Wireshark keeps track of that and, when you click on
1263 another packet, it automatically opens all subtrees of that type.
1264 If you close one of them, all subtrees of that type will be closed when
1265 you move to another packet.
1267 There are several functions that the programmer can use to add either
1268 protocol or field labels to the proto_tree:
1271 proto_tree_add_item(tree, id, tvb, start, length, encoding);
1274 proto_tree_add_item_ret_int(tree, id, tvb, start, length, encoding,
1278 proto_tree_add_item_ret_uint(tree, id, tvb, start, length, encoding,
1282 proto_tree_add_item_ret_uint64(tree, id, tvb, start, length, encoding,
1286 proto_tree_add_item_ret_boolean(tree, id, tvb, start, length, encoding,
1290 proto_tree_add_subtree(tree, tvb, start, length, idx, tree_item,
1294 proto_tree_add_subtree_format(tree, tvb, start, length, idx, tree_item,
1298 proto_tree_add_none_format(tree, id, tvb, start, length, format, ...);
1301 proto_tree_add_protocol_format(tree, id, tvb, start, length,
1305 proto_tree_add_bytes(tree, id, tvb, start, length, start_ptr);
1308 proto_tree_add_bytes_item(tree, id, tvb, start, length, encoding,
1309 retval, endoff, err);
1312 proto_tree_add_bytes_format(tree, id, tvb, start, length, start_ptr,
1316 proto_tree_add_bytes_format_value(tree, id, tvb, start, length,
1317 start_ptr, format, ...);
1320 proto_tree_add_bytes_with_length(tree, id, tvb, start, tvb_length, start_ptr, ptr_length);
1323 proto_tree_add_time(tree, id, tvb, start, length, value_ptr);
1326 proto_tree_add_time_item(tree, id, tvb, start, length, encoding,
1327 retval, endoff, err);
1330 proto_tree_add_time_format(tree, id, tvb, start, length, value_ptr,
1334 proto_tree_add_time_format_value(tree, id, tvb, start, length,
1335 value_ptr, format, ...);
1338 proto_tree_add_ipxnet(tree, id, tvb, start, length, value);
1341 proto_tree_add_ipxnet_format(tree, id, tvb, start, length, value,
1345 proto_tree_add_ipxnet_format_value(tree, id, tvb, start, length,
1346 value, format, ...);
1349 proto_tree_add_ipv4(tree, id, tvb, start, length, value);
1352 proto_tree_add_ipv4_format(tree, id, tvb, start, length, value,
1356 proto_tree_add_ipv4_format_value(tree, id, tvb, start, length,
1357 value, format, ...);
1360 proto_tree_add_ipv6(tree, id, tvb, start, length, value_ptr);
1363 proto_tree_add_ipv6_format(tree, id, tvb, start, length, value_ptr,
1367 proto_tree_add_ipv6_format_value(tree, id, tvb, start, length,
1368 value_ptr, format, ...);
1371 proto_tree_add_ether(tree, id, tvb, start, length, value_ptr);
1374 proto_tree_add_ether_format(tree, id, tvb, start, length, value_ptr,
1378 proto_tree_add_ether_format_value(tree, id, tvb, start, length,
1379 value_ptr, format, ...);
1382 proto_tree_add_guid(tree, id, tvb, start, length, value_ptr);
1385 proto_tree_add_guid_format(tree, id, tvb, start, length, value_ptr,
1389 proto_tree_add_guid_format_value(tree, id, tvb, start, length,
1390 value_ptr, format, ...);
1393 proto_tree_add_oid(tree, id, tvb, start, length, value_ptr);
1396 proto_tree_add_oid_format(tree, id, tvb, start, length, value_ptr,
1400 proto_tree_add_oid_format_value(tree, id, tvb, start, length,
1401 value_ptr, format, ...);
1404 proto_tree_add_string(tree, id, tvb, start, length, value_ptr);
1407 proto_tree_add_string_format(tree, id, tvb, start, length, value_ptr,
1411 proto_tree_add_string_format_value(tree, id, tvb, start, length,
1412 value_ptr, format, ...);
1415 proto_tree_add_boolean(tree, id, tvb, start, length, value);
1418 proto_tree_add_boolean_format(tree, id, tvb, start, length, value,
1422 proto_tree_add_boolean_format_value(tree, id, tvb, start, length,
1423 value, format, ...);
1426 proto_tree_add_float(tree, id, tvb, start, length, value);
1429 proto_tree_add_float_format(tree, id, tvb, start, length, value,
1433 proto_tree_add_float_format_value(tree, id, tvb, start, length,
1434 value, format, ...);
1437 proto_tree_add_double(tree, id, tvb, start, length, value);
1440 proto_tree_add_double_format(tree, id, tvb, start, length, value,
1444 proto_tree_add_double_format_value(tree, id, tvb, start, length,
1445 value, format, ...);
1448 proto_tree_add_uint(tree, id, tvb, start, length, value);
1451 proto_tree_add_uint_format(tree, id, tvb, start, length, value,
1455 proto_tree_add_uint_format_value(tree, id, tvb, start, length,
1456 value, format, ...);
1459 proto_tree_add_uint64(tree, id, tvb, start, length, value);
1462 proto_tree_add_uint64_format(tree, id, tvb, start, length, value,
1466 proto_tree_add_uint64_format_value(tree, id, tvb, start, length,
1467 value, format, ...);
1470 proto_tree_add_int(tree, id, tvb, start, length, value);
1473 proto_tree_add_int_format(tree, id, tvb, start, length, value,
1477 proto_tree_add_int_format_value(tree, id, tvb, start, length,
1478 value, format, ...);
1481 proto_tree_add_int64(tree, id, tvb, start, length, value);
1484 proto_tree_add_int64_format(tree, id, tvb, start, length, value,
1488 proto_tree_add_int64_format_value(tree, id, tvb, start, length,
1489 value, format, ...);
1492 proto_tree_add_eui64(tree, id, tvb, start, length, value);
1495 proto_tree_add_eui64_format(tree, id, tvb, start, length, value,
1499 proto_tree_add_eui64_format_value(tree, id, tvb, start, length,
1500 value, format, ...);
1503 proto_tree_add_checksum(proto_tree *tree, tvbuff_t *tvb, const guint offset,
1504 const int hf_checksum, const int hf_checksum_status, struct expert_field* bad_checksum_expert,
1505 packet_info *pinfo, guint32 computed_checksum, const guint encoding, const guint flags);
1508 proto_tree_add_bitmask(tree, tvb, start, header, ett, fields,
1512 proto_tree_add_bitmask_len(tree, tvb, start, len, header, ett, fields,
1516 proto_tree_add_bitmask_text(tree, tvb, offset, len, name, fallback,
1517 ett, fields, encoding, flags);
1520 proto_tree_add_bitmask_with_flags(tree, tvb, offset, hf_hdr, ett,
1521 fields, encoding, flags);
1524 proto_tree_add_bits_item(tree, id, tvb, bit_offset, no_of_bits,
1528 proto_tree_add_split_bits_item_ret_val(tree, hf_index, tvb, bit_offset,
1529 crumb_spec, return_value);
1532 proto_tree_add_split_bits_crumb(tree, hf_index, tvb, bit_offset,
1533 crumb_spec, crumb_index);
1536 proto_tree_add_bits_ret_val(tree, id, tvb, bit_offset, no_of_bits,
1537 return_value, encoding);
1540 proto_tree_add_uint_bits_format_value(tree, id, tvb, bit_offset,
1541 no_of_bits, value, format, ...);
1544 proto_tree_add_boolean_bits_format_value(tree, id, tvb, bit_offset,
1545 no_of_bits, value, format, ...);
1548 proto_tree_add_int_bits_format_value(tree, id, tvb, bit_offset,
1549 no_of_bits, value, format, ...);
1552 proto_tree_add_float_bits_format_value(tree, id, tvb, bit_offset,
1553 no_of_bits, value, format, ...);
1556 proto_tree_add_ts_23_038_7bits_item(tree, hf_index, tvb,
1557 bit_offset, no_of_chars);
1559 The 'tree' argument is the tree to which the item is to be added. The
1560 'tvb' argument is the tvbuff from which the item's value is being
1561 extracted; the 'start' argument is the offset from the beginning of that
1562 tvbuff of the item being added, and the 'length' argument is the length,
1563 in bytes, of the item, bit_offset is the offset in bits and no_of_bits
1564 is the length in bits.
1566 The length of some items cannot be determined until the item has been
1567 dissected; to add such an item, add it with a length of -1, and, when the
1568 dissection is complete, set the length with 'proto_item_set_len()':
1571 proto_item_set_len(ti, length);
1573 The "ti" argument is the value returned by the call that added the item
1574 to the tree, and the "length" argument is the length of the item.
1576 proto_tree_add_item()
1577 ---------------------
1578 proto_tree_add_item is used when you wish to do no special formatting.
1579 The item added to the GUI tree will contain the name (as passed in the
1580 proto_register_*() function) and a value. The value will be fetched
1581 from the tvbuff by proto_tree_add_item(), based on the type of the field
1582 and the encoding of the value as specified by the "encoding" argument.
1584 For FT_NONE, FT_BYTES, FT_ETHER, FT_IPv6, FT_IPXNET, FT_OID, FT_REL_OID,
1585 FT_AX25, FT_VINES, FT_SYSTEM_ID, FT_FCWWN fields, and 'protocol' fields
1586 the encoding is not relevant; the 'encoding' argument should be
1587 ENC_NA (Not Applicable).
1589 For FT_UINT_BYTES fields, the byte order of the count must be specified
1590 as well as the 'encoding' for bytes which should be ENC_NA,
1591 i.e. ENC_LITTLE_ENDIAN|ENC_NA
1593 For integral, floating-point, Boolean, FT_GUID, and FT_EUI64 fields,
1594 the encoding specifies the byte order of the value; the 'encoding'
1595 argument should be ENC_LITTLE_ENDIAN if the value is little-endian
1596 and ENC_BIG_ENDIAN if it is big-endian.
1598 For FT_IPv4 fields, the encoding also specifies the byte order of the
1599 value. In almost all cases, the encoding is in network byte order,
1600 hence big-endian, but in at least one protocol dissected by Wireshark,
1601 at least one IPv4 address is byte-swapped, so it's in little-endian
1604 For string fields, the encoding specifies the character set used for the
1605 string and the way individual code points in that character set are
1606 encoded. For FT_UINT_STRING fields, the byte order of the count must be
1607 specified; for UCS-2 and UTF-16, the byte order of the encoding must be
1608 specified (for counted UCS-2 and UTF-16 strings, the byte order of the
1609 count and the 16-bit values in the string must be the same). In other
1610 cases, ENC_NA should be used. The character encodings that are
1611 currently supported are:
1613 ENC_ASCII - ASCII (currently treated as UTF-8; in the future,
1614 all bytes with the 8th bit set will be treated as
1616 ENC_UTF_8 - UTF-8-encoded Unicode
1617 ENC_UTF_16 - UTF-16-encoded Unicode, with surrogate pairs
1618 ENC_UCS_2 - UCS-2-encoded subset of Unicode, with no surrogate pairs
1619 and thus no code points above 0xFFFF
1620 ENC_UCS_4 - UCS-4-encoded Unicode
1621 ENC_WINDOWS_1250 - Windows-1250 code page
1622 ENC_ISO_8859_1 - ISO 8859-1
1623 ENC_ISO_8859_2 - ISO 8859-2
1624 ENC_ISO_8859_3 - ISO 8859-3
1625 ENC_ISO_8859_4 - ISO 8859-4
1626 ENC_ISO_8859_5 - ISO 8859-5
1627 ENC_ISO_8859_6 - ISO 8859-6
1628 ENC_ISO_8859_7 - ISO 8859-7
1629 ENC_ISO_8859_8 - ISO 8859-8
1630 ENC_ISO_8859_9 - ISO 8859-9
1631 ENC_ISO_8859_10 - ISO 8859-10
1632 ENC_ISO_8859_11 - ISO 8859-11
1633 ENC_ISO_8859_13 - ISO 8859-13
1634 ENC_ISO_8859_14 - ISO 8859-14
1635 ENC_ISO_8859_15 - ISO 8859-15
1636 ENC_ISO_8859_16 - ISO 8859-16
1637 ENC_WINDOWS_1250 - Windows-1250
1638 ENC_3GPP_TS_23_038_7BITS - GSM 7 bits alphabet as described
1641 ENC_MAC_ROMAN - MAC ROMAN
1642 ENC_CP437 - DOS CP437
1643 ENC_ASCII_7BITS - 7 bits ASCII
1646 Other encodings will be added in the future.
1648 For FT_ABSOLUTE_TIME fields, the encoding specifies the form in which
1649 the time stamp is specified, as well as its byte order. The time stamp
1650 encodings that are currently supported are:
1652 ENC_TIME_SECS_NSECS - 8, 12, or 16 bytes. For 8 bytes, the first 4
1653 bytes are seconds and the next 4 bytes are nanoseconds; for 12
1654 bytes, the first 8 bytes are seconds and the next 4 bytes are
1655 nanoseconds; for 16 bytes, the first 8 bytes are seconds and
1656 the next 8 bytes are nanoseconds. The seconds are seconds
1657 since the UN*X epoch (1970-01-01 00:00:00 UTC). (I.e., a UN*X
1658 struct timespec with a 4-byte or 8-byte time_t or a structure
1659 with an 8-byte time_t and an 8-byte nanoseconds field.)
1661 ENC_TIME_NTP - 8 bytes; the first 4 bytes are seconds since the NTP
1662 epoch (1900-01-01 00:00:00 GMT) and the next 4 bytes are 1/2^32's of
1663 a second since that second. (I.e., a 64-bit count of 1/2^32's of a
1664 second since the NTP epoch, with the upper 32 bits first and the
1665 lower 32 bits second, even when little-endian.)
1667 ENC_TIME_TOD - 8 bytes, as a count of microseconds since the System/3x0
1668 and z/Architecture epoch (1900-01-01 00:00:00 GMT).
1670 ENC_TIME_RTPS - 8 bytes; the first 4 bytes are seconds since the UN*X
1671 epoch and the next 4 bytes are are 1/2^32's of a second since that
1672 second. (I.e., it's the offspring of a mating between UN*X time and
1673 NTP time.) It's used by the Object Management Group's Real-Time
1674 Publish-Subscribe Wire Protocol for the Data Distribution Service.
1676 ENC_TIME_SECS_USECS - 8 bytes; the first 4 bytes are seconds since the
1677 UN*X epoch and the next 4 bytes are microseconds since that
1678 second. (I.e., a UN*X struct timeval with a 4-byte time_t.)
1680 ENC_TIME_SECS - 4 to 8 bytes, representing a value in seconds since
1683 ENC_TIME_MSECS - 6 to 8 bytes, representing a value in milliseconds
1684 since the UN*X epoch.
1686 ENC_TIME_SECS_NTP - 4 bytes, representing a count of seconds since
1687 the NTP epoch. (I.e., seconds since the NTP epoch.)
1689 ENC_TIME_RFC_3971 - 8 bytes, representing a count of 1/64ths of a
1690 second since the UN*X epoch; see section 5.3.1 "Timestamp Option"
1693 ENC_TIME_MSEC_NTP - 4-8 bytes, representing a count of milliseconds since
1694 the NTP epoch. (I.e., milliseconds since the NTP epoch.)
1696 For FT_RELATIVE_TIME fields, the encoding specifies the form in which
1697 the time stamp is specified, as well as its byte order. The time stamp
1698 encodings that are currently supported are:
1700 ENC_TIME_SECS_NSECS - 8, 12, or 16 bytes. For 8 bytes, the first 4
1701 bytes are seconds and the next 4 bytes are nanoseconds; for 12
1702 bytes, the first 8 bytes are seconds and the next 4 bytes are
1703 nanoseconds; for 16 bytes, the first 8 bytes are seconds and
1704 the next 8 bytes are nanoseconds.
1706 ENC_TIME_SECS_USECS - 8 bytes; the first 4 bytes are seconds and the
1707 next 4 bytes are microseconds.
1709 ENC_TIME_SECS - 4 to 8 bytes, representing a value in seconds.
1711 ENC_TIME_MSECS - 6 to 8 bytes, representing a value in milliseconds.
1713 For other types, there is no support for proto_tree_add_item().
1715 Now that definitions of fields have detailed information about bitfield
1716 fields, you can use proto_tree_add_item() with no extra processing to
1717 add bitfield values to your tree. Here's an example. Take the Format
1718 Identifier (FID) field in the Transmission Header (TH) portion of the SNA
1719 protocol. The FID is the high nibble of the first byte of the TH. The
1720 FID would be registered like this:
1722 name = "Format Identifier"
1723 abbrev = "sna.th.fid"
1726 strings = sna_th_fid_vals
1729 The bitmask contains the value which would leave only the FID if bitwise-ANDed
1730 against the parent field, the first byte of the TH.
1732 The code to add the FID to the tree would be;
1734 proto_tree_add_item(bf_tree, hf_sna_th_fid, tvb, offset, 1,
1737 The definition of the field already has the information about bitmasking
1738 and bitshifting, so it does the work of masking and shifting for us!
1739 This also means that you no longer have to create value_string structs
1740 with the values bitshifted. The value_string for FID looks like this,
1741 even though the FID value is actually contained in the high nibble.
1742 (You'd expect the values to be 0x0, 0x10, 0x20, etc.)
1744 /* Format Identifier */
1745 static const value_string sna_th_fid_vals[] = {
1746 { 0x0, "SNA device <--> Non-SNA Device" },
1747 { 0x1, "Subarea Node <--> Subarea Node" },
1748 { 0x2, "Subarea Node <--> PU2" },
1749 { 0x3, "Subarea Node or SNA host <--> Subarea Node" },
1752 { 0xf, "Adjacent Subarea Nodes" },
1756 The final implication of this is that display filters work the way you'd
1757 naturally expect them to. You'd type "sna.th.fid == 0xf" to find Adjacent
1758 Subarea Nodes. The user does not have to shift the value of the FID to
1759 the high nibble of the byte ("sna.th.fid == 0xf0") as was necessary
1762 proto_tree_add_item_ret_XXX()
1763 ------------------------------
1764 proto_tree_add_item_ret_XXX is used when you want the displayed value returned
1765 for futher processing only integer and unsigned integer types up to 32 bits are
1766 supported usage of proper FT_ is checked.
1768 proto_tree_add_XXX_item()
1769 ---------------------
1770 proto_tree_add_XXX_item is used when you wish to do no special formatting,
1771 but also either wish for the retrieved value from the tvbuff to be handed
1772 back (to avoid doing tvb_get_...), and/or wish to have the value be decoded
1773 from the tvbuff in a string-encoded format.
1775 The item added to the GUI tree will contain the name (as passed in the
1776 proto_register_*() function) and a value. The value will be fetched
1777 from the tvbuff, based on the type of the XXX name and the encoding of
1778 the value as specified by the "encoding" argument.
1780 This function retrieves the value even if the passed-in tree param is NULL,
1781 so that it can be used by dissectors at all times to both get the value
1782 and set the tree item to it.
1784 Like other proto_tree_add functions, if there is a tree and the value cannot
1785 be decoded from the tvbuff, then an expert info error is reported. For string
1786 encoding, this means that a failure to decode the hex value from the string
1787 results in an expert info error being added to the tree.
1789 For string-decoding, the passed-in encoding argument needs to specify the
1790 string encoding (e.g., ENC_ASCII, ENC_UTF_8) as well as the format. For
1791 some XXX types, the format is constrained - for example for the encoding format
1792 for proto_tree_add_time_item() can only be one of the ENC_ISO_8601_* ones
1793 or ENC_RFC_822 or ENC_RFC_1123. For proto_tree_add_bytes_item() it can only
1794 be ENC_STR_HEX bit-or'ed with one or more of the ENC_SEP_* separator types.
1796 proto_tree_add_protocol_format()
1797 --------------------------------
1798 proto_tree_add_protocol_format is used to add the top-level item for the
1799 protocol when the dissector routine wants complete control over how the
1800 field and value will be represented on the GUI tree. The ID value for
1801 the protocol is passed in as the "id" argument; the rest of the
1802 arguments are a "printf"-style format and any arguments for that format.
1803 The caller must include the name of the protocol in the format; it is
1804 not added automatically as in proto_tree_add_item().
1806 proto_tree_add_none_format()
1807 ----------------------------
1808 proto_tree_add_none_format is used to add an item of type FT_NONE.
1809 The caller must include the name of the field in the format; it is
1810 not added automatically as in proto_tree_add_item().
1812 proto_tree_add_bytes()
1813 proto_tree_add_time()
1814 proto_tree_add_ipxnet()
1815 proto_tree_add_ipv4()
1816 proto_tree_add_ipv6()
1817 proto_tree_add_ether()
1818 proto_tree_add_string()
1819 proto_tree_add_boolean()
1820 proto_tree_add_float()
1821 proto_tree_add_double()
1822 proto_tree_add_uint()
1823 proto_tree_add_uint64()
1824 proto_tree_add_int()
1825 proto_tree_add_int64()
1826 proto_tree_add_guid()
1827 proto_tree_add_oid()
1828 proto_tree_add_eui64()
1829 ------------------------
1830 These routines are used to add items to the protocol tree if either:
1832 the value of the item to be added isn't just extracted from the
1833 packet data, but is computed from data in the packet;
1835 the value was fetched into a variable.
1837 The 'value' argument has the value to be added to the tree.
1839 NOTE: in all cases where the 'value' argument is a pointer, a copy is
1840 made of the object pointed to; if you have dynamically allocated a
1841 buffer for the object, that buffer will not be freed when the protocol
1842 tree is freed - you must free the buffer yourself when you don't need it
1845 For proto_tree_add_bytes(), the 'value_ptr' argument is a pointer to a
1849 proto_tree_add_bytes_with_length() is similar to proto_tree_add_bytes,
1850 except that the length is not derived from the tvb length. Instead,
1851 the displayed data size is controlled by 'ptr_length'.
1853 For proto_tree_add_bytes_format() and proto_tree_add_bytes_format_value(), the
1854 'value_ptr' argument is a pointer to a sequence of bytes or NULL if the bytes
1855 should be taken from the given TVB using the given offset and length.
1857 For proto_tree_add_time(), the 'value_ptr' argument is a pointer to an
1858 "nstime_t", which is a structure containing the time to be added; it has
1859 'secs' and 'nsecs' members, giving the integral part and the fractional
1860 part of a time in units of seconds, with 'nsecs' being the number of
1861 nanoseconds. For absolute times, "secs" is a UNIX-style seconds since
1862 January 1, 1970, 00:00:00 GMT value.
1864 For proto_tree_add_ipxnet(), the 'value' argument is a 32-bit IPX
1867 For proto_tree_add_ipv4(), the 'value' argument is a 32-bit IPv4
1868 address, in network byte order.
1870 For proto_tree_add_ipv6(), the 'value_ptr' argument is a pointer to a
1871 128-bit IPv6 address.
1873 For proto_tree_add_ether(), the 'value_ptr' argument is a pointer to a
1876 For proto_tree_add_string(), the 'value_ptr' argument is a pointer to a
1877 text string; this string must be NULL terminated even if the string in the
1878 TVB is not (as may be the case with FT_STRINGs).
1880 For proto_tree_add_boolean(), the 'value' argument is a 32-bit integer.
1881 It is masked and shifted as defined by the field info after which zero
1882 means "false", and non-zero means "true".
1884 For proto_tree_add_float(), the 'value' argument is a 'float' in the
1885 host's floating-point format.
1887 For proto_tree_add_double(), the 'value' argument is a 'double' in the
1888 host's floating-point format.
1890 For proto_tree_add_uint(), the 'value' argument is a 32-bit unsigned
1891 integer value, in host byte order. (This routine cannot be used to add
1894 For proto_tree_add_uint64(), the 'value' argument is a 64-bit unsigned
1895 integer value, in host byte order.
1897 For proto_tree_add_int(), the 'value' argument is a 32-bit signed
1898 integer value, in host byte order. (This routine cannot be used to add
1901 For proto_tree_add_int64(), the 'value' argument is a 64-bit signed
1902 integer value, in host byte order.
1904 For proto_tree_add_guid(), the 'value_ptr' argument is a pointer to an
1907 For proto_tree_add_oid(), the 'value_ptr' argument is a pointer to an
1908 ASN.1 Object Identifier.
1910 For proto_tree_add_eui64(), the 'value' argument is a 64-bit integer
1913 proto_tree_add_bytes_format()
1914 proto_tree_add_time_format()
1915 proto_tree_add_ipxnet_format()
1916 proto_tree_add_ipv4_format()
1917 proto_tree_add_ipv6_format()
1918 proto_tree_add_ether_format()
1919 proto_tree_add_string_format()
1920 proto_tree_add_boolean_format()
1921 proto_tree_add_float_format()
1922 proto_tree_add_double_format()
1923 proto_tree_add_uint_format()
1924 proto_tree_add_uint64_format()
1925 proto_tree_add_int_format()
1926 proto_tree_add_int64_format()
1927 proto_tree_add_guid_format()
1928 proto_tree_add_oid_format()
1929 proto_tree_add_eui64_format()
1930 ----------------------------
1931 These routines are used to add items to the protocol tree when the
1932 dissector routine wants complete control over how the field and value
1933 will be represented on the GUI tree. The argument giving the value is
1934 the same as the corresponding proto_tree_add_XXX() function; the rest of
1935 the arguments are a "printf"-style format and any arguments for that
1936 format. The caller must include the name of the field in the format; it
1937 is not added automatically as in the proto_tree_add_XXX() functions.
1939 proto_tree_add_bytes_format_value()
1940 proto_tree_add_time_format_value()
1941 proto_tree_add_ipxnet_format_value()
1942 proto_tree_add_ipv4_format_value()
1943 proto_tree_add_ipv6_format_value()
1944 proto_tree_add_ether_format_value()
1945 proto_tree_add_string_format_value()
1946 proto_tree_add_boolean_format_value()
1947 proto_tree_add_float_format_value()
1948 proto_tree_add_double_format_value()
1949 proto_tree_add_uint_format_value()
1950 proto_tree_add_uint64_format_value()
1951 proto_tree_add_int_format_value()
1952 proto_tree_add_int64_format_value()
1953 proto_tree_add_guid_format_value()
1954 proto_tree_add_oid_format_value()
1955 proto_tree_add_eui64_format_value()
1956 ------------------------------------
1958 These routines are used to add items to the protocol tree when the
1959 dissector routine wants complete control over how the value will be
1960 represented on the GUI tree. The argument giving the value is the same
1961 as the corresponding proto_tree_add_XXX() function; the rest of the
1962 arguments are a "printf"-style format and any arguments for that format.
1963 With these routines, unlike the proto_tree_add_XXX_format() routines,
1964 the name of the field is added automatically as in the
1965 proto_tree_add_XXX() functions; only the value is added with the format.
1966 One use case for this would be to add a unit of measurement string to
1967 the value of the field, however using BASE_UNIT_STRING in the hf_
1968 definition is now preferred.
1970 proto_tree_add_checksum()
1971 ----------------------------
1972 proto_tree_add_checksum is used to add a checksum field. The hf field
1973 provided must be the correct size of the checksum (FT_UINT, FT_UINT16,
1974 FT_UINT32, etc). Additional parameters are there to provide "status"
1975 and expert info depending on whether the checksum matches the provided
1976 value. The "status" and expert info can be used in cases except
1977 where PROTO_CHECKSUM_NO_FLAGS is used.
1979 proto_tree_add_subtree()
1980 ---------------------
1981 proto_tree_add_subtree() is used to add a label to the GUI tree and create
1982 a subtree for other fields. It will contain no value, so it is not searchable
1983 in the display filter process.
1985 This should only be used for items with subtrees, which may not
1986 have values themselves - the items in the subtree are the ones with values.
1988 For a subtree, the label on the subtree might reflect some of the items
1989 in the subtree. This means the label can't be set until at least some
1990 of the items in the subtree have been dissected. To do this, use
1991 'proto_item_set_text()' or 'proto_item_append_text()':
1994 proto_item_set_text(proto_item *ti, ...);
1997 proto_item_append_text(proto_item *ti, ...);
1999 'proto_item_set_text()' takes as an argument the proto_item value returned by
2000 one of the parameters in 'proto_tree_add_subtree()', a 'printf'-style format
2001 string, and a set of arguments corresponding to '%' format items in that string,
2002 and replaces the text for the item created by 'proto_tree_add_subtree()' with the result
2003 of applying the arguments to the format string.
2005 'proto_item_append_text()' is similar, but it appends to the text for
2006 the item the result of applying the arguments to the format string.
2008 For example, early in the dissection, one might do:
2010 subtree = proto_tree_add_subtree(tree, tvb, offset, length, ett, &ti, <label>);
2014 proto_item_set_text(ti, "%s: %s", type, value);
2016 after the "type" and "value" fields have been extracted and dissected.
2017 <label> would be a label giving what information about the subtree is
2018 available without dissecting any of the data in the subtree.
2020 Note that an exception might be thrown when trying to extract the values of
2021 the items used to set the label, if not all the bytes of the item are
2022 available. Thus, one should create the item with text that is as
2023 meaningful as possible, and set it or append additional information to
2024 it as the values needed to supply that information are extracted.
2026 proto_tree_add_subtree_format()
2027 ----------------------------
2028 This is like proto_tree_add_subtree(), but uses printf-style arguments to
2029 create the label; it is used to allow routines that take a printf-like
2030 variable-length list of arguments to add a text item to the protocol
2033 proto_tree_add_bits_item()
2034 --------------------------
2035 Adds a number of bits to the protocol tree which does not have to be byte
2036 aligned. The offset and length is in bits.
2039 ..10 1010 10.. .... "value" (formatted as FT_ indicates).
2041 proto_tree_add_bits_ret_val()
2042 -----------------------------
2043 Works in the same way but also returns the value of the read bits.
2045 proto_tree_add_split_bits_item_ret_val()
2046 -----------------------------------
2047 Similar, but is used for items that are made of 2 or more smaller sets of bits (crumbs)
2048 which are not contiguous, but are concatenated to form the actual value. The size of
2049 the crumbs and the order of assembly are specified in an array of crumb_spec structures.
2051 proto_tree_add_split_bits_crumb()
2052 ---------------------------------
2053 Helper function for the above, to add text for each crumb as it is encountered.
2055 proto_tree_add_ts_23_038_7bits_item()
2056 -------------------------------------
2057 Adds a string of a given number of characters and encoded according to 3GPP TS 23.038 7 bits
2060 proto_tree_add_bitmask() et al.
2061 -------------------------------
2062 These functions provide easy to use and convenient dissection of many types of common
2063 bitmasks into individual fields.
2065 header is an integer type and must be of type FT_[U]INT{8|16|24|32||40|48|56|64} and
2066 represents the entire dissectable width of the bitmask.
2068 'header' and 'ett' are the hf fields and ett field respectively to create an
2069 expansion that covers the bytes of the bitmask.
2071 'fields' is a NULL terminated array of pointers to hf fields representing
2072 the individual subfields of the bitmask. These fields must either be integers
2073 (usually of the same byte width as 'header') or of the type FT_BOOLEAN.
2074 Each of the entries in 'fields' will be dissected as an item under the
2075 'header' expansion and also IF the field is a boolean and IF it is set to 1,
2076 then the name of that boolean field will be printed on the 'header' expansion
2077 line. For integer type subfields that have a value_string defined, the
2078 matched string from that value_string will be printed on the expansion line
2081 Example: (from the SCSI dissector)
2082 static int hf_scsi_inq_peripheral = -1;
2083 static int hf_scsi_inq_qualifier = -1;
2084 static int hf_scsi_inq_devtype = -1;
2086 static gint ett_scsi_inq_peripheral = -1;
2088 static const int *peripheral_fields[] = {
2089 &hf_scsi_inq_qualifier,
2090 &hf_scsi_inq_devtype,
2094 /* Qualifier and DeviceType */
2095 proto_tree_add_bitmask(tree, tvb, offset, hf_scsi_inq_peripheral,
2096 ett_scsi_inq_peripheral, peripheral_fields, ENC_BIG_ENDIAN);
2099 { &hf_scsi_inq_peripheral,
2100 {"Peripheral", "scsi.inquiry.peripheral", FT_UINT8, BASE_HEX,
2101 NULL, 0, NULL, HFILL}},
2102 { &hf_scsi_inq_qualifier,
2103 {"Qualifier", "scsi.inquiry.qualifier", FT_UINT8, BASE_HEX,
2104 VALS (scsi_qualifier_val), 0xE0, NULL, HFILL}},
2105 { &hf_scsi_inq_devtype,
2106 {"Device Type", "scsi.inquiry.devtype", FT_UINT8, BASE_HEX,
2107 VALS (scsi_devtype_val), SCSI_DEV_BITS, NULL, HFILL}},
2110 Which provides very pretty dissection of this one byte bitmask.
2112 Peripheral: 0x05, Qualifier: Device type is connected to logical unit, Device Type: CD-ROM
2113 000. .... = Qualifier: Device type is connected to logical unit (0x00)
2114 ...0 0101 = Device Type: CD-ROM (0x05)
2116 The proto_tree_add_bitmask_text() function is an extended version of
2117 the proto_tree_add_bitmask() function. In addition, it allows to:
2118 - Provide a leading text (e.g. "Flags: ") that will appear before
2119 the comma-separated list of field values
2120 - Provide a fallback text (e.g. "None") that will be appended if
2121 no fields warranted a change to the top-level title.
2122 - Using flags, specify which fields will affect the top-level title.
2124 There are the following flags defined:
2126 BMT_NO_APPEND - the title is taken "as-is" from the 'name' argument.
2127 BMT_NO_INT - only boolean flags are added to the title.
2128 BMT_NO_FALSE - boolean flags are only added to the title if they are set.
2129 BMT_NO_TFS - only add flag name to the title, do not use true_false_string
2131 The proto_tree_add_bitmask_with_flags() function is an extended version
2132 of the proto_tree_add_bitmask() function. It allows using flags to specify
2133 which fields will affect the top-level title. The flags are the
2134 same BMT_NO_* flags as used in the proto_tree_add_bitmask_text() function.
2136 The proto_tree_add_bitmask() behavior can be obtained by providing
2137 both 'name' and 'fallback' arguments as NULL, and a flags of
2138 (BMT_NO_FALSE|BMT_NO_TFS).
2140 The proto_tree_add_bitmask_len() function is intended for protocols where
2141 bitmask length is permitted to vary, so a length is specified explicitly
2142 along with the bitmask value. USB Video "bmControl" and "bControlSize"
2143 fields follow this pattern. The primary intent of this is "forward
2144 compatibility," enabling an interpreter coded for version M of a structure
2145 to comprehend fields in version N of the structure, where N > M and
2146 bControlSize increases from version M to version N.
2148 proto_tree_add_bitmask_len() is an extended version of proto_tree_add_bitmask()
2149 that uses an explicitly specified (rather than inferred) length to control
2150 dissection. Because of this, it may encounter two cases that
2151 proto_tree_add_bitmask() and proto_tree_add_bitmask_text() may not:
2152 - A length that exceeds that of the 'header' and bitmask subfields.
2153 In this case the least-significant bytes of the bitmask are dissected.
2154 An expert warning is generated in this case, because the dissection code
2155 likely needs to be updated for a new revision of the protocol.
2156 - A length that is shorter than that of the 'header' and bitmask subfields.
2157 In this case, subfields whose data is fully present are dissected,
2158 and other subfields are not. No warning is generated in this case,
2159 because the dissection code is likely for a later revision of the protocol
2160 than the packet it was called to interpret.
2163 PROTO_ITEM_SET_GENERATED()
2164 --------------------------
2165 PROTO_ITEM_SET_GENERATED is used to mark fields as not being read from the
2166 captured data directly, but inferred from one or more values.
2168 One of the primary uses of this is the presentation of verification of
2169 checksums. Every IP packet has a checksum line, which can present the result
2170 of the checksum verification, if enabled in the preferences. The result is
2171 presented as a subtree, where the result is enclosed in square brackets
2172 indicating a generated field.
2174 Header checksum: 0x3d42 [correct]
2175 [Checksum Status: Good (1)]
2177 PROTO_ITEM_SET_HIDDEN()
2178 -----------------------
2179 PROTO_ITEM_SET_HIDDEN is used to hide fields, which have already been added
2180 to the tree, from being visible in the displayed tree.
2182 NOTE that creating hidden fields is actually quite a bad idea from a UI design
2183 perspective because the user (someone who did not write nor has ever seen the
2184 code) has no way of knowing that hidden fields are there to be filtered on
2185 thus defeating the whole purpose of putting them there. A Better Way might
2186 be to add the fields (that might otherwise be hidden) to a subtree where they
2187 won't be seen unless the user opens the subtree--but they can be found if the
2190 One use for hidden fields (which would be better implemented using visible
2191 fields in a subtree) follows: The caller may want a value to be
2192 included in a tree so that the packet can be filtered on this field, but
2193 the representation of that field in the tree is not appropriate. An
2194 example is the token-ring routing information field (RIF). The best way
2195 to show the RIF in a GUI is by a sequence of ring and bridge numbers.
2196 Rings are 3-digit hex numbers, and bridges are single hex digits:
2198 RIF: 001-A-013-9-C0F-B-555
2200 In the case of RIF, the programmer should use a field with no value and
2201 use proto_tree_add_none_format() to build the above representation. The
2202 programmer can then add the ring and bridge values, one-by-one, with
2203 proto_tree_add_item() and hide them with PROTO_ITEM_SET_HIDDEN() so that the
2204 user can then filter on or search for a particular ring or bridge. Here's a
2205 skeleton of how the programmer might code this.
2208 rif = create_rif_string(...);
2210 proto_tree_add_none_format(tree, hf_tr_rif_label, ..., "RIF: %s", rif);
2212 for(i = 0; i < num_rings; i++) {
2215 pi = proto_tree_add_item(tree, hf_tr_rif_ring, ...,
2217 PROTO_ITEM_SET_HIDDEN(pi);
2219 for(i = 0; i < num_rings - 1; i++) {
2222 pi = proto_tree_add_item(tree, hf_tr_rif_bridge, ...,
2224 PROTO_ITEM_SET_HIDDEN(pi);
2227 The logical tree has these items:
2229 hf_tr_rif_label, text="RIF: 001-A-013-9-C0F-B-555", value = NONE
2230 hf_tr_rif_ring, hidden, value=0x001
2231 hf_tr_rif_bridge, hidden, value=0xA
2232 hf_tr_rif_ring, hidden, value=0x013
2233 hf_tr_rif_bridge, hidden, value=0x9
2234 hf_tr_rif_ring, hidden, value=0xC0F
2235 hf_tr_rif_bridge, hidden, value=0xB
2236 hf_tr_rif_ring, hidden, value=0x555
2238 GUI or print code will not display the hidden fields, but a display
2239 filter or "packet grep" routine will still see the values. The possible
2240 filter is then possible:
2242 tr.rif_ring eq 0x013
2246 PROTO_ITEM_SET_URL is used to mark fields as containing a URL. This can only
2247 be done with fields of type FT_STRING(Z). If these fields are presented they
2248 are underlined, as could be done in a browser. These fields are sensitive to
2249 clicks as well, launching the configured browser with this URL as parameter.
2251 1.6 Utility routines.
2253 1.6.1 val_to_str, val_to_str_const, try_val_to_str and try_val_to_str_idx
2255 A dissector may need to convert a value to a string, using a
2256 'value_string' structure, by hand, rather than by declaring a field with
2257 an associated 'value_string' structure; this might be used, for example,
2258 to generate a COL_INFO line for a frame.
2260 val_to_str() handles the most common case:
2263 val_to_str(guint32 val, const value_string *vs, const char *fmt)
2265 If the value 'val' is found in the 'value_string' table pointed to by
2266 'vs', 'val_to_str' will return the corresponding string; otherwise, it
2267 will use 'fmt' as an 'sprintf'-style format, with 'val' as an argument,
2268 to generate a string, and will return a pointer to that string.
2269 You can use it in a call to generate a COL_INFO line for a frame such as
2271 col_add_fstr(COL_INFO, ", %s", val_to_str(val, table, "Unknown %d"));
2273 If you don't need to display 'val' in your fmt string, you can use
2274 val_to_str_const() which just takes a string constant instead and returns it
2275 unmodified when 'val' isn't found.
2277 If you need to handle the failure case in some custom way, try_val_to_str()
2278 will return NULL if val isn't found:
2281 try_val_to_str(guint32 val, const value_string *vs)
2283 Note that, you must check whether 'try_val_to_str()' returns NULL, and arrange
2284 that its return value not be dereferenced if it's NULL. 'try_val_to_str_idx()'
2285 behaves similarly, except it also returns an index into the value_string array,
2286 or -1 if 'val' was not found.
2288 The *_ext functions are "extended" versions of those already described. They
2289 should be used for large value-string arrays which contain many entries. They
2290 implement value to string conversions which will do either a direct access or
2291 a binary search of the value string array if possible. See
2292 "Extended Value Strings" under section 1.6 "Constructing the protocol tree" for
2295 See epan/value_string.h for detailed information on the various value_string
2298 To handle 64-bit values, there are an equivalent set of functions. These are:
2301 val64_to_str(const guint64 val, const val64_string *vs, const char *fmt)
2304 val64_to_str_const(const guint64 val, const val64_string *vs, const char *unknown_str);
2307 try_val64_to_str(const guint64 val, const val64_string *vs);
2310 try_val64_to_str_idx(const guint64 val, const val64_string *vs, gint *idx);
2313 1.6.2 rval_to_str, try_rval_to_str and try_rval_to_str_idx
2315 A dissector may need to convert a range of values to a string, using a
2316 'range_string' structure.
2318 Most of the same functions exist as with regular value_strings (see section
2319 1.6.1) except with the names 'rval' instead of 'val'.
2322 1.7 Calling Other Dissectors.
2324 As each dissector completes its portion of the protocol analysis, it
2325 is expected to create a new tvbuff of type TVBUFF_SUBSET which
2326 contains the payload portion of the protocol (that is, the bytes
2327 that are relevant to the next dissector).
2329 To create a new TVBUFF_SUBSET that begins at a specified offset in a
2330 parent tvbuff, and runs to the end of the parent tvbuff, the routine
2331 tvbuff_new_subset_remaining() is used:
2333 next_tvb = tvb_new_subset_remaining(tvb, offset);
2336 tvb is the tvbuff that the dissector has been working on. It
2337 can be a tvbuff of any type.
2339 next_tvb is the new TVBUFF_SUBSET.
2341 offset is the byte offset of 'tvb' at which the new tvbuff
2342 should start. The first byte is the 0th byte.
2344 To create a new TVBUFF_SUBSET that begins at a specified offset in a
2345 parent tvbuff, with a specified number of bytes in the payload, the
2346 routine tvbuff_new_subset_length() is used:
2348 next_tvb = tvb_new_subset_length(tvb, offset, reported_length);
2351 tvb is the tvbuff that the dissector has been working on. It
2352 can be a tvbuff of any type.
2354 next_tvb is the new TVBUFF_SUBSET.
2356 offset is the byte offset of 'tvb' at which the new tvbuff
2357 should start. The first byte is the 0th byte.
2359 reported_length is the number of bytes that the current protocol
2360 says should be in the payload.
2362 In the few cases where the number of bytes available in the new subset
2363 must be explicitly specified, rather than being calculated based on the
2364 number of bytes in the payload, the routine tvb_new_subset_length_caplen()
2367 next_tvb = tvb_new_subset_length_caplen(tvb, offset, length, reported_length);
2370 tvb is the tvbuff that the dissector has been working on. It
2371 can be a tvbuff of any type.
2373 next_tvb is the new TVBUFF_SUBSET.
2375 offset is the byte offset of 'tvb' at which the new tvbuff
2376 should start. The first byte is the 0th byte.
2378 length is the number of bytes in the new TVBUFF_SUBSET. A length
2379 argument of -1 says to use as many bytes as are available in
2382 reported_length is the number of bytes that the current protocol
2383 says should be in the payload. A reported_length of -1 says that
2384 the protocol doesn't say anything about the size of its payload.
2386 To call a dissector you need to get the handle of the dissector using
2387 find_dissector(), passing it the string name of the dissector. The setting
2388 of the handle is usually done once at startup during the proto_reg_handoff
2389 function within the calling dissector.
2391 1.7.1 Dissector Tables
2393 Another way to call a subdissector is to setup a dissector table. A dissector
2394 table is a list of subdissectors grouped by a common identifier (integer or
2395 string) in a dissector. Subdissectors will register themselves with the dissector
2396 table using their unique identifier using one of the following APIs:
2398 void dissector_add_uint(const char *abbrev, const guint32 pattern,
2399 dissector_handle_t handle);
2401 void dissector_add_uint_range(const char *abbrev, struct epan_range *range,
2402 dissector_handle_t handle);
2404 void dissector_add_string(const char *name, const gchar *pattern,
2405 dissector_handle_t handle);
2407 void dissector_add_for_decode_as(const char *name,
2408 dissector_handle_t handle);
2410 dissector_add_for_decode_as doesn't add a unique identifier in the dissector
2411 table, but it lets the user add it from the command line or, in Wireshark,
2412 through the "Decode As" UI.
2414 Then when the dissector hits the common identifier field, it will useone of the
2415 following APIs to invoke the subdissector:
2417 int dissector_try_uint(dissector_table_t sub_dissectors,
2418 const guint32 uint_val, tvbuff_t *tvb, packet_info *pinfo,
2421 int dissector_try_uint_new(dissector_table_t sub_dissectors,
2422 const guint32 uint_val, tvbuff_t *tvb, packet_info *pinfo,
2423 proto_tree *tree, const gboolean add_proto_name, void *data);
2425 int dissector_try_string(dissector_table_t sub_dissectors, const gchar *string,
2426 tvbuff_t *tvb, packet_info *pinfo, proto_tree *tree, void *data);
2428 These pass a subset of the remaining packet (typically the rest of the
2429 packet) for the dissector table to determine which subdissector is called.
2430 This allows dissection of a packet to be expanded outside of dissector without
2431 having to modify the dissector directly.
2434 1.8 Editing CMakeLists.txt to add your dissector.
2436 To arrange that your dissector will be built as part of Wireshark, you
2437 must add the name of the source file for your dissector to the DISSECTOR_SRC
2438 section of epan/dissectors/CMakeLists.txt
2441 1.9 Using the git source code tree.
2443 See <https://www.wireshark.org/develop.html>
2446 1.10 Submitting code for your new dissector.
2448 - VERIFY that your dissector code does not use prohibited or deprecated APIs
2450 perl <wireshark_root>/tools/checkAPIs.pl <source-filename(s)>
2452 - VERIFY that your dissector code does not contain any header field related
2454 perl <wireshark_root>/tools/checkhf.pl <source-filename(s)>
2456 - VERIFY that your dissector code does not contain any display filter related
2458 perl <wireshark_root>/tools/checkfiltername.pl <source-filename(s)>
2460 - CHECK your dissector with CppCheck (http://cppcheck.sourceforge.net/) using
2461 Wireshark's customized configuration. This is particularly important on
2462 Windows, since Microsoft's compiler warnings are quite thin:
2463 ./tools/cppcheck/cppcheck.sh <source-filename(s)>
2465 - TEST YOUR DISSECTOR BEFORE SUBMITTING IT.
2466 Use fuzz-test.sh and/or randpkt against your dissector. These are
2467 described at <https://wiki.wireshark.org/FuzzTesting>.
2469 - Subscribe to <mailto:wireshark-dev[AT]wireshark.org> by sending an email to
2470 <mailto:wireshark-dev-request[AT]wireshark.org?body="help"> or visiting
2471 <https://www.wireshark.org/lists/>.
2473 - 'git diff' to verify all your changes look good.
2475 - 'git add' all the files you changed.
2477 - 'git commit' to commit (locally) your changes. First line of commit message
2478 should be a summary of the changes followed by an empty line and a more
2479 verbose description.
2481 - 'git push origin HEAD:refs/for/master' to push the changes to Gerrit. (If
2482 you previously ran 'git config --add remote.origin.push HEAD:refs/for/master'
2483 then only 'git push' is needed.)
2485 - Create a Wiki page on the protocol at <https://wiki.wireshark.org>.
2486 A template is provided so it is easy to setup in a consistent style.
2487 See: <https://wiki.wireshark.org/HowToEdit>
2488 and <https://wiki.wireshark.org/ProtocolReference>
2490 - If possible, add sample capture files to the sample captures page at
2491 <https://wiki.wireshark.org/SampleCaptures>. These files are used by
2492 the automated build system for fuzz testing.
2494 - If you don't think the wiki is the right place for your sample capture,
2495 submit a bug report to the Wireshark bug database, found at
2496 <https://bugs.wireshark.org>, qualified as an enhancement and attach your
2497 sample capture there. Normally a new dissector won't be accepted without
2498 a sample capture! If you open a bug be sure to cross-link your Gerrit
2501 2. Advanced dissector topics.
2505 Some of the advanced features are being worked on constantly. When using them
2506 it is wise to check the relevant header and source files for additional details.
2508 2.2 Following "conversations".
2510 In wireshark a conversation is defined as a series of data packets between two
2511 address:port combinations. A conversation is not sensitive to the direction of
2512 the packet. The same conversation will be returned for a packet bound from
2513 ServerA:1000 to ClientA:2000 and the packet from ClientA:2000 to ServerA:1000.
2515 2.2.1 Conversation Routines
2517 There are seven routines that you will use to work with a conversation:
2518 conversation_new, find_conversation, find_or_create_conversation,
2519 conversation_add_proto_data, conversation_get_proto_data,
2520 conversation_delete_proto_data, and conversation_set_dissector.
2523 2.2.1.1 The conversation_init function.
2525 This is an internal routine for the conversation code. As such you
2526 will not have to call this routine. Just be aware that this routine is
2527 called at the start of each capture and before the packets are filtered
2528 with a display filter. The routine will destroy all stored
2529 conversations. This routine does NOT clean up any data pointers that are
2530 passed in the conversation_add_proto_data 'data' variable. You are
2531 responsible for this clean up if you pass a malloc'ed pointer
2534 See item 2.2.1.5 for more information about use of the 'data' pointer.
2537 2.2.1.2 The conversation_new function.
2539 This routine will create a new conversation based upon two address/port
2540 pairs. If you want to associate with the conversation a pointer to a
2541 private data structure you must use the conversation_add_proto_data
2542 function. The ptype variable is used to differentiate between
2543 conversations over different protocols, i.e. TCP and UDP. The options
2544 variable is used to define a conversation that will accept any destination
2545 address and/or port. Set options = 0 if the destination port and address
2546 are know when conversation_new is called. See section 2.4 for more
2547 information on usage of the options parameter.
2549 The conversation_new prototype:
2550 conversation_t *conversation_new(guint32 setup_frame, address *addr1,
2551 address *addr2, port_type ptype, guint32 port1, guint32 port2,
2555 guint32 setup_frame = The lowest numbered frame for this conversation
2556 address* addr1 = first data packet address
2557 address* addr2 = second data packet address
2558 port_type ptype = port type, this is defined in packet.h
2559 guint32 port1 = first data packet port
2560 guint32 port2 = second data packet port
2561 guint options = conversation options, NO_ADDR2 and/or NO_PORT2
2563 setup_frame indicates the first frame for this conversation, and is used to
2564 distinguish multiple conversations with the same addr1/port1 and addr2/port2
2565 pair that occur within the same capture session.
2567 "addr1" and "port1" are the first address/port pair; "addr2" and "port2"
2568 are the second address/port pair. A conversation doesn't have source
2569 and destination address/port pairs - packets in a conversation go in
2570 both directions - so "addr1"/"port1" may be the source or destination
2571 address/port pair; "addr2"/"port2" would be the other pair.
2573 If NO_ADDR2 is specified, the conversation is set up so that a
2574 conversation lookup will match only the "addr1" address; if NO_PORT2 is
2575 specified, the conversation is set up so that a conversation lookup will
2576 match only the "port1" port; if both are specified, i.e.
2577 NO_ADDR2|NO_PORT2, the conversation is set up so that the lookup will
2578 match only the "addr1"/"port1" address/port pair. This can be used if a
2579 packet indicates that, later in the capture, a conversation will be
2580 created using certain addresses and ports, in the case where the packet
2581 doesn't specify the addresses and ports of both sides.
2583 2.2.1.3 The find_conversation function.
2585 Call this routine to look up a conversation. If no conversation is found,
2586 the routine will return a NULL value.
2588 The find_conversation prototype:
2590 conversation_t *find_conversation(guint32 frame_num, address *addr_a,
2591 address *addr_b, port_type ptype, guint32 port_a, guint32 port_b,
2595 guint32 frame_num = a frame number to match
2596 address* addr_a = first address
2597 address* addr_b = second address
2598 port_type ptype = port type
2599 guint32 port_a = first data packet port
2600 guint32 port_b = second data packet port
2601 guint options = conversation options, NO_ADDR_B and/or NO_PORT_B
2603 frame_num is a frame number to match. The conversation returned is where
2604 (frame_num >= conversation->setup_frame
2605 && frame_num < conversation->next->setup_frame)
2606 Suppose there are a total of 3 conversations (A, B, and C) that match
2607 addr_a/port_a and addr_b/port_b, where the setup_frame used in
2608 conversation_new() for A, B and C are 10, 50, and 100 respectively. The
2609 frame_num passed in find_conversation is compared to the setup_frame of each
2610 conversation. So if (frame_num >= 10 && frame_num < 50), conversation A is
2611 returned. If (frame_num >= 50 && frame_num < 100), conversation B is returned.
2612 If (frame_num >= 100) conversation C is returned.
2614 "addr_a" and "port_a" are the first address/port pair; "addr_b" and
2615 "port_b" are the second address/port pair. Again, as a conversation
2616 doesn't have source and destination address/port pairs, so
2617 "addr_a"/"port_a" may be the source or destination address/port pair;
2618 "addr_b"/"port_b" would be the other pair. The search will match the
2619 "a" address/port pair against both the "1" and "2" address/port pairs,
2620 and match the "b" address/port pair against both the "2" and "1"
2621 address/port pairs; you don't have to worry about which side the "a" or
2622 "b" pairs correspond to.
2624 If the NO_ADDR_B flag was specified to "find_conversation()", the
2625 "addr_b" address will be treated as matching any "wildcarded" address;
2626 if the NO_PORT_B flag was specified, the "port_b" port will be treated
2627 as matching any "wildcarded" port. If both flags are specified, i.e.
2628 NO_ADDR_B|NO_PORT_B, the "addr_b" address will be treated as matching
2629 any "wildcarded" address and the "port_b" port will be treated as
2630 matching any "wildcarded" port.
2632 2.2.1.4 The find_conversation_pinfo function.
2634 This convenience function will find an existing conversation (by calling
2635 find_conversation())
2637 The find_conversation_pinfo prototype:
2639 extern conversation_t *find_conversation_pinfo(packet_info *pinfo);
2642 packet_info *pinfo = the packet_info structure
2644 The frame number and the addresses necessary for find_conversation() are
2645 taken from the pinfo structure (as is commonly done).
2647 2.2.1.5 The find_or_create_conversation function.
2649 This convenience function will find an existing conversation (by calling
2650 find_conversation()) and, if a conversation does not already exist, create a
2651 new conversation by calling conversation_new().
2653 The find_or_create_conversation prototype:
2655 extern conversation_t *find_or_create_conversation(packet_info *pinfo);
2658 packet_info *pinfo = the packet_info structure
2660 The frame number and the addresses necessary for find_conversation() and
2661 conversation_new() are taken from the pinfo structure (as is commonly done)
2662 and no 'options' are used.
2665 2.2.1.6 The conversation_add_proto_data function.
2667 Once you have created a conversation with conversation_new, you can
2668 associate data with it using this function.
2670 The conversation_add_proto_data prototype:
2672 void conversation_add_proto_data(conversation_t *conv, int proto,
2676 conversation_t *conv = the conversation in question
2677 int proto = registered protocol number
2678 void *data = dissector data structure
2680 "conversation" is the value returned by conversation_new. "proto" is a
2681 unique protocol number created with proto_register_protocol. Protocols
2682 are typically registered in the proto_register_XXXX section of your
2683 dissector. "data" is a pointer to the data you wish to associate with the
2684 conversation. "data" usually points to "wmem_alloc'd" memory; the
2685 memory will be automatically freed each time a new dissection begins
2686 and thus need not be managed (freed) by the dissector.
2687 Using the protocol number allows several dissectors to
2688 associate data with a given conversation.
2691 2.2.1.7 The conversation_get_proto_data function.
2693 After you have located a conversation with find_conversation, you can use
2694 this function to retrieve any data associated with it.
2696 The conversation_get_proto_data prototype:
2698 void *conversation_get_proto_data(conversation_t *conv, int proto);
2701 conversation_t *conv = the conversation in question
2702 int proto = registered protocol number
2704 "conversation" is the conversation created with conversation_new. "proto"
2705 is a unique protocol number created with proto_register_protocol,
2706 typically in the proto_register_XXXX portion of a dissector. The function
2707 returns a pointer to the data requested, or NULL if no data was found.
2710 2.2.1.8 The conversation_delete_proto_data function.
2712 After you are finished with a conversation, you can remove your association
2713 with this function. Please note that ONLY the conversation entry is
2714 removed. If you have allocated any memory for your data (other than with wmem_alloc),
2715 you must free it as well.
2717 The conversation_delete_proto_data prototype:
2719 void conversation_delete_proto_data(conversation_t *conv, int proto);
2722 conversation_t *conv = the conversation in question
2723 int proto = registered protocol number
2725 "conversation" is the conversation created with conversation_new. "proto"
2726 is a unique protocol number created with proto_register_protocol,
2727 typically in the proto_register_XXXX portion of a dissector.
2729 2.2.1.9 The conversation_set_dissector function
2731 This function sets the protocol dissector to be invoked whenever
2732 conversation parameters (addresses, port_types, ports, etc) are matched
2733 during the dissection of a packet.
2735 The conversation_set_dissector prototype:
2737 void conversation_set_dissector(conversation_t *conversation, const dissector_handle_t handle);
2740 conversation_t *conv = the conversation in question
2741 const dissector_handle_t handle = the dissector handle.
2744 2.2.2 Using timestamps relative to the conversation
2746 There is a framework to calculate timestamps relative to the start of the
2747 conversation. First of all the timestamp of the first packet that has been
2748 seen in the conversation must be kept in the protocol data to be able
2749 to calculate the timestamp of the current packet relative to the start
2750 of the conversation. The timestamp of the last packet that was seen in the
2751 conversation should also be kept in the protocol data. This way the
2752 delta time between the current packet and the previous packet in the
2753 conversation can be calculated.
2755 So add the following items to the struct that is used for the protocol data:
2760 The ts_prev value should only be set during the first run through the
2761 packets (ie PINFO_FD_VISITED(pinfo) is false).
2763 Next step is to use the per-packet information (described in section 2.5)
2764 to keep the calculated delta timestamp, as it can only be calculated
2765 on the first run through the packets. This is because a packet can be
2766 selected in random order once the whole file has been read.
2768 After calculating the conversation timestamps, it is time to put them in
2769 the appropriate columns with the function 'col_set_time' (described in
2770 section 1.5.9). The column used for relative timestamps is:
2772 COL_REL_TIME, /* Delta time to last frame in conversation */
2774 Last but not least, there MUST be a preference in each dissector that
2775 uses conversation timestamps that makes it possible to enable and
2776 disable the calculation of conversation timestamps. The main argument
2777 for this is that a higher level conversation is able to overwrite
2778 the values of lower level conversations in these two columns. Being
2779 able to actively select which protocols may overwrite the conversation
2780 timestamp columns gives the user the power to control these columns.
2781 (A second reason is that conversation timestamps use the per-packet
2782 data structure which uses additional memory, which should be avoided
2783 if these timestamps are not needed)
2785 Have a look at the differences to packet-tcp.[ch] in SVN 22966 and
2786 SVN 23058 to see the implementation of conversation timestamps for
2790 2.2.3 The example conversation code using wmem_file_scope memory.
2792 For a conversation between two IP addresses and ports you can use this as an
2793 example. This example uses wmem_alloc() with wmem_file_scope() to allocate
2794 memory and stores the data pointer in the conversation 'data' variable.
2796 /************************ Global values ************************/
2798 /* define your structure here */
2803 /* Registered protocol number */
2804 static int my_proto = -1;
2806 /********************* in the dissector routine *********************/
2808 /* the local variables in the dissector */
2810 conversation_t *conversation;
2811 my_entry_t *data_ptr;
2814 /* look up the conversation */
2816 conversation = find_conversation(pinfo->num, &pinfo->src, &pinfo->dst,
2817 pinfo->ptype, pinfo->srcport, pinfo->destport, 0);
2819 /* if conversation found get the data pointer that you stored */
2821 data_ptr = (my_entry_t*)conversation_get_proto_data(conversation, my_proto);
2824 /* new conversation create local data structure */
2826 data_ptr = wmem_alloc(wmem_file_scope(), sizeof(my_entry_t));
2828 /*** add your code here to setup the new data structure ***/
2830 /* create the conversation with your data pointer */
2832 conversation = conversation_new(pinfo->num, &pinfo->src, &pinfo->dst, pinfo->ptype,
2833 pinfo->srcport, pinfo->destport, 0);
2834 conversation_add_proto_data(conversation, my_proto, (void *)data_ptr);
2837 /* at this point the conversation data is ready */
2839 /***************** in the protocol register routine *****************/
2841 my_proto = proto_register_protocol("My Protocol", "My Protocol", "my_proto");
2844 2.2.4 An example conversation code that starts at a specific frame number.
2846 Sometimes a dissector has determined that a new conversation is needed that
2847 starts at a specific frame number, when a capture session encompasses multiple
2848 conversation that reuse the same src/dest ip/port pairs. You can use the
2849 conversation->setup_frame returned by find_conversation with
2850 pinfo->num to determine whether or not there already exists a conversation
2851 that starts at the specific frame number.
2853 /* in the dissector routine */
2855 conversation = find_conversation(pinfo->num, &pinfo->src, &pinfo->dst,
2856 pinfo->ptype, pinfo->srcport, pinfo->destport, 0);
2857 if (conversation == NULL || (conversation->setup_frame != pinfo->num)) {
2858 /* It's not part of any conversation or the returned
2859 * conversation->setup_frame doesn't match the current frame
2862 conversation = conversation_new(pinfo->num, &pinfo->src,
2863 &pinfo->dst, pinfo->ptype, pinfo->srcport, pinfo->destport,
2868 2.2.5 The example conversation code using conversation index field.
2870 Sometimes the conversation isn't enough to define a unique data storage
2871 value for the network traffic. For example if you are storing information
2872 about requests carried in a conversation, the request may have an
2873 identifier that is used to define the request. In this case the
2874 conversation and the identifier are required to find the data storage
2875 pointer. You can use the conversation data structure index value to
2876 uniquely define the conversation.
2878 See packet-afs.c for an example of how to use the conversation index. In
2879 this dissector multiple requests are sent in the same conversation. To store
2880 information for each request the dissector has an internal hash table based
2881 upon the conversation index and values inside the request packets.
2884 /* in the dissector routine */
2886 /* to find a request value, first lookup conversation to get index */
2887 /* then used the conversation index, and request data to find data */
2888 /* in the local hash table */
2890 conversation = find_or_create_conversation(pinfo);
2892 request_key.conversation = conversation->index;
2893 request_key.service = pntoh16(&rxh->serviceId);
2894 request_key.callnumber = pntoh32(&rxh->callNumber);
2896 request_val = (struct afs_request_val *)g_hash_table_lookup(
2897 afs_request_hash, &request_key);
2899 /* only allocate a new hash element when it's a request */
2901 if (!request_val && !reply)
2903 new_request_key = wmem_alloc(wmem_file_scope(), sizeof(struct afs_request_key));
2904 *new_request_key = request_key;
2906 request_val = wmem_alloc(wmem_file_scope(), sizeof(struct afs_request_val));
2907 request_val -> opcode = pntoh32(&afsh->opcode);
2908 opcode = request_val->opcode;
2910 g_hash_table_insert(afs_request_hash, new_request_key,
2916 2.3 Dynamic conversation dissector registration.
2919 NOTE: This sections assumes that all information is available to
2920 create a complete conversation, source port/address and
2921 destination port/address. If either the destination port or
2922 address is known, see section 2.4 Dynamic server port dissector
2925 For protocols that negotiate a secondary port connection, for example
2926 packet-msproxy.c, a conversation can install a dissector to handle
2927 the secondary protocol dissection. After the conversation is created
2928 for the negotiated ports use the conversation_set_dissector to define
2929 the dissection routine.
2930 Before we create these conversations or assign a dissector to them we should
2931 first check that the conversation does not already exist and if it exists
2932 whether it is registered to our protocol or not.
2933 We should do this because it is uncommon but it does happen that multiple
2934 different protocols can use the same socketpair during different stages of
2935 an application cycle. By keeping track of the frame number a conversation
2936 was started in wireshark can still tell these different protocols apart.
2938 The second argument to conversation_set_dissector is a dissector handle,
2939 which is created with a call to create_dissector_handle or
2942 create_dissector_handle takes as arguments a pointer to the dissector
2943 function and a protocol ID as returned by proto_register_protocol;
2944 register_dissector takes as arguments a string giving a name for the
2945 dissector, a pointer to the dissector function, and a protocol ID.
2947 The protocol ID is the ID for the protocol dissected by the function.
2948 The function will not be called if the protocol has been disabled by the
2949 user; instead, the data for the protocol will be dissected as raw data.
2953 /* the handle for the dynamic dissector *
2954 static dissector_handle_t sub_dissector_handle;
2956 /* prototype for the dynamic dissector */
2957 static void sub_dissector(tvbuff_t *tvb, packet_info *pinfo,
2960 /* in the main protocol dissector, where the next dissector is setup */
2962 /* if conversation has a data field, create it and load structure */
2964 /* First check if a conversation already exists for this
2967 conversation = find_conversation(pinfo->num,
2968 &pinfo->src, &pinfo->dst, protocol,
2969 src_port, dst_port, 0);
2971 /* If there is no such conversation, or if there is one but for
2972 someone else's protocol then we just create a new conversation
2973 and assign our protocol to it.
2975 if ( (conversation == NULL) ||
2976 (conversation->dissector_handle != sub_dissector_handle) ) {
2977 new_conv_info = wmem_alloc(wmem_file_scope(), sizeof(struct _new_conv_info));
2978 new_conv_info->data1 = value1;
2980 /* create the conversation for the dynamic port */
2981 conversation = conversation_new(pinfo->num,
2982 &pinfo->src, &pinfo->dst, protocol,
2983 src_port, dst_port, new_conv_info, 0);
2985 /* set the dissector for the new conversation */
2986 conversation_set_dissector(conversation, sub_dissector_handle);
2991 proto_register_PROTOABBREV(void)
2995 sub_dissector_handle = create_dissector_handle(sub_dissector,
3001 2.4 Dynamic server port dissector registration.
3003 NOTE: While this example used both NO_ADDR2 and NO_PORT2 to create a
3004 conversation with only one port and address set, this isn't a
3005 requirement. Either the second port or the second address can be set
3006 when the conversation is created.
3008 For protocols that define a server address and port for a secondary
3009 protocol, a conversation can be used to link a protocol dissector to
3010 the server port and address. The key is to create the new
3011 conversation with the second address and port set to the "accept
3014 Some server applications can use the same port for different protocols during
3015 different stages of a transaction. For example it might initially use SNMP
3016 to perform some discovery and later switch to use TFTP using the same port.
3017 In order to handle this properly we must first check whether such a
3018 conversation already exists or not and if it exists we also check whether the
3019 registered dissector_handle for that conversation is "our" dissector or not.
3020 If not we create a new conversation on top of the previous one and set this new
3021 conversation to use our protocol.
3022 Since wireshark keeps track of the frame number where a conversation started
3023 wireshark will still be able to keep the packets apart even though they do use
3024 the same socketpair.
3025 (See packet-tftp.c and packet-snmp.c for examples of this)
3027 There are two support routines that will allow the second port and/or
3028 address to be set later.
3030 conversation_set_port2( conversation_t *conv, guint32 port);
3031 conversation_set_addr2( conversation_t *conv, address addr);
3033 These routines will change the second address or port for the
3034 conversation. So, the server port conversation will be converted into a
3035 more complete conversation definition. Don't use these routines if you
3036 want to create a conversation between the server and client and retain the
3037 server port definition, you must create a new conversation.
3042 /* the handle for the dynamic dissector *
3043 static dissector_handle_t sub_dissector_handle;
3047 /* in the main protocol dissector, where the next dissector is setup */
3049 /* if conversation has a data field, create it and load structure */
3051 new_conv_info = wmem_alloc(wmem_file_scope(), sizeof(struct _new_conv_info));
3052 new_conv_info->data1 = value1;
3054 /* create the conversation for the dynamic server address and port */
3055 /* NOTE: The second address and port values don't matter because the */
3056 /* NO_ADDR2 and NO_PORT2 options are set. */
3058 /* First check if a conversation already exists for this
3061 conversation = find_conversation(pinfo->num,
3062 &server_src_addr, 0, protocol,
3063 server_src_port, 0, NO_ADDR2 | NO_PORT_B);
3064 /* If there is no such conversation, or if there is one but for
3065 someone else's protocol then we just create a new conversation
3066 and assign our protocol to it.
3068 if ( (conversation == NULL) ||
3069 (conversation->dissector_handle != sub_dissector_handle) ) {
3070 conversation = conversation_new(pinfo->num,
3071 &server_src_addr, 0, protocol,
3072 server_src_port, 0, new_conv_info, NO_ADDR2 | NO_PORT2);
3074 /* set the dissector for the new conversation */
3075 conversation_set_dissector(conversation, sub_dissector_handle);
3078 2.5 Per-packet information.
3080 Information can be stored for each data packet that is processed by the
3081 dissector. The information is added with the p_add_proto_data function and
3082 retrieved with the p_get_proto_data function. The data pointers passed into
3083 the p_add_proto_data are not managed by the proto_data routines, however the
3084 data pointer memory scope must match that of the scope parameter.
3085 The two most common use cases for p_add_proto_data/p_get_proto_data are for
3086 persistent data about the packet for the lifetime of the capture (file scope)
3087 and to exchange data between dissectors across a single packet (packet scope).
3088 It is also used to provide packet data for Decode As dialog (packet scope).
3090 These functions are delcared in <epan/proto_data.h>.
3093 p_add_proto_data(wmem_allocator_t *scope, packet_info *pinfo, int proto, guint32 key, void *proto_data)
3095 p_get_proto_data(wmem_allocator_t *scope, packet_info *pinfo, int proto, guint32 key)
3098 scope - Lifetime of the data to be stored, typically wmem_file_scope()
3099 or pinfo->pool (packet scope). Must match scope of data
3101 pinfo - The packet info pointer.
3102 proto - Protocol id returned by the proto_register_protocol call
3103 during initialization
3104 key - key associated with 'proto_data'
3105 proto_data - pointer to the dissector data.
3108 2.6 User Preferences.
3110 If the dissector has user options, there is support for adding these preferences
3111 to a configuration dialog.
3113 You must register the module with the preferences routine with -
3115 module_t *prefs_register_protocol(proto_id, void (*apply_cb)(void))
3117 module_t *prefs_register_protocol_subtree(const char *subtree, int id,
3118 void (*apply_cb)(void));
3121 Where: proto_id - the value returned by "proto_register_protocol()" when
3122 the protocol was registered.
3123 apply_cb - Callback routine that is called when preferences are
3124 applied. It may be NULL, which inhibits the callback.
3125 subtree - grouping preferences tree node name (several protocols can
3126 be grouped under one preferences subtree)
3128 Then you can register the fields that can be configured by the user with these
3131 /* Register a preference with an unsigned integral value. */
3132 void prefs_register_uint_preference(module_t *module, const char *name,
3133 const char *title, const char *description, guint base, guint *var);
3135 /* Register a preference with an Boolean value. */
3136 void prefs_register_bool_preference(module_t *module, const char *name,
3137 const char *title, const char *description, gboolean *var);
3139 /* Register a preference with an enumerated value. */
3140 void prefs_register_enum_preference(module_t *module, const char *name,
3141 const char *title, const char *description, gint *var,
3142 const enum_val_t *enumvals, gboolean radio_buttons)
3144 /* Register a preference with a character-string value. */
3145 void prefs_register_string_preference(module_t *module, const char *name,
3146 const char *title, const char *description, char **var)
3148 /* Register a preference with a file name (string) value.
3149 * File name preferences are basically like string preferences
3150 * except that the GUI gives the user the ability to browse for the
3151 * file. Set for_writing TRUE to show a Save dialog instead of normal Open.
3153 void prefs_register_filename_preference(module_t *module, const char *name,
3154 const char *title, const char *description, char **var,
3155 gboolean for_writing)
3157 /* Register a preference with a range of unsigned integers (e.g.,
3160 void prefs_register_range_preference(module_t *module, const char *name,
3161 const char *title, const char *description, range_t *var,
3164 Where: module - Returned by the prefs_register_protocol routine
3165 name - This is appended to the name of the protocol, with a
3166 "." between them, to construct a name that identifies
3167 the field in the preference file; the name itself
3168 should not include the protocol name, as the name in
3169 the preference file will already have it. Make sure that
3170 only lower-case ASCII letters, numbers, underscores and
3171 dots appear in the preference name.
3172 title - Field title in the preferences dialog
3173 description - Comments added to the preference file above the
3174 preference value and shown as tooltip in the GUI, or NULL
3175 var - pointer to the storage location that is updated when the
3176 field is changed in the preference dialog box. Note that
3177 with string preferences the given pointer is overwritten
3178 with a pointer to a new copy of the string during the
3179 preference registration. The passed-in string may be
3180 freed, but you must keep another pointer to the string
3181 in order to free it.
3182 base - Base that the unsigned integer is expected to be in,
3184 enumvals - an array of enum_val_t structures. This must be
3185 NULL-terminated; the members of that structure are:
3187 a short name, to be used with the "-o" flag - it
3188 should not contain spaces or upper-case letters,
3189 so that it's easier to put in a command line;
3191 a description, which is used in the GUI (and
3192 which, for compatibility reasons, is currently
3193 what's written to the preferences file) - it can
3194 contain spaces, capital letters, punctuation,
3197 the numerical value corresponding to that name
3199 radio_buttons - TRUE if the field is to be displayed in the
3200 preferences dialog as a set of radio buttons,
3201 FALSE if it is to be displayed as an option
3203 max_value - The maximum allowed value for a range (0 is the minimum).
3205 These functions are declared in <epan/prefs.h>.
3207 An example from packet-rtpproxy.c -
3209 proto_rtpproxy = proto_register_protocol ( "Sippy RTPproxy Protocol", "RTPproxy", "rtpproxy");
3213 rtpproxy_module = prefs_register_protocol(proto_rtpproxy, proto_reg_handoff_rtpproxy);
3215 prefs_register_bool_preference(rtpproxy_module, "establish_conversation",
3216 "Establish Media Conversation",
3217 "Specifies that RTP/RTCP/T.38/MSRP/etc streams are decoded based "
3218 "upon port numbers found in RTPproxy answers",
3219 &rtpproxy_establish_conversation);
3221 prefs_register_uint_preference(rtpproxy_module, "reply.timeout",
3222 "RTPproxy reply timeout", /* Title */
3223 "Maximum timeout value in waiting for reply from RTPProxy (in milliseconds).", /* Descr */
3227 This will create preferences "rtpproxy.establish_conversation" and
3228 "rtpproxy.reply.timeout", the first of which is an Boolean and the
3229 second of which is a unsigned integer.
3231 Note that a warning will pop up if you've saved such preference to the
3232 preference file and you subsequently take the code out. The way to make
3233 a preference obsolete is to register it as such:
3235 /* Register a preference that used to be supported but no longer is. */
3236 void prefs_register_obsolete_preference(module_t *module,
3239 2.7 Reassembly/desegmentation for protocols running atop TCP.
3241 There are two main ways of reassembling a Protocol Data Unit (PDU) which
3242 spans across multiple TCP segments. The first approach is simpler, but
3243 assumes you are running atop of TCP when this occurs (but your dissector
3244 might run atop of UDP, too, for example), and that your PDUs consist of a
3245 fixed amount of data that includes enough information to determine the PDU
3246 length, possibly followed by additional data. The second method is more
3247 generic but requires more code and is less efficient.
3249 2.7.1 Using tcp_dissect_pdus().
3251 For the first method, you register two different dissection methods, one
3252 for the TCP case, and one for the other cases. It is a good idea to
3253 also have a dissect_PROTO_common function which will parse the generic
3254 content that you can find in all PDUs which is called from
3255 dissect_PROTO_tcp when the reassembly is complete and from
3256 dissect_PROTO_udp (or dissect_PROTO_other).
3258 To register the distinct dissector functions, consider the following
3259 example, stolen from packet-dns.c:
3261 #include "packet-tcp.h"
3263 dissector_handle_t hartip_tcp_handle;
3264 dissector_handle_t hartip_udp_handle;
3266 hartip_tcp_handle = create_dissector_handle(dissect_hartip_tcp, proto_hartip);
3267 hartip_udp_handle = create_dissector_handle(dissect_hartip_udp, proto_hartip);
3269 dissector_add_uint("udp.port", HARTIP_PORT, hartip_udp_handle);
3270 dissector_add_uint_with_preference("tcp.port", HARTIP_PORT, hartip_tcp_handle);
3272 The dissect_hartip_udp function does very little work and calls
3273 dissect_hartip_common, while dissect_hartip_tcp calls tcp_dissect_pdus with a
3274 reference to a callback which will be called with reassembled data:
3277 dissect_hartip_tcp(tvbuff_t *tvb, packet_info *pinfo, proto_tree *tree,
3280 if (!tvb_bytes_exist(tvb, 0, HARTIP_HEADER_LENGTH))
3283 tcp_dissect_pdus(tvb, pinfo, tree, hartip_desegment, HARTIP_HEADER_LENGTH,
3284 get_dissect_hartip_len, dissect_hartip_pdu, data);
3285 return tvb_reported_length(tvb);
3288 (The dissect_hartip_pdu function acts similarly to dissect_hartip_udp.)
3289 The arguments to tcp_dissect_pdus are:
3291 the tvbuff pointer, packet_info pointer, and proto_tree pointer
3292 passed to the dissector;
3294 a gboolean flag indicating whether desegmentation is enabled for
3297 the number of bytes of PDU data required to determine the length
3300 a routine that takes as arguments a packet_info pointer, a tvbuff
3301 pointer and an offset value representing the offset into the tvbuff
3302 at which a PDU begins, and a void pointer for user data, and should
3303 return the total length of the PDU in bytes (or 0 if more bytes are
3304 needed to determine the message length).
3305 The routine must not throw exceptions (it is guaranteed that the
3306 number of bytes specified by the previous argument to
3307 tcp_dissect_pdus is available, but more data might not be available,
3308 so don't refer to any data past that);
3310 a new_dissector_t routine to dissect the pdu that's passed a tvbuff
3311 pointer, packet_info pointer, proto_tree pointer and a void pointer for
3312 user data, with the tvbuff containing a possibly-reassembled PDU. (The
3313 "reported_length" of the tvbuff will be the length of the PDU);
3315 a void pointer to user data that is passed to the length-determining
3316 routine, and the dissector routine referenced in the previous parameter.
3318 2.7.2 Modifying the pinfo struct.
3320 The second reassembly mode is preferred when the dissector cannot determine
3321 how many bytes it will need to read in order to determine the size of a PDU.
3322 It may also be useful if your dissector needs to support reassembly from
3323 protocols other than TCP.
3325 Your dissect_PROTO will initially be passed a tvbuff containing the payload of
3326 the first packet. It should dissect as much data as it can, noting that it may
3327 contain more than one complete PDU. If the end of the provided tvbuff coincides
3328 with the end of a PDU then all is well and your dissector can just return as
3329 normal. (If it is a new-style dissector, it should return the number of bytes
3330 successfully processed.)
3332 If the dissector discovers that the end of the tvbuff does /not/ coincide with
3333 the end of a PDU, (ie, there is half of a PDU at the end of the tvbuff), it can
3334 indicate this to the parent dissector, by updating the pinfo struct. The
3335 desegment_offset field is the offset in the tvbuff at which the dissector will
3336 continue processing when next called. The desegment_len field should contain
3337 the estimated number of additional bytes required for completing the PDU. Next
3338 time your dissect_PROTO is called, it will be passed a tvbuff composed of the
3339 end of the data from the previous tvbuff together with desegment_len more bytes.
3341 If the dissector cannot tell how many more bytes it will need, it should set
3342 desegment_len=DESEGMENT_ONE_MORE_SEGMENT; it will then be called again as soon
3343 as any more data becomes available. Dissectors should set the desegment_len to a
3344 reasonable value when possible rather than always setting
3345 DESEGMENT_ONE_MORE_SEGMENT as it will generally be more efficient. Also, you
3346 *must not* set desegment_len=1 in this case, in the hope that you can change
3347 your mind later: once you return a positive value from desegment_len, your PDU
3348 boundary is set in stone.
3350 static hf_register_info hf[] = {
3352 {"C String", "c.string", FT_STRING, BASE_NONE, NULL, 0x0,
3358 * Dissect a buffer containing ASCII C strings.
3360 * @param tvb The buffer to dissect.
3361 * @param pinfo Packet Info.
3362 * @param tree The protocol tree.
3363 * @param data Optional data parameter given by parent dissector.
3365 static int dissect_cstr(tvbuff_t * tvb, packet_info * pinfo, proto_tree * tree, void *data _U_)
3368 while(offset < tvb_reported_length(tvb)) {
3369 gint available = tvb_reported_length_remaining(tvb, offset);
3370 gint len = tvb_strnlen(tvb, offset, available);
3373 /* we ran out of data: ask for more */
3374 pinfo->desegment_offset = offset;
3375 pinfo->desegment_len = DESEGMENT_ONE_MORE_SEGMENT;
3376 return (offset + available);
3379 col_set_str(pinfo->cinfo, COL_INFO, "C String");
3381 len += 1; /* Add one for the '\0' */
3384 proto_tree_add_item(tree, hf_cstring, tvb, offset, len,
3387 offset += (guint)len;
3390 /* if we get here, then the end of the tvb coincided with the end of a
3391 string. Happy days. */
3392 return tvb_captured_length(tvb);
3395 This simple dissector will repeatedly return DESEGMENT_ONE_MORE_SEGMENT
3396 requesting more data until the tvbuff contains a complete C string. The C string
3397 will then be added to the protocol tree. Note that there may be more
3398 than one complete C string in the tvbuff, so the dissection is done in a
3401 2.8 Using udp_dissect_pdus().
3403 As noted in section 2.7.1, TCP has an API to dissect its PDU that can handle
3404 a PDU spread across multiple packets or multiple PDUs spread across a single
3405 packet. This section describes a similar mechanism for UDP, but is only
3406 applicable for one or more PDUs in a single packet. If a protocol runs on top
3407 of TCP as well as UDP, a common PDU dissection function can be created for both.
3409 To register the distinct dissector functions, consider the following
3410 example using UDP and TCP dissection, stolen from packet-dnp.c:
3412 #include "packet-tcp.h"
3413 #include "packet-udp.h"
3415 dissector_handle_t dnp3_tcp_handle;
3416 dissector_handle_t dnp3_udp_handle;
3418 dnp3_tcp_handle = create_dissector_handle(dissect_dnp3_tcp, proto_dnp3);
3419 dnp3_udp_handle = create_dissector_handle(dissect_dnp3_udp, proto_dnp3);
3421 dissector_add_uint("tcp.port", TCP_PORT_DNP, dnp3_tcp_handle);
3422 dissector_add_uint("udp.port", UDP_PORT_DNP, dnp3_udp_handle);
3424 Both dissect_dnp3_tcp and dissect_dnp3_udp call tcp_dissect_pdus and
3425 udp_dissect_pdus respectively, with a reference to the same callbacks which
3426 are called to handle PDU data.
3429 dissect_dnp3_udp(tvbuff_t *tvb, packet_info *pinfo, proto_tree *tree, void *data)
3431 return udp_dissect_pdus(tvb, pinfo, tree, DNP_HDR_LEN, dnp3_udp_check_header,
3432 get_dnp3_message_len, dissect_dnp3_message, data);
3436 dissect_dnp3_tcp(tvbuff_t *tvb, packet_info *pinfo, proto_tree *tree, void *data)
3438 if (!check_dnp3_header(tvb, FALSE)) {
3442 tcp_dissect_pdus(tvb, pinfo, tree, TRUE, DNP_HDR_LEN,
3443 get_dnp3_message_len, dissect_dnp3_message, data);
3445 return tvb_captured_length(tvb);
3448 (udp_dissect_pdus has an option of a heuristic check function within it while
3449 tcp_dissect_pdus does not, so it's done outside)
3451 The arguments to udp_dissect_pdus are:
3453 the tvbuff pointer, packet_info pointer, and proto_tree pointer
3454 passed to the dissector;
3456 the number of bytes of PDU data required to determine the length
3459 an optional routine (passing NULL is okay) that takes as arguments a
3460 packet_info pointer, a tvbuff pointer and an offset value representing the
3461 offset into the tvbuff at which a PDU begins, and a void pointer for user
3462 data, and should return TRUE if the packet belongs to the dissector.
3463 The routine must not throw exceptions (it is guaranteed that the
3464 number of bytes specified by the previous argument to
3465 udp_dissect_pdus is available, but more data might not be available,
3466 so don't refer to any data past that);
3468 a routine that takes as arguments a packet_info pointer, a tvbuff
3469 pointer and an offset value representing the offset into the tvbuff
3470 at which a PDU begins, and a void pointer for user data, and should
3471 return the total length of the PDU in bytes. If return value is 0,
3472 it's treated the same as a failed heuristic.
3473 The routine must not throw exceptions (it is guaranteed that the
3474 number of bytes specified by the previous argument to
3475 tcp_dissect_pdus is available, but more data might not be available,
3476 so don't refer to any data past that);
3478 a new_dissector_t routine to dissect the pdu that's passed a tvbuff
3479 pointer, packet_info pointer, proto_tree pointer and a void pointer for
3480 user data, with the tvbuff containing a possibly-reassembled PDU. (The
3481 "reported_length" of the tvbuff will be the length of the PDU);
3483 a void pointer to user data that is passed to the length-determining
3484 routine, and the dissector routine referenced in the previous parameter.
3486 2.9 PINOs (Protocols in name only)
3488 For the typical dissector there is a 1-1 relationship between it and it's
3489 protocol. However, there are times when a protocol needs multiple "names"
3490 because it has multiple dissection functions going into the same dissector
3491 table. The muliple names removes confusion when picking dissection through
3492 Decode As functionality.
3494 Once the "main" protocol name has been created through proto_register_protocol,
3495 additional "pinos" can be created with proto_register_protocol_in_name_only.
3496 These pinos have all of the naming conventions of a protocol, but are stored
3497 separately as to remove confusion from real protocols. "pinos" the main
3498 protocol's properties for things like enable/disable. i.e. If the "main"
3499 protocol has been disabled, all of its pinos will be disabled as well.
3500 Pinos should not have any fields registered with them or heuristic tables
3501 associated with them.
3503 Another use case for pinos is when a protocol contains a TLV design and it
3504 wants to create a dissector table to handle dissection of the "V". Dissector
3505 tables require a "protocol", but the dissection functions for that table
3506 typically aren't a protocol. In this case proto_register_protocol_in_name_only
3507 creates the necessary placeholder for the dissector table. In addition, because
3508 a dissector table exists, "V"s of the TLVs can be dissected outside of the
3509 original dissector file.
3511 2.10 Creating Decode As functionality.
3513 While the Decode As functionality is available through the GUI, the underlying
3514 functionality is controlled by dissectors themselves. To create Decode As
3515 functionality for a dissector, two things are required:
3516 1. A dissector table
3517 2. A series of structures to assist the GUI in how to present the dissector
3520 Consider the following example using IP dissection, stolen from packet-ip.c:
3522 static build_valid_func ip_da_build_value[1] = {ip_value};
3523 static decode_as_value_t ip_da_values = {ip_prompt, 1, ip_da_build_value};
3524 static decode_as_t ip_da = {"ip", "Network", "ip.proto", 1, 0, &ip_da_values, NULL, NULL,
3525 decode_as_default_populate_list, decode_as_default_reset, decode_as_default_change, NULL};
3527 ip_dissector_table = register_dissector_table("ip.proto", "IP protocol", ip_proto, FT_UINT8, BASE_DEC);
3529 register_decode_as(&ip_da);
3531 ip_da_build_value contains all of the function pointers (typically just 1) that
3532 can be used to retrieve the value(s) that go into the dissector table. This is
3533 usually data saved by the dissector during packet dissector with an API like
3534 p_add_proto_data and retrieved in the "value" function with p_get_proto_data.
3536 ip_da_values contains all of the function pointers (typically just 1) that
3537 provide the text explaining the name and use of the value field that will
3538 be passed to the dissector table to change the dissection output.
3540 ip_da pulls everything together including the dissector (protocol) name, the
3541 "layer type" of the dissector, the dissector table name, the function pointer
3542 values as well as handlers for populating, applying and reseting the changes
3543 to the dissector table through Decode As GUI functionality. For dissector
3544 tables that are an integer or string type, the provided "default" handling
3545 functions shown in the example should suffice.
3547 All entries into a dissector table that use Decode As must have a unique
3548 protocol ID. If a protocol wants multiple entries into a dissector table,
3549 a pino should be used (see section 2.9)
3553 The ptvcursor API allows a simpler approach to writing dissectors for
3554 simple protocols. The ptvcursor API works best for protocols whose fields
3555 are static and whose format does not depend on the value of other fields.
3556 However, even if only a portion of your protocol is statically defined,
3557 then that portion could make use of ptvcursors.
3559 The ptvcursor API lets you extract data from a tvbuff, and add it to a
3560 protocol tree in one step. It also keeps track of the position in the
3561 tvbuff so that you can extract data again without having to compute any
3562 offsets --- hence the "cursor" name of the API.
3564 The three steps for a simple protocol are:
3565 1. Create a new ptvcursor with ptvcursor_new()
3566 2. Add fields with multiple calls of ptvcursor_add()
3567 3. Delete the ptvcursor with ptvcursor_free()
3569 ptvcursor offers the possibility to add subtrees in the tree as well. It can be
3570 done in very simple steps :
3571 1. Create a new subtree with ptvcursor_push_subtree(). The old subtree is
3572 pushed in a stack and the new subtree will be used by ptvcursor.
3573 2. Add fields with multiple calls of ptvcursor_add(). The fields will be
3574 added in the new subtree created at the previous step.
3575 3. Pop the previous subtree with ptvcursor_pop_subtree(). The previous
3576 subtree is again used by ptvcursor.
3577 Note that at the end of the parsing of a packet you must have popped each
3578 subtree you pushed. If it's not the case, the dissector will generate an error.
3580 To use the ptvcursor API, include the "ptvcursor.h" file. The PGM dissector
3581 is an example of how to use it. You don't need to look at it as a guide;
3582 instead, the API description here should be good enough.
3584 2.11.1 ptvcursor API.
3587 ptvcursor_new(proto_tree* tree, tvbuff_t* tvb, gint offset)
3588 This creates a new ptvcursor_t object for iterating over a tvbuff.
3589 You must call this and use this ptvcursor_t object so you can use the
3593 ptvcursor_add(ptvcursor_t* ptvc, int hf, gint length, const guint encoding)
3594 This will extract 'length' bytes from the tvbuff and place it in
3595 the proto_tree as field 'hf', which is a registered header_field. The
3596 pointer to the proto_item that is created is passed back to you. Internally,
3597 the ptvcursor advances its cursor so the next call to ptvcursor_add
3598 starts where this call finished. The 'encoding' parameter is relevant for
3599 certain type of fields (See above under proto_tree_add_item()).
3602 ptvcursor_add_ret_uint(ptvcursor_t* ptvc, int hf, gint length, const guint encoding, guint32 *retval);
3603 Like ptvcursor_add, but returns uint value retreived
3606 ptvcursor_add_ret_int(ptvcursor_t* ptvc, int hf, gint length, const guint encoding, gint32 *retval);
3607 Like ptvcursor_add, but returns int value retreived
3610 ptvcursor_add_ret_string(ptvcursor_t* ptvc, int hf, gint length, const guint encoding, wmem_allocator_t *scope, const guint8 **retval);
3611 Like ptvcursor_add, but returns string retreived
3614 ptvcursor_add_ret_boolean(ptvcursor_t* ptvc, int hf, gint length, const guint encoding, gboolean *retval);
3615 Like ptvcursor_add, but returns boolean value retreived
3618 ptvcursor_add_no_advance(ptvcursor_t* ptvc, int hf, gint length, const guint encoding)
3619 Like ptvcursor_add, but does not advance the internal cursor.
3622 ptvcursor_advance(ptvcursor_t* ptvc, gint length)
3623 Advances the internal cursor without adding anything to the proto_tree.
3626 ptvcursor_free(ptvcursor_t* ptvc)
3627 Frees the memory associated with the ptvcursor. You must call this
3628 after your dissection with the ptvcursor API is completed.
3632 ptvcursor_push_subtree(ptvcursor_t* ptvc, proto_item* it, gint ett_subtree)
3633 Pushes the current subtree in the tree stack of the cursor, creates a new
3634 one and sets this one as the working tree.
3637 ptvcursor_pop_subtree(ptvcursor_t* ptvc);
3638 Pops a subtree in the tree stack of the cursor
3641 ptvcursor_add_with_subtree(ptvcursor_t* ptvc, int hfindex, gint length,
3642 const guint encoding, gint ett_subtree);
3643 Adds an item to the tree and creates a subtree.
3644 If the length is unknown, length may be defined as SUBTREE_UNDEFINED_LENGTH.
3645 In this case, at the next pop, the item length will be equal to the advancement
3646 of the cursor since the creation of the subtree.
3649 ptvcursor_add_text_with_subtree(ptvcursor_t* ptvc, gint length,
3650 gint ett_subtree, const char* format, ...);
3651 Add a text node to the tree and create a subtree.
3652 If the length is unknown, length may be defined as SUBTREE_UNDEFINED_LENGTH.
3653 In this case, at the next pop, the item length will be equal to the advancement
3654 of the cursor since the creation of the subtree.
3656 2.11.2 Miscellaneous functions.
3659 ptvcursor_tvbuff(ptvcursor_t* ptvc)
3660 Returns the tvbuff associated with the ptvcursor.
3663 ptvcursor_current_offset(ptvcursor_t* ptvc)
3664 Returns the current offset.
3667 ptvcursor_tree(ptvcursor_t* ptvc)
3668 Returns the proto_tree associated with the ptvcursor.
3671 ptvcursor_set_tree(ptvcursor_t* ptvc, proto_tree *tree)
3672 Sets a new proto_tree for the ptvcursor.
3675 ptvcursor_set_subtree(ptvcursor_t* ptvc, proto_item* it, gint ett_subtree);
3676 Creates a subtree and adds it to the cursor as the working tree but does
3677 not save the old working tree.
3681 A protocol dissector may be called in 2 different ways - with, or
3682 without a non-null "tree" argument.
3684 If the proto_tree argument is null, Wireshark does not need to use
3685 the protocol tree information from your dissector, and therefore is
3686 passing the dissector a null "tree" argument so that it doesn't
3687 need to do work necessary to build the protocol tree.
3689 In the interest of speed, if "tree" is NULL, avoid building a
3690 protocol tree and adding stuff to it, or even looking at any packet
3691 data needed only if you're building the protocol tree, if possible.
3693 Note, however, that you must fill in column information, create
3694 conversations, reassemble packets, do calls to "expert" functions,
3695 build any other persistent state needed for dissection, and call
3696 subdissectors regardless of whether "tree" is NULL or not.
3698 This might be inconvenient to do without doing most of the
3699 dissection work; the routines for adding items to the protocol tree
3700 can be passed a null protocol tree pointer, in which case they'll
3701 return a null item pointer, and "proto_item_add_subtree()" returns
3702 a null tree pointer if passed a null item pointer, so, if you're
3703 careful not to dereference any null tree or item pointers, you can
3704 accomplish this by doing all the dissection work. This might not
3705 be as efficient as skipping that work if you're not building a
3706 protocol tree, but if the code would have a lot of tests whether
3707 "tree" is null if you skipped that work, you might still be better
3708 off just doing all that work regardless of whether "tree" is null
3711 Note also that there is no guarantee, the first time the dissector is
3712 called, whether "tree" will be null or not; your dissector must work
3713 correctly, building or updating whatever state information is
3714 necessary, in either case.
3717 * Editor modelines - https://www.wireshark.org/tools/modelines.html
3722 * indent-tabs-mode: nil
3725 * vi: set shiftwidth=4 tabstop=8 expandtab:
3726 * :indentSize=4:tabSize=8:noTabs=true: