files:
- README.binarytrees - fast access to large data collections
+- README.heuristic - what are heuristic dissectors and how to write them
- README.malloc - how to obtain "memory leak free" memory
- README.plugins - how to "pluginize" a dissector
- README.request_response_tracking - how to track req./resp. times and such
unsigned integers.
When printing or displaying the values of 64-bit integral data types,
-don't assume use "%lld", "%llu", "%llx", or "%llo" - not all platforms
+don't use "%lld", "%llu", "%llx", or "%llo" - not all platforms
support "%ll" for printing 64-bit integral data types. Instead, for
GLib routines, and routines that use them, such as all the routines in
Wireshark that take format arguments, use G_GINT64_MODIFIER, for example:
"_write()", etc..
Do not use "open()", "rename()", "mkdir()", "stat()", "unlink()", "remove()",
-"fopen()", "freopen()" directly. Instead use "eth_open()", "eth_rename()",
-"eth_mkdir()", "eth_stat()", "eth_unlink()", "eth_remove()", "eth_fopen()",
-"eth_freopen()": these wrapper functions change the path and file name from
+"fopen()", "freopen()" directly. Instead use "ws_open()", "ws_rename()",
+"ws_mkdir()", "ws_stat()", "ws_unlink()", "ws_remove()", "ws_fopen()",
+"ws_freopen()": these wrapper functions change the path and file name from
UTF8 to UTF16 on Windows allowing the functions to work correctly when the
path or file name contain non-ASCII characters.
-When opening a file with "eth_fopen()", "eth_freopen()", or "eth_fdopen()", if
+When opening a file with "ws_fopen()", "ws_freopen()", or "ws_fdopen()", if
the file contains ASCII text, use "r", "w", "a", and so on as the open mode
- but if it contains binary data, use "rb", "wb", and so on. On
Windows, if a file is opened in a text mode, writing a byte with the
carriage return/line feed).
In addition, that also means that when opening or creating a binary
-file, you must use "eth_open()" (with O_CREAT and possibly O_TRUNC if the
+file, you must use "ws_open()" (with O_CREAT and possibly O_TRUNC if the
file is to be created if it doesn't exist), and OR in the O_BINARY flag.
That flag is not present on most, if not all, UNIX systems, so you must
also do
unaligned access for you, and will, on at least some platforms, cause
the program to be terminated.
-Wireshark supports both platforms with GLib 1.2[.x]/GTK+ 1.2[.x] and GLib
-2.x/GTK+ 1.3[.x] and 2.x. If at all possible, either use only
-mechanisms that are present in GLib 1.2[.x] and GTK+ 1.2[.x], use #if's
-to conditionally use older or newer mechanisms depending on the platform
-on which Wireshark is being built, or, if the code in GLib or GTK+ that
-implements that mechanism will build with GLib 1.2[.x]/GTK+ 1.2[.x],
-conditionally include that code as part of the Wireshark source and use
-the included version with GLib 1.2[.x] or GTK+ 1.2[.x]. In particular,
-if the GLib 2.x or GTK+ 2.x mechanism indicates that a routine is
-deprecated and shouldn't be used in new code, and that it was renamed in
-GLib 2.x or GTK+ 2.x and the new name should be used, disregard that and
-use the old name - it'll still work with GLib 2.x or GTK+ 2.x, but will
-also work with GLib 1.2[.x] and GTK+ 1.2[.x].
+Wireshark supports platforms with GLib 2.4[.x]/GTK+ 2.4[.x] or newer.
+If a Glib/GTK+ mechanism is available only in Glib/GTK+ versions
+newer than 2.4/2.4 then use "#if GTK_CHECK_VERSION(...)" to conditionally
+compile code using that mechanism.
When different code must be used on UN*X and Win32, use a #if or #ifdef
that tests _WIN32, not WIN32. Try to write code portably whenever
...
#define MAX_BUFFER 1024
buffer=ep_alloc(MAX_BUFFER);
- buffer[0]=0;
+ buffer[0]='\0';
...
g_snprintf(buffer, MAX_BUFFER, ...
don't have to worry about free()ing them explicitly in order to not leak memory.
Please read README.malloc.
-When using g_strsplit() from glib, place an #include <epan/ws_strsplit.h> at
-the top of your file. This file will leave in place g_strsplit() when using
-GTK/GLib v2 and replace it with GLib v2 code when compiling for GTK/GLib 1.
-This is necessary because the GLib v1 version of g_strsplit is known to be
-buggy. In either case, you will still use the g_strsplit() function name
-as usual in your code.
-
1.1.3 Robustness.
Wireshark is not guaranteed to read only network traces that contain correctly-
-formed packets. Wireshark is commonly used is to track down networking
+formed packets. Wireshark is commonly used to track down networking
problems, and the problems might be due to a buggy protocol implementation
sending out bad packets.
/* add an item to the subtree, see section 1.6 for more information */
proto_tree_add_item(PROTOABBREV_tree,
- hf_PROTOABBREV_FIELDABBREV, tvb, offset, len, FALSE)
+ hf_PROTOABBREV_FIELDABBREV, tvb, offset, len, FALSE);
/* Continue adding tree items to process the packet here */
proto_reg_handoff_PROTOABBREV);
/* Register a sample preference */
- prefs_register_bool_preference(PROTOABBREV_module, "showHex",
+ prefs_register_bool_preference(PROTOABBREV_module, "show_hex",
"Display numbers in Hex",
"Enable to display numerical values in hexadecimal.",
&gPREF_HEX);
If you perform registration functions which are dependent upon
prefs the you should de-register everything which was associated
with the previous settings and re-register using the new prefs
- settings here. In general this means you need to keep track of what
- value the preference had at the time you registered using a local
- static in this function. ie.
+ settings here. In general this means you need to keep track of
+ the PROTOABBREV_handle and the value the preference had at the time
+ you registered. The PROTOABBREV_handle value and the value of the preference
+ can be saved using local statics in this function (proto_reg_handoff). ie.
+ static PROTOABBREV_handle;
static int currentPort = -1;
+ ...
+
if (currentPort != -1) {
dissector_delete("tcp.port", currentPort, PROTOABBREV_handle);
}
FIELDTYPE FT_NONE, FT_BOOLEAN, FT_UINT8, FT_UINT16, FT_UINT24,
FT_UINT32, FT_UINT64, FT_INT8, FT_INT16, FT_INT24, FT_INT32,
FT_INT64, FT_FLOAT, FT_DOUBLE, FT_ABSOLUTE_TIME,
- FT_RELATIVE_TIME, FT_STRING, FT_STRINGZ, FT_UINT_STRING,
- FT_ETHER, FT_BYTES, FT_IPv4, FT_IPv6, FT_IPXNET,
+ FT_RELATIVE_TIME, FT_STRING, FT_STRINGZ, FT_EBCDIC,
+ FT_UINT_STRING, FT_ETHER, FT_BYTES, FT_IPv4, FT_IPv6, FT_IPXNET,
FT_FRAMENUM, FT_PROTOCOL, FT_GUID, FT_OID
FIELDBASE BASE_NONE, BASE_DEC, BASE_HEX, BASE_OCT, BASE_DEC_HEX,
- BASE_HEX_DEC, BASE_RANGE_STRING
+ BASE_HEX_DEC, BASE_RANGE_STRING, BASE_CUSTOM
FIELDCONVERT VALS(x), RVALS(x), TFS(x), NULL
BITMASK Usually 0x0 unless using the TFS(x) field conversion.
-FIELDDESCR A brief description of the field.
+FIELDDESCR A brief description of the field, or NULL.
PARENT_SUBFIELD Lower level protocol field used for lookup, i.e. "tcp.port"
ID_VALUE Lower level protocol field value that identifies this protocol
For example the TCP or UDP port number
register itself with the lower level dissector, or if the protocol dissector
wants/needs to expose code to other subdissectors.
-The dissector must declared as exactly as follows in the file
+The dissector must be declared exactly as follows in the file
packet-PROTOABBREV.h:
int
The "tvb" argument to a dissector points to a buffer containing the raw
data to be analyzed by the dissector; for example, for a protocol
running atop UDP, it contains the UDP payload (but not the UDP header,
-or any protocol headers above it). A tvbuffer is a opaque data
+or any protocol headers above it). A tvbuffer is an opaque data
structure, the internal data structures are hidden and the data must be
-access via the tvbuffer accessors.
+accessed via the tvbuffer accessors.
The accessors are:
+Bit accessors for a maximum of 8-bits, 16-bits 32-bits and 64-bits:
+
+guint8 tvb_get_bits8(tvbuff_t *tvb, gint bit_offset, gint no_of_bits);
+guint16 tvb_get_bits16(tvbuff_t *tvb, gint bit_offset, gint no_of_bits,gboolean little_endian);
+guint32 tvb_get_bits32(tvbuff_t *tvb, gint bit_offset, gint no_of_bits,gboolean little_endian);
+guint64 tvb_get_bits64(tvbuff_t *tvb, gint bit_offset, gint no_of_bits,gboolean little_endian);
+
Single-byte accessor:
guint8 tvb_get_guint8(tvbuff_t*, gint offset);
guint8 *tvb_get_ephemeral_stringz(tvbuff_t *tvb, gint offset, gint *lengthp);
Returns a null-terminated buffer, allocated with "g_malloc()",
-containing data from the specified tvbuff, starting with at the
+containing data from the specified tvbuff, starting at the
specified offset, and containing all characters from the tvbuff up to
and including a terminating null character in the tvbuff. "*lengthp"
will be set to the length of the string, including the terminating null.
dissected.
-guint8 *tvb_fake_unicode(tvbuff_t*, gint offset, gint length);
-guint8 *tvb_get_ephemeral_faked_unicode(tvbuff_t*, gint offset, gint length);
+guint8 *tvb_fake_unicode(tvbuff_t*, gint offset, gint length, gboolean little_endian);
+guint8 *tvb_get_ephemeral_faked_unicode(tvbuff_t*, gint offset, gint length, gboolean little_endian);
Converts a 2-byte unicode string to an ASCII string.
Returns a null-terminated buffer containing data from the specified
The reason that tvb_get_ptr() might have to allocate a copy of its data
only occurs with TVBUFF_COMPOSITES, data that spans multiple tvbuffers.
-If the user request a pointer to a range of bytes that spans the member
+If the user requests a pointer to a range of bytes that span the member
tvbuffs that make up the TVBUFF_COMPOSITE, the data will have to be
copied to another memory region to assure that all the bytes are
contiguous.
1.5.9 The col_set_time function.
-The 'col_set_time' function takes a nstime value as it's third argument.
+The 'col_set_time' function takes an nstime value as its third argument.
This nstime value is a relative value and will be added as such to the
column. The fourth argument is the filtername holding this value. This
way, rightclicking on the column makes it possible to build a filter
/* abbrev */ "frame" );
A header field is also registered with its name and abbreviation, but
-information about the its data type is needed. It helps to look at
+information about its data type is needed. It helps to look at
the header_field_info struct to see what information is expected:
struct header_field_info {
- char *name;
- char *abbrev;
+ const char *name;
+ const char *abbrev;
enum ftenum type;
int display;
- void *strings;
- guint bitmask;
- char *blurb;
-
- int id; /* calculated */
- int parent;
- int bitshift; /* calculated */
+ const void *strings;
+ guint32 bitmask;
+ const char *blurb;
+ .....
};
name
types, are to be used for text strings,
not raw binary data.
FT_STRINGZ A NUL-terminated string of characters.
+ FT_EBCDIC A string of characters, not necessarily
+ NUL-terminated, but possibly NUL-padded.
+ The data from the packet is converted from
+ EBCDIC to ASCII before displaying to the user.
FT_UINT_STRING A counted string of characters, consisting
- of a count (represented as an integral
- value) followed immediately by the
- specified number of characters.
+ of a count (represented as an integral value,
+ of width given in the proto_tree_add_item()
+ call) followed immediately by that number of
+ characters.
FT_ETHER A six octet string displayed in
Ethernet-address format.
FT_BYTES A string of bytes with arbitrary values;
display
-------
The display field has a couple of overloaded uses. This is unfortunate,
-but since we're C as an application programming language, this sometimes
+but since we're using C as an application programming language, this sometimes
makes for cleaner programs. Right now I still think that overloading
this variable was okay.
BASE_HEX,
BASE_OCT,
BASE_DEC_HEX,
- BASE_HEX_DEC
+ BASE_HEX_DEC,
+ BASE_CUSTOM
BASE_DEC, BASE_HEX, and BASE_OCT are decimal, hexadecimal, and octal,
respectively. BASE_DEC_HEX and BASE_HEX_DEC display value in two bases
-(the 1st representation followed by the 2nd in parenthesis)
+(the 1st representation followed by the 2nd in parenthesis).
+
+BASE_CUSTOM allows one to specify a callback function pointer that will
+format the value. The function pointer of the same type as defined by
+custom_fmt_func_t in epan/proto.h, specifically:
+
+ void func(gchar *, guint32);
+
+The first argument is a pointer to a buffer of the ITEM_LABEL_LENGTH size
+and the second argument is the value to be formatted.
For FT_BOOLEAN fields that are also bitfields, 'display' is used to tell
the proto_tree how wide the parent bitfield is. With integers this is
leave only the bits needed to make the field when ANDed with a value.
The proto_tree routines will calculate 'bitshift' automatically
from 'bitmask', by finding the rightmost set bit in the bitmask.
+This shift is applied before applying string mapping functions or
+filtering.
If the field is not a bitfield, then bitmask should be set to 0.
blurb
-----
-This is a string giving a proper description of the field.
-It should be at least one grammatically complete sentence.
+This is a string giving a proper description of the field. It should be
+at least one grammatically complete sentence, or NULL in which case the
+name field is used.
It is meant to provide a more detailed description of the field than the
name alone provides. This information will be used in the man page, and
in a future GUI display-filter creation tool. We might also add tooltips
proto_tree_add_item(tree, id, tvb, start, length, little_endian);
proto_item*
- proto_tree_add_item_hidden(tree, id, tvb, start, length, little_endian);
+ proto_tree_add_bits_item(tree, id, tvb, bit_offset, no_of_bits, little_endian);
+
+ proto_item *
+ proto_tree_add_bits_ret_val(tree, id, tvb, bit_offset, no_of_bits, return_value, little_endian);
proto_item*
proto_tree_add_none_format(tree, id, tvb, start, length, format, ...);
proto_item *
proto_tree_add_bytes(tree, id, tvb, start, length, start_ptr);
- proto_item *
- proto_tree_add_bytes_hidden(tree, id, tvb, start, length, start_ptr);
-
proto_item *
proto_tree_add_bytes_format(tree, id, tvb, start, length, start_ptr,
format, ...);
proto_item *
proto_tree_add_time(tree, id, tvb, start, length, value_ptr);
- proto_item *
- proto_tree_add_time_hidden(tree, id, tvb, start, length, value_ptr);
-
proto_item *
proto_tree_add_time_format(tree, id, tvb, start, length, value_ptr,
format, ...);
proto_item *
proto_tree_add_ipxnet(tree, id, tvb, start, length, value);
- proto_item *
- proto_tree_add_ipxnet_hidden(tree, id, tvb, start, length, value);
-
proto_item *
proto_tree_add_ipxnet_format(tree, id, tvb, start, length, value,
format, ...);
proto_item *
proto_tree_add_ipv4(tree, id, tvb, start, length, value);
- proto_item *
- proto_tree_add_ipv4_hidden(tree, id, tvb, start, length, value);
-
proto_item *
proto_tree_add_ipv4_format(tree, id, tvb, start, length, value,
format, ...);
proto_item *
proto_tree_add_ipv6(tree, id, tvb, start, length, value_ptr);
- proto_item *
- proto_tree_add_ipv6_hidden(tree, id, tvb, start, length, value_ptr);
-
proto_item *
proto_tree_add_ipv6_format(tree, id, tvb, start, length, value_ptr,
format, ...);
proto_item *
proto_tree_add_ether(tree, id, tvb, start, length, value_ptr);
- proto_item *
- proto_tree_add_ether_hidden(tree, id, tvb, start, length, value_ptr);
-
proto_item *
proto_tree_add_ether_format(tree, id, tvb, start, length, value_ptr,
format, ...);
proto_item *
proto_tree_add_string(tree, id, tvb, start, length, value_ptr);
- proto_item *
- proto_tree_add_string_hidden(tree, id, tvb, start, length, value_ptr);
-
proto_item *
proto_tree_add_string_format(tree, id, tvb, start, length, value_ptr,
format, ...);
proto_item *
proto_tree_add_boolean(tree, id, tvb, start, length, value);
- proto_item *
- proto_tree_add_boolean_hidden(tree, id, tvb, start, length, value);
-
proto_item *
proto_tree_add_boolean_format(tree, id, tvb, start, length, value,
format, ...);
proto_item *
proto_tree_add_float(tree, id, tvb, start, length, value);
- proto_item *
- proto_tree_add_float_hidden(tree, id, tvb, start, length, value);
-
proto_item *
proto_tree_add_float_format(tree, id, tvb, start, length, value,
format, ...);
proto_item *
proto_tree_add_double(tree, id, tvb, start, length, value);
- proto_item *
- proto_tree_add_double_hidden(tree, id, tvb, start, length, value);
-
proto_item *
proto_tree_add_double_format(tree, id, tvb, start, length, value,
format, ...);
proto_item *
proto_tree_add_uint(tree, id, tvb, start, length, value);
- proto_item *
- proto_tree_add_uint_hidden(tree, id, tvb, start, length, value);
-
proto_item *
proto_tree_add_uint_format(tree, id, tvb, start, length, value,
format, ...);
proto_item *
proto_tree_add_int(tree, id, tvb, start, length, value);
- proto_item *
- proto_tree_add_int_hidden(tree, id, tvb, start, length, value);
-
proto_item *
proto_tree_add_int_format(tree, id, tvb, start, length, value,
format, ...);
proto_item *
proto_tree_add_guid(tree, id, tvb, start, length, value_ptr);
- proto_item *
- proto_tree_add_guid_hidden(tree, id, tvb, start, length, value_ptr);
-
proto_item *
proto_tree_add_guid_format(tree, id, tvb, start, length, value_ptr,
format, ...);
proto_item *
proto_tree_add_oid(tree, id, tvb, start, length, value_ptr);
- proto_item *
- proto_tree_add_oid_hidden(tree, id, tvb, start, length, value_ptr);
-
proto_item *
proto_tree_add_oid_format(tree, id, tvb, start, length, value_ptr,
format, ...);
proto_tree_add_bitmask(tree, tvb, start, header, ett, **fields,
little_endian);
+ proto_item *
+ proto_tree_add_bitmask_text(proto_tree *tree, tvbuff_t *tvb,
+ guint offset, guint len, const char *name, const char *fallback,
+ gint ett, const int **fields, gboolean little_endian, int flags);
+
The 'tree' argument is the tree to which the item is to be added. The
'tvb' argument is the tvbuff from which the item's value is being
extracted; the 'start' argument is the offset from the beginning of that
tvbuff of the item being added, and the 'length' argument is the length,
-in bytes, of the item.
+in bytes, of the item, bit_offset is the offset in bits and no_of_bits
+is the lenght in bits.
The length of some items cannot be determined until the item has been
dissected; to add such an item, add it with a length of -1, and, when the
the high nibble of the byte ("sna.th.fid == 0xf0") as was necessary
in the past.
-proto_tree_add_item_hidden()
-----------------------------
-proto_tree_add_item_hidden is used to add fields and values to a tree,
-but not show them on a GUI tree.
-
-NOTE that creating hidden fields is actually quite a bad idea from a UI design
-perspective because the user (someone who did not write nor has ever seen the
-code) has no way of knowing that hidden fields are there to be filtered on
-thus defeating the whole purpose of putting them there. A Better Way might
-be to add the fields (that might otherwise be hidden) to a subtree where they
-won't be seen unless the user opens the subtree--but they can be found if the
-user wants.
-
-NOTE, too, that all of the proto_tree_add_*_hidden() APIs are deprecated:
-instead of using them, use add the item using proto_tree_add_item() and then
-make it hidden using PROTO_ITEM_SET_HIDDEN().
-
-One use for hidden fields (which would be better implemented using visible
-fields in a subtree) follows: The caller may want a value to be
-included in a tree so that the packet can be filtered on this field, but
-the representation of that field in the tree is not appropriate. An
-example is the token-ring routing information field (RIF). The best way
-to show the RIF in a GUI is by a sequence of ring and bridge numbers.
-Rings are 3-digit hex numbers, and bridges are single hex digits:
-
- RIF: 001-A-013-9-C0F-B-555
-
-In the case of RIF, the programmer should use a field with no value and
-use proto_tree_add_none_format() to build the above representation. The
-programmer can then add the ring and bridge values, one-by-one, with
-proto_tree_add_item_hidden() so that the user can then filter on or
-search for a particular ring or bridge. Here's a skeleton of how the
-programmer might code this.
-
- char *rif;
- rif = create_rif_string(...);
-
- proto_tree_add_none_format(tree, hf_tr_rif_label, ..., "RIF: %s", rif);
-
- for(i = 0; i < num_rings; i++) {
- proto_tree_add_item_hidden(tree, hf_tr_rif_ring, ..., FALSE);
- }
- for(i = 0; i < num_rings - 1; i++) {
- proto_tree_add_item_hidden(tree, hf_tr_rif_bridge, ..., FALSE);
- }
-
-The logical tree has these items:
-
- hf_tr_rif_label, text="RIF: 001-A-013-9-C0F-B-555", value = NONE
- hf_tr_rif_ring, hidden, value=0x001
- hf_tr_rif_bridge, hidden, value=0xA
- hf_tr_rif_ring, hidden, value=0x013
- hf_tr_rif_bridge, hidden, value=0x9
- hf_tr_rif_ring, hidden, value=0xC0F
- hf_tr_rif_bridge, hidden, value=0xB
- hf_tr_rif_ring, hidden, value=0x555
+proto_tree_add_bits_item()
+--------------------------
+Adds a number of bits to the protocol tree which does not have to be byte aligned.
+The offset and length is in bits.
+Output format:
-GUI or print code will not display the hidden fields, but a display
-filter or "packet grep" routine will still see the values. The possible
-filter is then possible:
+..10 1010 10.. .... "value" (formated as FT_ indicates).
- tr.rif_ring eq 0x013
+proto_tree_add_bits_ret_val()
+-----------------------------
+Works in the same way but alo returns the value of the read bits.
proto_tree_add_protocol_format()
--------------------------------
proto_tree_add_protocol_format is used to add the top-level item for the
-protocol when the dissector routines wants complete control over how the
+protocol when the dissector routine wants complete control over how the
field and value will be represented on the GUI tree. The ID value for
the protocol is passed in as the "id" argument; the rest of the
arguments are a "printf"-style format and any arguments for that format.
For proto_tree_add_oid(), the 'value_ptr' argument is a pointer to an
ASN.1 Object Identifier.
-proto_tree_add_bytes_hidden()
-proto_tree_add_time_hidden()
-proto_tree_add_ipxnet_hidden()
-proto_tree_add_ipv4_hidden()
-proto_tree_add_ipv6_hidden()
-proto_tree_add_ether_hidden()
-proto_tree_add_string_hidden()
-proto_tree_add_boolean_hidden()
-proto_tree_add_float_hidden()
-proto_tree_add_double_hidden()
-proto_tree_add_uint_hidden()
-proto_tree_add_int_hidden()
-proto_tree_add_guid_hidden()
-proto_tree_add_oid_hidden()
-----------------------------
-These routines add fields and values to a tree, but don't show them in the GUI
-tree. They are used for the same reason that proto_tree_add_item_hidden() is
-used (and they should not be used for the same reasons).
-
proto_tree_add_bytes_format()
proto_tree_add_time_format()
proto_tree_add_ipxnet_format()
proto_tree_add_oid_format()
----------------------------
These routines are used to add items to the protocol tree when the
-dissector routines wants complete control over how the field and value
+dissector routine wants complete control over how the field and value
will be represented on the GUI tree. The argument giving the value is
the same as the corresponding proto_tree_add_XXX() function; the rest of
the arguments are a "printf"-style format and any arguments for that
------------------------------------
These routines are used to add items to the protocol tree when the
-dissector routines wants complete control over how the value will be
+dissector routine wants complete control over how the value will be
represented on the GUI tree. The argument giving the value is the same
as the corresponding proto_tree_add_XXX() function; the rest of the
arguments are a "printf"-style format and any arguments for that format.
<label> would be a label giving what information about the subtree is
available without dissecting any of the data in the subtree.
-Note that an exception might thrown when trying to extract the values of
+Note that an exception might be thrown when trying to extract the values of
the items used to set the label, if not all the bytes of the item are
available. Thus, one should create the item with text that is as
meaningful as possible, and set it or append additional information to
-it as the values needed to supply that information is extracted.
+it as the values needed to supply that information are extracted.
proto_tree_add_text_valist()
----------------------------
variable-length list of arguments to add a text item to the protocol
tree.
-proto_tree_add_bitmask()
-------------------------
+proto_tree_add_bitmask() and proto_tree_add_bitmask_text()
+----------------------------------------------------------
This function provides an easy to use and convenient helper function
to manage many types of common bitmasks that occur in protocols.
...
{ &hf_scsi_inq_peripheral,
{"Peripheral", "scsi.inquiry.preipheral", FT_UINT8, BASE_HEX,
- NULL, 0, "", HFILL}},
+ NULL, 0, NULL, HFILL}},
{ &hf_scsi_inq_qualifier,
{"Qualifier", "scsi.inquiry.qualifier", FT_UINT8, BASE_HEX,
- VALS (scsi_qualifier_val), 0xE0, "", HFILL}},
+ VALS (scsi_qualifier_val), 0xE0, NULL, HFILL}},
...
Which provides very pretty dissection of this one byte bitmask.
+PROTO_ITEM_SET_HIDDEN()
+-----------------------
+PROTO_ITEM_SET_HIDDEN is used to hide fields, which have already been added
+to the tree, from being visible in the displayed tree.
+
+NOTE that creating hidden fields is actually quite a bad idea from a UI design
+perspective because the user (someone who did not write nor has ever seen the
+code) has no way of knowing that hidden fields are there to be filtered on
+thus defeating the whole purpose of putting them there. A Better Way might
+be to add the fields (that might otherwise be hidden) to a subtree where they
+won't be seen unless the user opens the subtree--but they can be found if the
+user wants.
+
+One use for hidden fields (which would be better implemented using visible
+fields in a subtree) follows: The caller may want a value to be
+included in a tree so that the packet can be filtered on this field, but
+the representation of that field in the tree is not appropriate. An
+example is the token-ring routing information field (RIF). The best way
+to show the RIF in a GUI is by a sequence of ring and bridge numbers.
+Rings are 3-digit hex numbers, and bridges are single hex digits:
+
+ RIF: 001-A-013-9-C0F-B-555
+
+In the case of RIF, the programmer should use a field with no value and
+use proto_tree_add_none_format() to build the above representation. The
+programmer can then add the ring and bridge values, one-by-one, with
+proto_tree_add_item() and hide them with PROTO_ITEM_SET_HIDDEN() so that the
+user can then filter on or search for a particular ring or bridge. Here's a
+skeleton of how the programmer might code this.
+
+ char *rif;
+ rif = create_rif_string(...);
+
+ proto_tree_add_none_format(tree, hf_tr_rif_label, ..., "RIF: %s", rif);
+
+ for(i = 0; i < num_rings; i++) {
+ proto_item *pi;
+
+ pi = proto_tree_add_item(tree, hf_tr_rif_ring, ..., FALSE);
+ PROTO_ITEM_SET_HIDDEN(pi);
+ }
+ for(i = 0; i < num_rings - 1; i++) {
+ proto_item *pi;
+
+ pi = proto_tree_add_item(tree, hf_tr_rif_bridge, ..., FALSE);
+ PROTO_ITEM_SET_HIDDEN(pi);
+ }
+
+The logical tree has these items:
+
+ hf_tr_rif_label, text="RIF: 001-A-013-9-C0F-B-555", value = NONE
+ hf_tr_rif_ring, hidden, value=0x001
+ hf_tr_rif_bridge, hidden, value=0xA
+ hf_tr_rif_ring, hidden, value=0x013
+ hf_tr_rif_bridge, hidden, value=0x9
+ hf_tr_rif_ring, hidden, value=0xC0F
+ hf_tr_rif_bridge, hidden, value=0xB
+ hf_tr_rif_ring, hidden, value=0x555
+
+GUI or print code will not display the hidden fields, but a display
+filter or "packet grep" routine will still see the values. The possible
+filter is then possible:
+
+ tr.rif_ring eq 0x013
+
+The proto_tree_add_bitmask_text() function is an extended version of
+the proto_tree_add_bitmask() function. In addition, it allows to:
+- Provide a leading text (e.g. "Flags: ") that will appear before
+ the comma-separated list of field values
+- Provide a fallback text (e.g. "None") that will be appended if
+ no fields warranted a change to the top-level title.
+- Using flags, specify which fields will affect the top-level title.
+
+There are the following flags defined:
+
+ BMT_NO_APPEND - the title is taken "as-is" from the 'name' argument.
+ BMT_NO_INT - only boolean flags are added to the title.
+ BMT_NO_FALSE - boolean flags are only added to the title if they are set.
+ BMT_NO_TFS - only add flag name to the title, do not use true_false_string
+
+The proto_tree_add_bitmask() behavior can be obtained by providing
+both 'name' and 'fallback' arguments as NULL, and a flags of
+(BMT_NO_FALSE|BMT_NO_TFS).
1.7 Utility routines.
protocol spec says it has to be" - protocol specs do not prevent invalid
packets from being put onto a network or into a purported packet capture
file), you must check whether 'match_strval()' returns NULL, and arrange
-that its return value not be dereferenced if it's NULL. In particular,
-don't use it in a call to generate a COL_INFO line for a frame such as
-
- col_add_fstr(COL_INFO, ", %s", match_strval(val, table));
-
-unless is it certain that 'val' is in 'table'.
-
-'val_to_str()' can be used to generate a string for values not found in
-the table:
+that its return value not be dereferenced if it's NULL. 'val_to_str()'
+can be used to generate a string for values not found in the table:
gchar*
val_to_str(guint32 val, const value_string *vs, const char *fmt)
'vs', 'val_to_str' will return the corresponding string; otherwise, it
will use 'fmt' as an 'sprintf'-style format, with 'val' as an argument,
to generate a string, and will return a pointer to that string.
-(Currently, it has three 64-byte static buffers, and cycles through
-them; this permits the results of up to three calls to 'val_to_str' to
-be passed as arguments to a routine using those strings.)
+You can use it in a call to generate a COL_INFO line for a frame such as
+
+ col_add_fstr(COL_INFO, ", %s", val_to_str(val, table, "Unknown %d"));
1.7.2 match_strrval and rval_to_str.
1.11 Submitting code for your new dissector.
+ - VERIFY that your dissector code does not use prohibited or deprecated APIs
+ as follows:
+ perl <wireshark_root>/tools/checkAPIs.pl <source-filename(s)>
+
- TEST YOUR DISSECTOR BEFORE SUBMITTING IT.
Use fuzz-test.sh and/or randpkt against your dissector. These are
described at <http://wiki.wireshark.org/FuzzTesting>.
- Edit the diff file - remove any changes unrelated to your new dissector,
e.g. changes in config.nmake
- - Send a note with the attached diff file requesting its inclusion to
- <mailto:wireshark-dev[AT]wireshark.org>. You can also use this procedure for
- providing patches to your dissector or any other part of Wireshark.
+ - Submit a bug report to the Wireshark bug database, found at
+ <http://bugs.wireshark.org>, qualified as an enhancement and attach your
+ diff file there. Set the review request flag to '?' so it will pop up in
+ the patch review list.
- Create a Wiki page on the protocol at <http://wiki.wireshark.org>.
A template is provided so it is easy to setup in a consistent style.
2.2 Following "conversations".
-In wireshark a conversation is defined as a series of data packet between two
+In wireshark a conversation is defined as a series of data packets between two
address:port combinations. A conversation is not sensitive to the direction of
the packet. The same conversation will be returned for a packet bound from
ServerA:1000 to ClientA:2000 and the packet from ClientA:2000 to ServerA:1000.
2.2.1 The conversation_init function.
-This is an internal routine for the conversation code. As such the you
+This is an internal routine for the conversation code. As such you
will not have to call this routine. Just be aware that this routine is
called at the start of each capture and before the packets are filtered
with a display filter. The routine will destroy all stored
2.2.7 Using timestamps relative to the conversation
-There is a framework to calculate timestams relative to the start of the
+There is a framework to calculate timestamps relative to the start of the
conversation. First of all the timestamp of the first packet that has been
seen in the conversation must be kept in the protocol data to be able
to calculate the timestamp of the current packet relative to the start
The ts_prev value should only be set during the first run through the
packets (ie pinfo->fd->flags.visited is false).
-Next step is to use the per packet information (described in section 2.5)
+Next step is to use the per-packet information (described in section 2.5)
to keep the calculated delta timestamp, as it can only be calculated
on the first run through the packets. This is because a packet can be
selected in random order once the whole file has been read.
Last but not least, there MUST be a preference in each dissector that
uses conversation timestamps that makes it possible to enable and
-dissable the calculation of conversation timestamps. The main argument
+disable the calculation of conversation timestamps. The main argument
for this is that a higher level conversation is able to overwrite
the values of lowel level conversations in these two columns. Being
able to actively select which protocols may overwrite the conversation
-timestamp columns give the user the power to control these columns.
-(A second reason is that conversation timestamps use the per packet
+timestamp columns gives the user the power to control these columns.
+(A second reason is that conversation timestamps use the per-packet
data structure which uses additional memory, which should be avoided
if these timestamps are not needed)
/* the GMemChunk base structure */
static GMemChunk *my_vals = NULL;
-/* Registered protocol number
+/* Registered protocol number */
static int my_proto = -1;
/* the local variables in the dissector */
conversation_t *conversation;
-my_entry_t *data_ptr
+my_entry_t *data_ptr;
/* look up the conversation */
Sometimes a dissector has determined that a new conversation is needed that
starts at a specific frame number, when a capture session encompasses multiple
conversation that reuse the same src/dest ip/port pairs. You can use the
-compare the conversation->setup_frame returned by find_conversation with
+conversation->setup_frame returned by find_conversation with
pinfo->fd->num to determine whether or not there already exists a conversation
that starts at the specific frame number.
Before we create these conversations or assign a dissector to them we should
first check that the conversation does not already exist and if it exists
whether it is registered to our protocol or not.
-We should do this because is uncommon but it does happen that multiple
+We should do this because it is uncommon but it does happen that multiple
different protocols can use the same socketpair during different stages of
an application cycle. By keeping track of the frame number a conversation
was started in wireshark can still tell these different protocols apart.
(See packet-tftp.c and packet-snmp.c for examples of this)
There are two support routines that will allow the second port and/or
-address to be set latter.
+address to be set later.
conversation_set_port2( conversation_t *conv, guint32 port);
conversation_set_addr2( conversation_t *conv, address addr);
These routines will change the second address or port for the
conversation. So, the server port conversation will be converted into a
more complete conversation definition. Don't use these routines if you
-want create a conversation between the server and client and retain the
+want to create a conversation between the server and client and retain the
server port definition, you must create a new conversation.
conversation_set_dissector(conversation, sub_dissector_handle);
}
-2.5 Per packet information.
+2.5 Per-packet information.
Information can be stored for each data packet that is processed by the
dissector. The information is added with the p_add_proto_data function and
Where: proto_id - the value returned by "proto_register_protocol()" when
the protocol was registered
- apply_cb - Callback routine that is call when preferences are applied
+ apply_cb - Callback routine that is called when preferences are applied
Then you can register the fields that can be configured by the user with these
2.8.1 ptvcursor API.
ptvcursor_t*
-ptvcursor_new(proto_tree*, tvbuff_t*, gint offset)
+ptvcursor_new(proto_tree* tree, tvbuff_t* tvb, gint offset)
This creates a new ptvcursor_t object for iterating over a tvbuff.
You must call this and use this ptvcursor_t object so you can use the
ptvcursor API.
proto_item*
-ptvcursor_add(ptvcursor_t*, int hf, gint length, gboolean endianness)
+ptvcursor_add(ptvcursor_t* ptvc, int hf, gint length, gboolean endianness)
This will extract 'length' bytes from the tvbuff and place it in
the proto_tree as field 'hf', which is a registered header_field. The
pointer to the proto_item that is created is passed back to you. Internally,
FT_UINT* and FT_INT* fields.
proto_item*
-ptvcursor_add_no_advance(ptvcursor_t*, int hf, gint length, gboolean endianness)
+ptvcursor_add_no_advance(ptvcursor_t* ptvc, int hf, gint length, gboolean endianness)
Like ptvcursor_add, but does not advance the internal cursor.
void
-ptvcursor_advance(ptvcursor_t*, gint length)
+ptvcursor_advance(ptvcursor_t* ptvc, gint length)
Advances the internal cursor without adding anything to the proto_tree.
void
-ptvcursor_free(ptvcursor_t*)
+ptvcursor_free(ptvcursor_t* ptvc)
Frees the memory associated with the ptvcursor. You must call this
after your dissection with the ptvcursor API is completed.
proto_tree*
-ptvcursor_push_subtree(ptvcursor_t *ptvc, proto_item *it, gint ett_subtree)
+ptvcursor_push_subtree(ptvcursor_t* ptvc, proto_item* it, gint ett_subtree)
Pushes the current subtree in the tree stack of the cursor, creates a new
- one and sets this one as the working tree.
+one and sets this one as the working tree.
void
-ptvcursor_pop_subtree(ptvcursor_t *ptvc);
+ptvcursor_pop_subtree(ptvcursor_t* ptvc);
Pops a subtree in the tree stack of the cursor
proto_tree*
-ptvcursor_add_with_subtree(ptvcursor_t * ptvc, int hfindex, gint length,
+ptvcursor_add_with_subtree(ptvcursor_t* ptvc, int hfindex, gint length,
gboolean little_endian, gint ett_subtree);
Adds an item to the tree and creates a subtree.
- If the length is unknown, length may be defined as
- SUBTREE_UNDEFINED_LENGTH. In this case, at the next pop, the item length
- will be equal to the advancement of the cursor since the creation of the
- subtree.
-
-proto_tree *
-ptvcursor_add_text_with_subtree(ptvcursor_t * ptvc, gint length,
- gint ett_subtree, const char *format, ...);
- Add a text node to the tree and create a subtree
- If the length is unknown, length may be defined as
- SUBTREE_UNDEFINED_LENGTH. In this case, at the next pop, the item length
- will be equal to the advancement of the cursor since the creation of the
- subtree.
+If the length is unknown, length may be defined as SUBTREE_UNDEFINED_LENGTH.
+In this case, at the next pop, the item length will be equal to the advancement
+of the cursor since the creation of the subtree.
+
+proto_tree*
+ptvcursor_add_text_with_subtree(ptvcursor_t* ptvc, gint length,
+ gint ett_subtree, const char* format, ...);
+ Add a text node to the tree and create a subtree.
+If the length is unknown, length may be defined as SUBTREE_UNDEFINED_LENGTH.
+In this case, at the next pop, the item length will be equal to the advancement
+of the cursor since the creation of the subtree.
2.8.2 Miscellaneous functions.
tvbuff_t*
-ptvcursor_tvbuff(ptvcursor_t*)
- returns the tvbuff associated with the ptvcursor
+ptvcursor_tvbuff(ptvcursor_t* ptvc)
+ Returns the tvbuff associated with the ptvcursor.
gint
-ptvcursor_current_offset(ptvcursor_t*)
- returns the current offset
+ptvcursor_current_offset(ptvcursor_t* ptvc)
+ Returns the current offset.
proto_tree*
-ptvcursor_tree(ptvcursor_t*)
- returns the proto_tree associated with the ptvcursor
+ptvcursor_tree(ptvcursor_t* ptvc)
+ Returns the proto_tree associated with the ptvcursor.
void
-ptvcursor_set_tree(ptvcursor_t*, proto_tree *)
- sets a new proto_tree for the ptvcursor
+ptvcursor_set_tree(ptvcursor_t* ptvc, proto_tree *tree)
+ Sets a new proto_tree for the ptvcursor.
+
+proto_tree*
+ptvcursor_set_subtree(ptvcursor_t* ptvc, proto_item* it, gint ett_subtree);
+ Creates a subtree and adds it to the cursor as the working tree but does
+not save the old working tree.
git.samba.org / obnox / wireshark / wip.git / blobdiff