forked from osmocom/wireshark
from Micheal Duigou: add some doxygen tags and some changes to README.developer
svn path=/trunk/; revision=13725
This commit is contained in:
Ulf Lamping
parent
801e9dd35e
commit
e378098855
|
|
@ -430,10 +430,10 @@ protocol, if any.
|
|||
Usually, you will put your newly created dissector file into the directory
|
||||
epan/dissectors, just like all the other packet-....c files already in there.
|
||||
|
||||
Also, please remind to add your dissector file to the corresponding makefile,
|
||||
described in chapter "1.9 Editing Makefile.common to add your dissector" below.
|
||||
Also, please add your dissector file to the corresponding makefile,
|
||||
described in section "1.9 Editing Makefile.common to add your dissector" below.
|
||||
|
||||
Dissectors that use the dissector registration to tell a lower level
|
||||
Dissectors that use the dissector registration to register with a lower level
|
||||
dissector don't need to define a prototype in the .h file. For other
|
||||
dissectors the main dissector routine should have a prototype in a header
|
||||
file whose name is "packet-", followed by the abbreviated name for the
|
||||
|
|
@ -460,7 +460,7 @@ version of the file is currently checked out.
|
|||
|
||||
When creating a new file, it is fine to just write "$Id$" as RCS will
|
||||
automatically fill in the identifier at the time the file will be added to the
|
||||
CVS repository (checked in).
|
||||
SVN repository (checked in).
|
||||
|
||||
------------------------------------Cut here------------------------------------
|
||||
/* packet-PROTOABBREV.c
|
||||
|
|
@ -505,6 +505,7 @@ CVS repository (checked in).
|
|||
#include <glib.h>
|
||||
|
||||
#include <epan/packet.h>
|
||||
#include <epan/prefs.h>
|
||||
|
||||
/* IF PROTO exposes code to other dissectors, then it must be exported
|
||||
in a header file. If not, a header file is not needed at all. */
|
||||
|
|
@ -514,6 +515,9 @@ CVS repository (checked in).
|
|||
static int proto_PROTOABBREV = -1;
|
||||
static int hf_PROTOABBREV_FIELDABBREV = -1;
|
||||
|
||||
/* Global sample preference ("controls" display of numbers) */
|
||||
static gboolean gPREF_HEX = FALSE;
|
||||
|
||||
/* Initialize the subtree pointers */
|
||||
static gint ett_PROTOABBREV = -1;
|
||||
|
||||
|
|
@ -530,13 +534,17 @@ dissect_PROTOABBREV(tvbuff_t *tvb, packet_info *pinfo, proto_tree *tree)
|
|||
if (check_col(pinfo->cinfo, COL_PROTOCOL))
|
||||
col_set_str(pinfo->cinfo, COL_PROTOCOL, "PROTOABBREV");
|
||||
|
||||
/* This field shows up as the "Info" column in the display; you should make
|
||||
it, if possible, summarize what's in the packet, so that a user looking
|
||||
/* This field shows up as the "Info" column in the display; you should use
|
||||
it, if possible, to summarize what's in the packet, so that a user looking
|
||||
at the list of packets can tell what type of packet it is. See section 1.5
|
||||
for more information.
|
||||
|
||||
If you are setting it to a constant string, use "col_set_str()", as
|
||||
it's more efficient than the other "col_set_XXX()" calls.
|
||||
Before changing the contents of a column you should make sure the column is
|
||||
active by calling "check_col(pinfo->cinfo, COL_*)". If it is not active
|
||||
don't bother setting it.
|
||||
|
||||
If you are setting the column to a constant string, use "col_set_str()",
|
||||
as it's more efficient than the other "col_set_XXX()" calls.
|
||||
|
||||
If you're setting it to a string you've constructed, or will be
|
||||
appending to the column later, use "col_add_str()".
|
||||
|
|
@ -567,7 +575,7 @@ dissect_PROTOABBREV(tvbuff_t *tvb, packet_info *pinfo, proto_tree *tree)
|
|||
In this mode, Ethereal is only interested in the way protocols
|
||||
interact, protocol conversations are created, packets are reassembled
|
||||
and handed over to higher-level protocol dissectors.
|
||||
This way Ethereal does not build a so-called "protocol tree".
|
||||
In this mode Ethereal does not build a so-called "protocol tree".
|
||||
|
||||
(b) Detailed dissection
|
||||
|
||||
|
|
@ -635,6 +643,7 @@ dissect_PROTOABBREV(tvbuff_t *tvb, packet_info *pinfo, proto_tree *tree)
|
|||
void
|
||||
proto_register_PROTOABBREV(void)
|
||||
{
|
||||
module_t *PROTOABBREV_module;
|
||||
|
||||
/* Setup list of header fields See Section 1.6.1 for details*/
|
||||
static hf_register_info hf[] = {
|
||||
|
|
@ -657,21 +666,61 @@ proto_register_PROTOABBREV(void)
|
|||
/* Required function calls to register the header fields and subtrees used */
|
||||
proto_register_field_array(proto_PROTOABBREV, hf, array_length(hf));
|
||||
proto_register_subtree_array(ett, array_length(ett));
|
||||
|
||||
/* Register preferences module (See Section 2.6 for more on preferences) */
|
||||
PROTOABBREV_module = prefs_register_protocol(proto_PROTOABBREV, proto_reg_handoff_PROTOABBREV);
|
||||
|
||||
/* Register a sample preference */
|
||||
prefs_register_bool_preference(PROTOABBREV_module, "showHex",
|
||||
"Display numbers in Hex",
|
||||
"Enable to display numerical values in hexidecimal.",
|
||||
&gPREF_HEX );
|
||||
}
|
||||
|
||||
|
||||
/* If this dissector uses sub-dissector registration add a registration routine.
|
||||
This format is required because a script is used to find these routines and
|
||||
create the code that calls these routines.
|
||||
This exact format is required because a script is used to find these routines
|
||||
and create the code that calls these routines.
|
||||
|
||||
This function is also called by preferences whenever "Apply" is pressed
|
||||
(see prefs_register_protocol above) so it should accommodate being called
|
||||
more than once.
|
||||
*/
|
||||
void
|
||||
proto_reg_handoff_PROTOABBREV(void)
|
||||
{
|
||||
static gboolean inited = FALSE;
|
||||
|
||||
if( inited ) {
|
||||
|
||||
dissector_handle_t PROTOABBREV_handle;
|
||||
|
||||
PROTOABBREV_handle = create_dissector_handle(dissect_PROTOABBREV,
|
||||
proto_PROTOABBREV);
|
||||
dissector_add("PARENT_SUBFIELD", ID_VALUE, PROTOABBREV_handle);
|
||||
|
||||
inited = TRUE;
|
||||
}
|
||||
|
||||
/*
|
||||
If you perform registration functions which are dependant 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.
|
||||
|
||||
static int currentPort = -1;
|
||||
|
||||
if( -1 != currentPort ) {
|
||||
dissector_delete( "tcp.port", currentPort, PROTOABBREV_handle);
|
||||
}
|
||||
|
||||
currentPort = gPortPref;
|
||||
|
||||
dissector_add("tcp.port", currentPort, PROTOABBREV_handle);
|
||||
|
||||
*/
|
||||
}
|
||||
|
||||
------------------------------------Cut here------------------------------------
|
||||
|
|
@ -724,8 +773,8 @@ This is only needed if the dissector doesn't use self-registration to
|
|||
register itself with the lower level dissector, or if the protocol dissector
|
||||
wants/needs to expose code to other subdissectors.
|
||||
|
||||
The dissector has the following header that must be placed into
|
||||
packet-PROTOABBREV.h.
|
||||
The dissector must declared as exactly as follows in the file
|
||||
packet-PROTOABBREV.h:
|
||||
|
||||
void
|
||||
dissect_PROTOABBREV(tvbuff_t *tvb, packet_info *pinfo, proto_tree *tree);
|
||||
|
|
@ -733,7 +782,7 @@ dissect_PROTOABBREV(tvbuff_t *tvb, packet_info *pinfo, proto_tree *tree);
|
|||
|
||||
1.4.2 Extracting data from packets.
|
||||
|
||||
NOTE: See the README.tvbuff for more details
|
||||
NOTE: See the README.tvbuff file for more details
|
||||
|
||||
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
|
||||
|
|
@ -1899,7 +1948,7 @@ 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.)
|
||||
|
||||
|
||||
1.8 Calling Other Dissector
|
||||
1.8 Calling Other Dissectors
|
||||
|
||||
NOTE: This is discussed in the README.tvbuff file. For more
|
||||
information on tvbuffers consult that file.
|
||||
|
|
@ -1976,10 +2025,28 @@ the 'epan/dissectors' directory, so that it's included when release source
|
|||
tarballs are built (otherwise, the source in the release tarballs won't
|
||||
compile).
|
||||
|
||||
1.10 Using the CVS source code tree.
|
||||
1.10 Using the SVN source code tree.
|
||||
|
||||
See <http://www.ethereal.com/development.html#source>
|
||||
|
||||
1.11 Submitting code for your new dissector.
|
||||
|
||||
- Subscribe to <mailto:ethereal-dev@ethereal.com> by sending an email to
|
||||
<mailto:ethereal-dev-request@ethereal.com?body="help"> or visiting
|
||||
<http://www.ethereal.com/lists/>.
|
||||
|
||||
- 'svn add' all the files of your new dissector.
|
||||
|
||||
- 'svn diff' the workspace and save the result to a file.
|
||||
|
||||
- Send the diff file along with a note requesting it's inclusion to
|
||||
<mailto:ethereal-dev@ethereal.com>. You can also use this procedure for
|
||||
providing patches to your dissector or any other part of ethereal.
|
||||
|
||||
- If you find that you are contributing a lot to ethereal on an ongoing
|
||||
basis you can request to become a committer which will allow you to commit
|
||||
files to subversion directly.
|
||||
|
||||
2. Advanced dissector topics.
|
||||
|
||||
2.1 ??
|
||||
|
|
@ -2255,11 +2322,11 @@ information for each request the dissector has an internal hash table based
|
|||
upon the conversation index and values inside the request packets.
|
||||
|
||||
|
||||
/* in the dissector routine */
|
||||
/* in the dissector routine */
|
||||
|
||||
/* to find a request value, first lookup conversation to get index */
|
||||
/* then used the conversation index, and request data to find data */
|
||||
/* in the local hash table */
|
||||
/* to find a request value, first lookup conversation to get index */
|
||||
/* then used the conversation index, and request data to find data */
|
||||
/* in the local hash table */
|
||||
|
||||
conversation = find_conversation(&pinfo->src, &pinfo->dst, pinfo->ptype,
|
||||
pinfo->srcport, pinfo->destport, 0);
|
||||
|
|
@ -2296,7 +2363,7 @@ upon the conversation index and values inside the request packets.
|
|||
2.3 Dynamic conversation dissector registration
|
||||
|
||||
|
||||
NOTE: This sections assumes that all information is available to
|
||||
NOTE: This sections assumes that all information is available to
|
||||
create a complete conversation, source port/address and
|
||||
destination port/address. If either the destination port or
|
||||
address is know, see section 2.4 Dynamic server port dissector
|
||||
|
|
@ -2527,17 +2594,17 @@ integer and the second of which is a Boolean.
|
|||
|
||||
2.7 Reassembly/desegmentation for protocols running atop TCP
|
||||
|
||||
There are two main ways of reassembling PDUs spanning across multiple
|
||||
TCP segmentss. The first one is simpler, but assumes you are running
|
||||
atop of TCP when this occurs (but your dissector might run atop of UDP,
|
||||
too, for example), and that your PDUs consist of a fixed amount of data
|
||||
that includes enough information to determine the PDU length, possibly
|
||||
followed by additional data. The second one is more generic but
|
||||
requires more code and is less efficient.
|
||||
There are two main ways of reassembling a Protocol Data Unit (PDU) which
|
||||
spans across multiple TCP segments. The first approach is simpler, but
|
||||
assumes you are running atop of TCP when this occurs (but your dissector
|
||||
might run atop of UDP, too, for example), and that your PDUs consist of a
|
||||
fixed amount of data that includes enough information to determine the PDU
|
||||
length, possibly followed by additional data. The second method is more
|
||||
generic but requires more code and is less efficient.
|
||||
|
||||
For the first method, you register two different dissection methods, one
|
||||
for the TCP case, and one for the other cases. It is a good idea to
|
||||
have a dissect_PROTO_common function which will parse the generic
|
||||
also have a dissect_PROTO_common function which will parse the generic
|
||||
content that you can find in all PDUs which is called from
|
||||
dissect_PROTO_tcp when the reassembly is complete and from
|
||||
dissect_PROTO_udp (or dissect_PROTO_other).
|
||||
|
|
|
|||
|
|
@ -9,10 +9,31 @@
|
|||
#define XCEPT_GROUP_ETHEREAL 1
|
||||
|
||||
/* Ethereal's exceptions */
|
||||
#define BoundsError 1 /* Index is out of range */
|
||||
#define ReportedBoundsError 2 /* Index is beyond reported length (not cap_len) */
|
||||
#define TypeError 3 /* During dfilter parsing */
|
||||
#define DissectorError 4 /* A bug was detected in a dissector */
|
||||
|
||||
/**
|
||||
Index is out of range.
|
||||
An attempt was made to read past the end of a buffer.
|
||||
**/
|
||||
#define BoundsError 1
|
||||
|
||||
/**
|
||||
Index is beyond reported length (not cap_len)
|
||||
An attempt was made to read past the logical end of a buffer. This
|
||||
differs from a BoundsError in that the parent protocol established a
|
||||
limit past which this dissector should not process in the buffer and that
|
||||
limit was execeeded.
|
||||
**/
|
||||
#define ReportedBoundsError 2
|
||||
|
||||
/**
|
||||
During dfilter parsing
|
||||
**/
|
||||
#define TypeError 3
|
||||
|
||||
/**
|
||||
A bug was detected in a dissector
|
||||
**/
|
||||
#define DissectorError 4
|
||||
|
||||
/* Usage:
|
||||
*
|
||||
|
|
|
|||
|
|
@ -90,6 +90,10 @@ typedef struct true_false_string {
|
|||
char *false_string;
|
||||
} true_false_string;
|
||||
|
||||
/**
|
||||
* A default set of true/false strings that dissectors can use for
|
||||
* FT_BOOLEAN header fields.
|
||||
**/
|
||||
extern const true_false_string flags_set_truth;
|
||||
|
||||
extern void packet_init(void);
|
||||
|
|
|
|||
|
|
@ -889,7 +889,7 @@ proto_item_fill_label(field_info *fi, gchar *label_str);
|
|||
|
||||
|
||||
/** Register a new protocol.
|
||||
@param name the name of the new protocol
|
||||
@param name the full name of the new protocol
|
||||
@param short_name abbreviated name of the new protocol
|
||||
@param filter_name protocol name used for a display filter string
|
||||
@return the new protocol handle */
|
||||
|
|
|
|||
Loading…
Reference in New Issue