diff options
author | Guy Harris <guy@alum.mit.edu> | 2000-03-03 06:58:28 +0000 |
---|---|---|
committer | Guy Harris <guy@alum.mit.edu> | 2000-03-03 06:58:28 +0000 |
commit | bcb954c51dfb94677e8d3d9364cca44b982c30ef (patch) | |
tree | f4a5bc289fff0d57e5bbab6cc7a2bd6eb6ab0de6 | |
parent | 9490a8ead6eb2f8b981dc37176d3e025365ca1cd (diff) |
Document "proto_tree_add_notext()", "proto_item_set_len()", and
"proto_item_set_text()".
svn path=/trunk/; revision=1688
-rw-r--r-- | doc/README.developer | 69 |
1 files changed, 63 insertions, 6 deletions
diff --git a/doc/README.developer b/doc/README.developer index c865c8c3a9..0011199f22 100644 --- a/doc/README.developer +++ b/doc/README.developer @@ -1,4 +1,4 @@ -$Id: README.developer,v 1.6 2000/03/03 06:39:10 guy Exp $ +$Id: README.developer,v 1.7 2000/03/03 06:58:28 guy Exp $ This file is a HOWTO for Ethereal developers. It describes how to start coding a protocol dissector and the use some of the important functions and variables @@ -46,7 +46,7 @@ code inside is needed only if you are using the "snprintf()" function. -The "$Id: README.developer,v 1.6 2000/03/03 06:39:10 guy Exp $" in the comment will be updated by CVS when the file is +The "$Id: README.developer,v 1.7 2000/03/03 06:58:28 guy Exp $" in the comment will be updated by CVS when the file is checked in; it will allow the RCS "ident" command to report which version of the file is currently checked out. @@ -55,7 +55,7 @@ version of the file is currently checked out. * Routines for PROTONAME dissection * Copyright 2000, YOUR_NAME <YOUR_EMAIL_ADDRESS> * - * $Id: README.developer,v 1.6 2000/03/03 06:39:10 guy Exp $ + * $Id: README.developer,v 1.7 2000/03/03 06:58:28 guy Exp $ * * Ethereal - Network traffic analyzer * By Gerald Combs <gerald@unicom.net> @@ -256,7 +256,7 @@ to "PROTOABBREV": 'col_add_fstr' takes a 'printf'-style format string as its third argument, and 'printf'-style arguments corresponding to '%' format -values in that string as its subsequent arguments. For example, to set +items in that string as its subsequent arguments. For example, to set the "Info" field to "<XXX> request, <N> bytes", where "reqtype" is a string containing the type of the request in the packet and "n" is an unsigned integer containing the number of bytes in the request: @@ -608,6 +608,7 @@ Also be sure to use the handy array_length() macro found in packet.h to have the compiler compute the array length for you at compile time. 1.5.2 Adding Items and Values to the Protocol Tree. + A protocol item is added to an existing protocol tree with one of a handful of proto_tree_add_item*() funtions. @@ -634,8 +635,8 @@ array of pointers to "gint" variables to hold the subtree type values to in your "register" routine, just as you register the protocol and the fields for that protocol. -There are now 4 functions that the programmer can use to add either -protocol or field labels to the proto_tree: +There are 5 functions that the programmer can use to add either protocol +or field labels to the proto_tree: proto_item* proto_tree_add_item(tree, id, start, length, value); @@ -650,6 +651,27 @@ protocol or field labels to the proto_tree: proto_item* proto_tree_add_text(tree, start, length, format, ...); + proto_item* + proto_tree_add_notext(tree, start, length); + +The 'tree' argument is the tree to which the item is to be added. The +'start' argument is the offset from the beginning of the frame (not the +offset from the beginning of the part of the packet belonging to this +protocol, but the offset from the beginning of the frame as a whole) of +the item being added, and the 'length' argument is the length, in bytes, +of the item. + +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 0, and, when the +dissection is complete (or fails because the packet is too short), set +the length with 'proto_item_set_len()': + + void + proto_item_set_len(ti, length); + +The "ti" argument is the value returned by the call that added the item +to the tree, and the "length" argument is the length of the item. + proto_tree_add_item() --------------------- The first function, proto_tree_add_item, is used when you wish to do no @@ -774,6 +796,41 @@ protocols and fields. Otherwise we would have had to cripple Ethereal's functionality while we converted all the old-style proto_tree calls to the new-style proto_tree calls. +This can also be used for items with subtrees, which may not have values +themselves - the items in the subtree are the ones with values. + +proto_tree_add_notext() +----------------------- +The fifth function, proto_tree_add_notext(), is used to add an item to +the logical tree that will have only a label, and no value (so it is not +searchable in the display filter process), but that doesn't yet have a +label, either. This is for items where the value is to be filled in +later. This is typically used for an item with a subtree, where the +label is to contain a summary of the subtree, with the values of some of +the fields in the subtree shown in the label of the item for the subtree +as a whole; the item can be created as a placeholder, with the label +added when the dissection is complete - and, if the dissection doesn't +complete because the packet is too short and not all the required fields +are present, the label could be set to something indicating this. + +The text is set by 'proto_item_set_text()': + + void + proto_tree_set_text(proto_item *ti, ...); + +which takes as an argument the value returned by +'proto_tree_add_notext()', a 'printf'-style format string, and a set of +arguments corresponding to '%' format items in that string. For +example, early in the dissection, one might do: + + ti = proto_tree_add_notext(tree, offset, length); + +and later do + + proto_item_set_text(ti, "%s: %s", type, value); + +after the "type" and "value" fields have been extracted and dissected. + 1.6 Editing Makefile.am and Makefile.nmake to add your dissector. To arrange that your dissector will be built as part of Ethereal, you |