forked from osmocom/wireshark
REAME.dissector: remove double spaces.
Change-Id: I87b9748bb14b148cfc7ffdc5fd5d9059fa2d2299 Reviewed-on: https://code.wireshark.org/review/33522 Reviewed-by: Anders Broman <a.broman58@gmail.com>
This commit is contained in:
parent
e44d4e740e
commit
14553ee358
|
@ -51,7 +51,7 @@ add to the protocol tree, and work with registered header fields.
|
||||||
|
|
||||||
Wireshark requires certain things when setting up a protocol dissector.
|
Wireshark requires certain things when setting up a protocol dissector.
|
||||||
We provide basic skeleton code for a dissector that you can copy to a new file
|
We provide basic skeleton code for a dissector that you can copy to a new file
|
||||||
and fill in. Your dissector should follow the naming convention of "packet-"
|
and fill in. Your dissector should follow the naming convention of "packet-"
|
||||||
followed by the abbreviated name for the protocol. It is recommended that where
|
followed by the abbreviated name for the protocol. It is recommended that where
|
||||||
possible you keep to the IANA abbreviated name for the protocol, if there is
|
possible you keep to the IANA abbreviated name for the protocol, if there is
|
||||||
one, or a commonly-used abbreviation for the protocol, if any.
|
one, or a commonly-used abbreviation for the protocol, if any.
|
||||||
|
@ -84,7 +84,7 @@ need to include additional headers.
|
||||||
In the skeleton sample code the following strings should be substituted with
|
In the skeleton sample code the following strings should be substituted with
|
||||||
your information.
|
your information.
|
||||||
|
|
||||||
YOUR_NAME Your name, of course. You do want credit, don't you?
|
YOUR_NAME Your name, of course. You do want credit, don't you?
|
||||||
It's the only payment you will receive....
|
It's the only payment you will receive....
|
||||||
YOUR_EMAIL_ADDRESS Keep those cards and letters coming.
|
YOUR_EMAIL_ADDRESS Keep those cards and letters coming.
|
||||||
PROTONAME The name of the protocol; this is displayed in the
|
PROTONAME The name of the protocol; this is displayed in the
|
||||||
|
@ -125,8 +125,8 @@ FIELDDISPLAY --For FT_UINT{8,16,24,32,40,48,56,64} and
|
||||||
filters for the field in question.
|
filters for the field in question.
|
||||||
|
|
||||||
BASE_NO_DISPLAY_VALUE will just display the field name with
|
BASE_NO_DISPLAY_VALUE will just display the field name with
|
||||||
no value. It is intended for byte arrays (FT_BYTES or
|
no value. It is intended for byte arrays (FT_BYTES or
|
||||||
FT_UINT_BYTES) or header fields above a subtree. The
|
FT_UINT_BYTES) or header fields above a subtree. The
|
||||||
value will still be filterable, just not displayed.
|
value will still be filterable, just not displayed.
|
||||||
|
|
||||||
--For FT_UINT16:
|
--For FT_UINT16:
|
||||||
|
@ -192,7 +192,7 @@ BITMASK Used to mask a field not 8-bit aligned or with a size other
|
||||||
FIELDDESCR A brief description of the field, or NULL. [Please do not use ""].
|
FIELDDESCR A brief description of the field, or NULL. [Please do not use ""].
|
||||||
|
|
||||||
If, for example, PROTONAME is "Internet Bogosity Discovery Protocol",
|
If, for example, PROTONAME is "Internet Bogosity Discovery Protocol",
|
||||||
PROTOSHORTNAME would be "IBDP", and PROTOABBREV would be "ibdp". Try to
|
PROTOSHORTNAME would be "IBDP", and PROTOABBREV would be "ibdp". Try to
|
||||||
conform with IANA names.
|
conform with IANA names.
|
||||||
|
|
||||||
1.3 The dissector and the data it receives.
|
1.3 The dissector and the data it receives.
|
||||||
|
@ -218,7 +218,7 @@ NOTE: See the file /epan/tvbuff.h for more details.
|
||||||
The "tvb" argument to a dissector points to a buffer containing the raw
|
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
|
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,
|
running atop UDP, it contains the UDP payload (but not the UDP header,
|
||||||
or any protocol headers above it). A tvbuffer is an 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
|
structure, the internal data structures are hidden and the data must be
|
||||||
accessed via the tvbuffer accessors.
|
accessed via the tvbuffer accessors.
|
||||||
|
|
||||||
|
@ -373,7 +373,7 @@ guint32 tvb_get_ipv4(tvbuff_t *tvb, const gint offset);
|
||||||
void tvb_get_ipv6(tvbuff_t *tvb, const gint offset, ws_in6_addr *addr);
|
void tvb_get_ipv6(tvbuff_t *tvb, const gint offset, ws_in6_addr *addr);
|
||||||
|
|
||||||
NOTE: IPv4 addresses are not to be converted to host byte order before
|
NOTE: IPv4 addresses are not to be converted to host byte order before
|
||||||
being passed to "proto_tree_add_ipv4()". You should use "tvb_get_ipv4()"
|
being passed to "proto_tree_add_ipv4()". You should use "tvb_get_ipv4()"
|
||||||
to fetch them, not "tvb_get_ntohl()" *OR* "tvb_get_letohl()" - don't,
|
to fetch them, not "tvb_get_ntohl()" *OR* "tvb_get_letohl()" - don't,
|
||||||
for example, try to use "tvb_get_ntohl()", find that it gives you the
|
for example, try to use "tvb_get_ntohl()", find that it gives you the
|
||||||
wrong answer on the PC on which you're doing development, and try
|
wrong answer on the PC on which you're doing development, and try
|
||||||
|
@ -409,9 +409,9 @@ guint8 *tvb_get_stringz_enc(wmem_allocator_t *scope, tvbuff_t *tvb, const gint o
|
||||||
Returns a null-terminated buffer allocated from the specified scope,
|
Returns a null-terminated buffer allocated from the specified scope,
|
||||||
containing data from the specified tvbuff, starting at the specified
|
containing data from the specified tvbuff, starting at the specified
|
||||||
offset, and containing all characters from the tvbuff up to and
|
offset, and containing all characters from the tvbuff up to and
|
||||||
including a terminating null character in the tvbuff. Reads data in the
|
including a terminating null character in the tvbuff. Reads data in the
|
||||||
specified encoding and produces UTF-8 in the buffer. See below for a
|
specified encoding and produces UTF-8 in the buffer. See below for a
|
||||||
list of input encoding values. "*lengthp" will be set to the length of
|
list of input encoding values. "*lengthp" will be set to the length of
|
||||||
the string, including the terminating null.
|
the string, including the terminating null.
|
||||||
|
|
||||||
The buffer is allocated in the given wmem scope (see README.wmem for more
|
The buffer is allocated in the given wmem scope (see README.wmem for more
|
||||||
|
@ -422,11 +422,11 @@ const guint8 *tvb_get_const_stringz(tvbuff_t *tvb, const gint offset, gint *leng
|
||||||
Returns a null-terminated const buffer containing data from the
|
Returns a null-terminated const buffer containing data from the
|
||||||
specified tvbuff, starting at the specified offset, and containing all
|
specified tvbuff, starting at the specified offset, and containing all
|
||||||
bytes from the tvbuff up to and including a terminating null character
|
bytes from the tvbuff up to and including a terminating null character
|
||||||
in the tvbuff. "*lengthp" will be set to the length of the string,
|
in the tvbuff. "*lengthp" will be set to the length of the string,
|
||||||
including the terminating null.
|
including the terminating null.
|
||||||
|
|
||||||
You do not need to free() this buffer; it will happen automatically once
|
You do not need to free() this buffer; it will happen automatically once
|
||||||
the next packet is dissected. This function is slightly more efficient
|
the next packet is dissected. This function is slightly more efficient
|
||||||
than the others because it does not allocate memory and copy the string,
|
than the others because it does not allocate memory and copy the string,
|
||||||
but it does not do any mapping to UTF-8 or checks for valid octet
|
but it does not do any mapping to UTF-8 or checks for valid octet
|
||||||
sequences.
|
sequences.
|
||||||
|
@ -502,10 +502,10 @@ Returns a buffer containing a copy of the given TVB bytes. The buffer is
|
||||||
allocated in the given wmem scope (see README.wmem for more information).
|
allocated in the given wmem scope (see README.wmem for more information).
|
||||||
|
|
||||||
Pointer-retrieval:
|
Pointer-retrieval:
|
||||||
/* WARNING! Don't use this function. There is almost always a better way.
|
/* WARNING! Don't use this function. There is almost always a better way.
|
||||||
* It's dangerous because once this pointer is given to the user, there's
|
* It's dangerous because once this pointer is given to the user, there's
|
||||||
* no guarantee that the user will honor the 'length' and not overstep the
|
* no guarantee that the user will honor the 'length' and not overstep the
|
||||||
* boundaries of the buffer. Also see the warning in the Portability section.
|
* boundaries of the buffer. Also see the warning in the Portability section.
|
||||||
*/
|
*/
|
||||||
const guint8* tvb_get_ptr(tvbuff_t *tvb, const gint offset, const gint length);
|
const guint8* tvb_get_ptr(tvbuff_t *tvb, const gint offset, const gint length);
|
||||||
|
|
||||||
|
@ -545,7 +545,7 @@ argument, and the COL_ value for the column as their second argument.
|
||||||
1.4.1 The col_set_str function.
|
1.4.1 The col_set_str function.
|
||||||
|
|
||||||
'col_set_str' takes a string as its third argument, and sets the value
|
'col_set_str' takes a string as its third argument, and sets the value
|
||||||
for the column to that value. It assumes that the pointer passed to it
|
for the column to that value. It assumes that the pointer passed to it
|
||||||
points to a string constant or a static "const" array, not to a
|
points to a string constant or a static "const" array, not to a
|
||||||
variable, as it doesn't copy the string, it merely saves the pointer
|
variable, as it doesn't copy the string, it merely saves the pointer
|
||||||
value; the argument can itself be a variable, as long as it always
|
value; the argument can itself be a variable, as long as it always
|
||||||
|
@ -566,7 +566,7 @@ to "PROTOABBREV":
|
||||||
1.4.2 The col_add_str function.
|
1.4.2 The col_add_str function.
|
||||||
|
|
||||||
'col_add_str' takes a string as its third argument, and sets the value
|
'col_add_str' takes a string as its third argument, and sets the value
|
||||||
for the column to that value. It takes the same arguments as
|
for the column to that value. It takes the same arguments as
|
||||||
'col_set_str', but copies the string, so that if the string is, for
|
'col_set_str', but copies the string, so that if the string is, for
|
||||||
example, an automatic variable that won't remain in scope when the
|
example, an automatic variable that won't remain in scope when the
|
||||||
dissector returns, it's safe to use.
|
dissector returns, it's safe to use.
|
||||||
|
@ -576,7 +576,7 @@ dissector returns, it's safe to use.
|
||||||
|
|
||||||
'col_add_fstr' takes a 'printf'-style format string as its third
|
'col_add_fstr' takes a 'printf'-style format string as its third
|
||||||
argument, and 'printf'-style arguments corresponding to '%' format
|
argument, and 'printf'-style arguments corresponding to '%' format
|
||||||
items 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
|
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
|
string containing the type of the request in the packet and "n" is an
|
||||||
unsigned integer containing the number of bytes in the request:
|
unsigned integer containing the number of bytes in the request:
|
||||||
|
@ -594,7 +594,7 @@ efficiently.
|
||||||
|
|
||||||
If the Info column will be filled with information from the packet, that
|
If the Info column will be filled with information from the packet, that
|
||||||
means that some data will be fetched from the packet before the Info
|
means that some data will be fetched from the packet before the Info
|
||||||
column is filled in. If the packet is so small that the data in
|
column is filled in. If the packet is so small that the data in
|
||||||
question cannot be fetched, the routines to fetch the data will throw an
|
question cannot be fetched, the routines to fetch the data will throw an
|
||||||
exception (see the comment at the beginning about tvbuffers improving
|
exception (see the comment at the beginning about tvbuffers improving
|
||||||
the handling of short packets - the tvbuffers keep track of how much
|
the handling of short packets - the tvbuffers keep track of how much
|
||||||
|
@ -634,10 +634,10 @@ string after it's fetched the data to use when doing that.
|
||||||
Sometimes the value of a column, especially the "Info" column, can't be
|
Sometimes the value of a column, especially the "Info" column, can't be
|
||||||
conveniently constructed at a single point in the dissection process;
|
conveniently constructed at a single point in the dissection process;
|
||||||
for example, it might contain small bits of information from many of the
|
for example, it might contain small bits of information from many of the
|
||||||
fields in the packet. 'col_append_str' takes, as arguments, the same
|
fields in the packet. 'col_append_str' takes, as arguments, the same
|
||||||
arguments as 'col_add_str', but the string is appended to the end of the
|
arguments as 'col_add_str', but the string is appended to the end of the
|
||||||
current value for the column, rather than replacing the value for that
|
current value for the column, rather than replacing the value for that
|
||||||
column. (Note that no blank separates the appended string from the
|
column. (Note that no blank separates the appended string from the
|
||||||
string to which it is appended; if you want a blank there, you must add
|
string to which it is appended; if you want a blank there, you must add
|
||||||
it yourself as part of the string being appended.)
|
it yourself as part of the string being appended.)
|
||||||
|
|
||||||
|
@ -663,7 +663,7 @@ identical to what 'col_append_str' and 'col_append_fstr' do.
|
||||||
|
|
||||||
Sometimes a dissector may be called multiple times for different PDUs in the
|
Sometimes a dissector may be called multiple times for different PDUs in the
|
||||||
same frame (for example in the case of SCTP chunk bundling: several upper
|
same frame (for example in the case of SCTP chunk bundling: several upper
|
||||||
layer data packets may be contained in one SCTP packet). If the upper layer
|
layer data packets may be contained in one SCTP packet). If the upper layer
|
||||||
dissector calls 'col_set_str()' or 'col_clear()' on the Info column when it
|
dissector calls 'col_set_str()' or 'col_clear()' on the Info column when it
|
||||||
begins dissecting each of those PDUs then when the frame is fully dissected
|
begins dissecting each of those PDUs then when the frame is fully dissected
|
||||||
the Info column would contain only the string from the last PDU in the frame.
|
the Info column would contain only the string from the last PDU in the frame.
|
||||||
|
@ -673,7 +673,7 @@ For example, the SCTP dissector calls 'col_set_fence' on the Info column
|
||||||
after it has called any subdissectors for that chunk so that subdissectors
|
after it has called any subdissectors for that chunk so that subdissectors
|
||||||
of any subsequent chunks may only append to the Info column.
|
of any subsequent chunks may only append to the Info column.
|
||||||
'col_prepend_fence_fstr' prepends data before a fence (moving it if
|
'col_prepend_fence_fstr' prepends data before a fence (moving it if
|
||||||
necessary). It will create a fence at the end of the prepended data if the
|
necessary). It will create a fence at the end of the prepended data if the
|
||||||
fence does not already exist.
|
fence does not already exist.
|
||||||
|
|
||||||
|
|
||||||
|
@ -711,7 +711,7 @@ proto_tree_draw().
|
||||||
The logical proto_tree needs to know detailed information about the protocols
|
The logical proto_tree needs to know detailed information about the protocols
|
||||||
and fields about which information will be collected from the dissection
|
and fields about which information will be collected from the dissection
|
||||||
routines. By strictly defining (or "typing") the data that can be attached to a
|
routines. By strictly defining (or "typing") the data that can be attached to a
|
||||||
proto tree, searching and filtering becomes possible. This means that for
|
proto tree, searching and filtering becomes possible. This means that for
|
||||||
every protocol and field (which I also call "header fields", since they are
|
every protocol and field (which I also call "header fields", since they are
|
||||||
fields in the protocol headers) which might be attached to a tree, some
|
fields in the protocol headers) which might be attached to a tree, some
|
||||||
information is needed.
|
information is needed.
|
||||||
|
@ -726,7 +726,7 @@ registration of protocols and fields at run-time, loadable modules of
|
||||||
protocol dissectors (perhaps even user-supplied) is feasible.
|
protocol dissectors (perhaps even user-supplied) is feasible.
|
||||||
|
|
||||||
To do this, each protocol should have a register routine, which will be
|
To do this, each protocol should have a register routine, which will be
|
||||||
called when Wireshark starts. The code to call the register routines is
|
called when Wireshark starts. The code to call the register routines is
|
||||||
generated automatically; to arrange that a protocol's register routine
|
generated automatically; to arrange that a protocol's register routine
|
||||||
be called at startup:
|
be called at startup:
|
||||||
|
|
||||||
|
@ -805,20 +805,20 @@ struct header_field_info {
|
||||||
name (FIELDNAME)
|
name (FIELDNAME)
|
||||||
----------------
|
----------------
|
||||||
A string representing the name of the field. This is the name
|
A string representing the name of the field. This is the name
|
||||||
that will appear in the graphical protocol tree. It must be a non-empty
|
that will appear in the graphical protocol tree. It must be a non-empty
|
||||||
string.
|
string.
|
||||||
|
|
||||||
abbrev (FIELDABBREV)
|
abbrev (FIELDABBREV)
|
||||||
--------------------
|
--------------------
|
||||||
A string with an abbreviation of the field. The abbreviation should start
|
A string with an abbreviation of the field. The abbreviation should start
|
||||||
with the abbreviation of the parent protocol followed by a period as a
|
with the abbreviation of the parent protocol followed by a period as a
|
||||||
separator. For example, the "src" field in an IP packet would have "ip.src"
|
separator. For example, the "src" field in an IP packet would have "ip.src"
|
||||||
as an abbreviation. It is acceptable to have multiple levels of periods if,
|
as an abbreviation. It is acceptable to have multiple levels of periods if,
|
||||||
for example, you have fields in your protocol that are then subdivided into
|
for example, you have fields in your protocol that are then subdivided into
|
||||||
subfields. For example, TRMAC has multiple error fields, so the abbreviations
|
subfields. For example, TRMAC has multiple error fields, so the abbreviations
|
||||||
follow this pattern: "trmac.errors.iso", "trmac.errors.noniso", etc.
|
follow this pattern: "trmac.errors.iso", "trmac.errors.noniso", etc.
|
||||||
|
|
||||||
The abbreviation is the identifier used in a display filter. As such it
|
The abbreviation is the identifier used in a display filter. As such it
|
||||||
cannot be an empty string.
|
cannot be an empty string.
|
||||||
|
|
||||||
type (FIELDTYPE)
|
type (FIELDTYPE)
|
||||||
|
@ -843,7 +843,7 @@ The type of value this field holds. The current field types are:
|
||||||
FT_FRAMENUM A frame number; if this is used, the "Go
|
FT_FRAMENUM A frame number; if this is used, the "Go
|
||||||
To Corresponding Frame" menu item can
|
To Corresponding Frame" menu item can
|
||||||
work on that field.
|
work on that field.
|
||||||
FT_CHAR An 8-bit ASCII character. It's treated similarly to an
|
FT_CHAR An 8-bit ASCII character. It's treated similarly to an
|
||||||
FT_UINT8, but is displayed as a C-style character
|
FT_UINT8, but is displayed as a C-style character
|
||||||
constant.
|
constant.
|
||||||
FT_UINT8 An 8-bit unsigned integer.
|
FT_UINT8 An 8-bit unsigned integer.
|
||||||
|
@ -921,12 +921,12 @@ signed integers; the number on the end represent how many bits are used
|
||||||
to represent the number.
|
to represent the number.
|
||||||
|
|
||||||
Some constraints are imposed on the header fields depending on the type
|
Some constraints are imposed on the header fields depending on the type
|
||||||
(e.g. FT_BYTES) of the field. Fields of type FT_ABSOLUTE_TIME must use
|
(e.g. FT_BYTES) of the field. Fields of type FT_ABSOLUTE_TIME must use
|
||||||
'ABSOLUTE_TIME_{LOCAL,UTC,DOY_UTC}, NULL, 0x0' as values for the
|
'ABSOLUTE_TIME_{LOCAL,UTC,DOY_UTC}, NULL, 0x0' as values for the
|
||||||
'display, 'strings', and 'bitmask' fields, and all other non-integral
|
'display, 'strings', and 'bitmask' fields, and all other non-integral
|
||||||
types (i.e.. types that are _not_ FT_INT* and FT_UINT*) must use
|
types (i.e.. types that are _not_ FT_INT* and FT_UINT*) must use
|
||||||
'BASE_NONE, NULL, 0x0' as values for the 'display', 'strings', 'bitmask'
|
'BASE_NONE, NULL, 0x0' as values for the 'display', 'strings', 'bitmask'
|
||||||
fields. The reason is simply that the type itself implicitly defines the
|
fields. The reason is simply that the type itself implicitly defines the
|
||||||
nature of 'display', 'strings', 'bitmask'.
|
nature of 'display', 'strings', 'bitmask'.
|
||||||
|
|
||||||
display (FIELDDISPLAY)
|
display (FIELDDISPLAY)
|
||||||
|
@ -937,7 +937,7 @@ makes for cleaner programs. Right now I still think that overloading
|
||||||
this variable was okay.
|
this variable was okay.
|
||||||
|
|
||||||
For integer fields (FT_UINT* and FT_INT*), this variable represents the
|
For integer fields (FT_UINT* and FT_INT*), this variable represents the
|
||||||
base in which you would like the value displayed. The acceptable bases
|
base in which you would like the value displayed. The acceptable bases
|
||||||
are:
|
are:
|
||||||
|
|
||||||
BASE_DEC,
|
BASE_DEC,
|
||||||
|
@ -982,7 +982,7 @@ wide the parent bitfield is). (If the FT_BOOLEAN 'bitmask' is zero, then
|
||||||
For integer fields a "field-width" is not needed since the type of
|
For integer fields a "field-width" is not needed since the type of
|
||||||
integer itself (FT_UINT8, FT_UINT16, FT_UINT24, FT_UINT32, FT_UINT40,
|
integer itself (FT_UINT8, FT_UINT16, FT_UINT24, FT_UINT32, FT_UINT40,
|
||||||
FT_UINT48, FT_UINT56, FT_UINT64, etc) tells the proto_tree how wide the
|
FT_UINT48, FT_UINT56, FT_UINT64, etc) tells the proto_tree how wide the
|
||||||
parent bitfield is. The same is true of FT_CHAR, as it's an 8-bit
|
parent bitfield is. The same is true of FT_CHAR, as it's an 8-bit
|
||||||
character.
|
character.
|
||||||
|
|
||||||
For FT_ABSOLUTE_TIME fields, 'display' is used to indicate whether the
|
For FT_ABSOLUTE_TIME fields, 'display' is used to indicate whether the
|
||||||
|
@ -993,7 +993,7 @@ date should be displayed as "{monthname} {day_of_month}, {year}" or as
|
||||||
|
|
||||||
Additionally, BASE_NONE is used for 'display' as a NULL-value. That is, for
|
Additionally, BASE_NONE is used for 'display' as a NULL-value. That is, for
|
||||||
non-integers other than FT_ABSOLUTE_TIME fields, and non-bitfield
|
non-integers other than FT_ABSOLUTE_TIME fields, and non-bitfield
|
||||||
FT_BOOLEANs, you'll want to use BASE_NONE in the 'display' field. You may
|
FT_BOOLEANs, you'll want to use BASE_NONE in the 'display' field. You may
|
||||||
not use BASE_NONE for integers.
|
not use BASE_NONE for integers.
|
||||||
|
|
||||||
It is possible that in the future we will record the endianness of
|
It is possible that in the future we will record the endianness of
|
||||||
|
@ -1008,7 +1008,7 @@ strings (FIELDCONVERT)
|
||||||
----------------------
|
----------------------
|
||||||
-- value_string
|
-- value_string
|
||||||
Some integer fields, of type FT_UINT*, need labels to represent the true
|
Some integer fields, of type FT_UINT*, need labels to represent the true
|
||||||
value of a field. You could think of those fields as having an
|
value of a field. You could think of those fields as having an
|
||||||
enumerated data type, rather than an integral data type.
|
enumerated data type, rather than an integral data type.
|
||||||
|
|
||||||
A 'value_string' structure is a way to map values to strings.
|
A 'value_string' structure is a way to map values to strings.
|
||||||
|
@ -1027,7 +1027,7 @@ For fields of that type, you would declare an array of "value_string"s:
|
||||||
};
|
};
|
||||||
|
|
||||||
(the last entry in the array must have a NULL 'strptr' value, to
|
(the last entry in the array must have a NULL 'strptr' value, to
|
||||||
indicate the end of the array). The 'strings' field would be set to
|
indicate the end of the array). The 'strings' field would be set to
|
||||||
'VALS(valstringname)'.
|
'VALS(valstringname)'.
|
||||||
|
|
||||||
If the field has a numeric rather than an enumerated type, the 'strings'
|
If the field has a numeric rather than an enumerated type, the 'strings'
|
||||||
|
@ -1035,7 +1035,7 @@ field would be set to NULL.
|
||||||
|
|
||||||
If BASE_SPECIAL_VALS is also applied to the display bitmask, then if the
|
If BASE_SPECIAL_VALS is also applied to the display bitmask, then if the
|
||||||
numeric value of a field doesn't match any values in the value_string
|
numeric value of a field doesn't match any values in the value_string
|
||||||
then just the numeric value is displayed (i.e. no "Unknown"). This is
|
then just the numeric value is displayed (i.e. no "Unknown"). This is
|
||||||
intended for use when the value_string only gives special names for
|
intended for use when the value_string only gives special names for
|
||||||
certain field values and values not in the value_string are expected.
|
certain field values and values not in the value_string are expected.
|
||||||
|
|
||||||
|
@ -1161,7 +1161,7 @@ ORed with 'BASE_RANGE_STRING' (e.g. BASE_DEC|BASE_RANGE_STRING).
|
||||||
-- Booleans
|
-- Booleans
|
||||||
FT_BOOLEANs have a default map of 0 = "False", 1 (or anything else) = "True".
|
FT_BOOLEANs have a default map of 0 = "False", 1 (or anything else) = "True".
|
||||||
Sometimes it is useful to change the labels for boolean values (e.g.,
|
Sometimes it is useful to change the labels for boolean values (e.g.,
|
||||||
to "Yes"/"No", "Fast"/"Slow", etc.). For these mappings, a struct called
|
to "Yes"/"No", "Fast"/"Slow", etc.). For these mappings, a struct called
|
||||||
true_false_string is used.
|
true_false_string is used.
|
||||||
|
|
||||||
typedef struct true_false_string {
|
typedef struct true_false_string {
|
||||||
|
@ -1178,7 +1178,7 @@ labels, you would declare a "true_false_string"s:
|
||||||
};
|
};
|
||||||
|
|
||||||
Its two fields are pointers to the string representing truth, and the
|
Its two fields are pointers to the string representing truth, and the
|
||||||
string representing falsehood. For FT_BOOLEAN fields that need a
|
string representing falsehood. For FT_BOOLEAN fields that need a
|
||||||
'true_false_string' struct, the 'strings' field would be set to
|
'true_false_string' struct, the 'strings' field would be set to
|
||||||
'TFS(&boolstringname)'.
|
'TFS(&boolstringname)'.
|
||||||
|
|
||||||
|
@ -1211,7 +1211,7 @@ If the field is not a bitfield, then bitmask should be set to 0.
|
||||||
|
|
||||||
blurb (FIELDDESCR)
|
blurb (FIELDDESCR)
|
||||||
------------------
|
------------------
|
||||||
This is a string giving a proper description of the field. It should be
|
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
|
at least one grammatically complete sentence, or NULL in which case the
|
||||||
name field is used. (Please do not use "").
|
name field is used. (Please do not use "").
|
||||||
|
|
||||||
|
@ -1318,7 +1318,7 @@ created under an item made by any of the "proto_tree_add_XXX" functions,
|
||||||
so that the tree can be given an arbitrary depth.
|
so that the tree can be given an arbitrary depth.
|
||||||
|
|
||||||
Subtree types are integers, assigned by
|
Subtree types are integers, assigned by
|
||||||
"proto_register_subtree_array()". To register subtree types, pass an
|
"proto_register_subtree_array()". To register subtree types, pass an
|
||||||
array of pointers to "gint" variables to hold the subtree type values to
|
array of pointers to "gint" variables to hold the subtree type values to
|
||||||
"proto_register_subtree_array()":
|
"proto_register_subtree_array()":
|
||||||
|
|
||||||
|
@ -1633,7 +1633,7 @@ protocol or field labels to the proto_tree:
|
||||||
proto_tree_add_ts_23_038_7bits_item(tree, hf_index, tvb,
|
proto_tree_add_ts_23_038_7bits_item(tree, hf_index, tvb,
|
||||||
bit_offset, no_of_chars);
|
bit_offset, no_of_chars);
|
||||||
|
|
||||||
The 'tree' argument is the tree to which the item is to be added. The
|
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
|
'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
|
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,
|
tvbuff of the item being added, and the 'length' argument is the length,
|
||||||
|
@ -1654,7 +1654,7 @@ proto_tree_add_item()
|
||||||
---------------------
|
---------------------
|
||||||
proto_tree_add_item is used when you wish to do no special formatting.
|
proto_tree_add_item is used when you wish to do no special formatting.
|
||||||
The item added to the GUI tree will contain the name (as passed in the
|
The item added to the GUI tree will contain the name (as passed in the
|
||||||
proto_register_*() function) and a value. The value will be fetched
|
proto_register_*() function) and a value. The value will be fetched
|
||||||
from the tvbuff by proto_tree_add_item(), based on the type of the field
|
from the tvbuff by proto_tree_add_item(), based on the type of the field
|
||||||
and the encoding of the value as specified by the "encoding" argument.
|
and the encoding of the value as specified by the "encoding" argument.
|
||||||
|
|
||||||
|
@ -1673,18 +1673,18 @@ argument should be ENC_LITTLE_ENDIAN if the value is little-endian
|
||||||
and ENC_BIG_ENDIAN if it is big-endian.
|
and ENC_BIG_ENDIAN if it is big-endian.
|
||||||
|
|
||||||
For FT_IPv4 fields, the encoding also specifies the byte order of the
|
For FT_IPv4 fields, the encoding also specifies the byte order of the
|
||||||
value. In almost all cases, the encoding is in network byte order,
|
value. In almost all cases, the encoding is in network byte order,
|
||||||
hence big-endian, but in at least one protocol dissected by Wireshark,
|
hence big-endian, but in at least one protocol dissected by Wireshark,
|
||||||
at least one IPv4 address is byte-swapped, so it's in little-endian
|
at least one IPv4 address is byte-swapped, so it's in little-endian
|
||||||
order.
|
order.
|
||||||
|
|
||||||
For string fields, the encoding specifies the character set used for the
|
For string fields, the encoding specifies the character set used for the
|
||||||
string and the way individual code points in that character set are
|
string and the way individual code points in that character set are
|
||||||
encoded. For FT_UINT_STRING fields, the byte order of the count must be
|
encoded. For FT_UINT_STRING fields, the byte order of the count must be
|
||||||
specified; for UCS-2 and UTF-16, the byte order of the encoding must be
|
specified; for UCS-2 and UTF-16, the byte order of the encoding must be
|
||||||
specified (for counted UCS-2 and UTF-16 strings, the byte order of the
|
specified (for counted UCS-2 and UTF-16 strings, the byte order of the
|
||||||
count and the 16-bit values in the string must be the same). In other
|
count and the 16-bit values in the string must be the same). In other
|
||||||
cases, ENC_NA should be used. The character encodings that are
|
cases, ENC_NA should be used. The character encodings that are
|
||||||
currently supported are:
|
currently supported are:
|
||||||
|
|
||||||
ENC_ASCII - ASCII (currently treated as UTF-8; in the future,
|
ENC_ASCII - ASCII (currently treated as UTF-8; in the future,
|
||||||
|
@ -1723,21 +1723,21 @@ currently supported are:
|
||||||
Other encodings will be added in the future.
|
Other encodings will be added in the future.
|
||||||
|
|
||||||
For FT_ABSOLUTE_TIME fields, the encoding specifies the form in which
|
For FT_ABSOLUTE_TIME fields, the encoding specifies the form in which
|
||||||
the time stamp is specified, as well as its byte order. The time stamp
|
the time stamp is specified, as well as its byte order. The time stamp
|
||||||
encodings that are currently supported are:
|
encodings that are currently supported are:
|
||||||
|
|
||||||
ENC_TIME_SECS_NSECS - 8, 12, or 16 bytes. For 8 bytes, the first 4
|
ENC_TIME_SECS_NSECS - 8, 12, or 16 bytes. For 8 bytes, the first 4
|
||||||
bytes are seconds and the next 4 bytes are nanoseconds; for 12
|
bytes are seconds and the next 4 bytes are nanoseconds; for 12
|
||||||
bytes, the first 8 bytes are seconds and the next 4 bytes are
|
bytes, the first 8 bytes are seconds and the next 4 bytes are
|
||||||
nanoseconds; for 16 bytes, the first 8 bytes are seconds and
|
nanoseconds; for 16 bytes, the first 8 bytes are seconds and
|
||||||
the next 8 bytes are nanoseconds. The seconds are seconds
|
the next 8 bytes are nanoseconds. The seconds are seconds
|
||||||
since the UN*X epoch (1970-01-01 00:00:00 UTC). (I.e., a UN*X
|
since the UN*X epoch (1970-01-01 00:00:00 UTC). (I.e., a UN*X
|
||||||
struct timespec with a 4-byte or 8-byte time_t or a structure
|
struct timespec with a 4-byte or 8-byte time_t or a structure
|
||||||
with an 8-byte time_t and an 8-byte nanoseconds field.)
|
with an 8-byte time_t and an 8-byte nanoseconds field.)
|
||||||
|
|
||||||
ENC_TIME_NTP - 8 bytes; the first 4 bytes are seconds since the NTP
|
ENC_TIME_NTP - 8 bytes; the first 4 bytes are seconds since the NTP
|
||||||
epoch (1900-01-01 00:00:00 GMT) and the next 4 bytes are 1/2^32's of
|
epoch (1900-01-01 00:00:00 GMT) and the next 4 bytes are 1/2^32's of
|
||||||
a second since that second. (I.e., a 64-bit count of 1/2^32's of a
|
a second since that second. (I.e., a 64-bit count of 1/2^32's of a
|
||||||
second since the NTP epoch, with the upper 32 bits first and the
|
second since the NTP epoch, with the upper 32 bits first and the
|
||||||
lower 32 bits second, even when little-endian.)
|
lower 32 bits second, even when little-endian.)
|
||||||
|
|
||||||
|
@ -1746,13 +1746,13 @@ encodings that are currently supported are:
|
||||||
|
|
||||||
ENC_TIME_RTPS - 8 bytes; the first 4 bytes are seconds since the UN*X
|
ENC_TIME_RTPS - 8 bytes; the first 4 bytes are seconds since the UN*X
|
||||||
epoch and the next 4 bytes are are 1/2^32's of a second since that
|
epoch and the next 4 bytes are are 1/2^32's of a second since that
|
||||||
second. (I.e., it's the offspring of a mating between UN*X time and
|
second. (I.e., it's the offspring of a mating between UN*X time and
|
||||||
NTP time.) It's used by the Object Management Group's Real-Time
|
NTP time). It's used by the Object Management Group's Real-Time
|
||||||
Publish-Subscribe Wire Protocol for the Data Distribution Service.
|
Publish-Subscribe Wire Protocol for the Data Distribution Service.
|
||||||
|
|
||||||
ENC_TIME_SECS_USECS - 8 bytes; the first 4 bytes are seconds since the
|
ENC_TIME_SECS_USECS - 8 bytes; the first 4 bytes are seconds since the
|
||||||
UN*X epoch and the next 4 bytes are microseconds since that
|
UN*X epoch and the next 4 bytes are microseconds since that
|
||||||
second. (I.e., a UN*X struct timeval with a 4-byte time_t.)
|
second. (I.e., a UN*X struct timeval with a 4-byte time_t.)
|
||||||
|
|
||||||
ENC_TIME_SECS - 4 to 8 bytes, representing a value in seconds since
|
ENC_TIME_SECS - 4 to 8 bytes, representing a value in seconds since
|
||||||
the UN*X epoch.
|
the UN*X epoch.
|
||||||
|
@ -1761,20 +1761,20 @@ encodings that are currently supported are:
|
||||||
since the UN*X epoch.
|
since the UN*X epoch.
|
||||||
|
|
||||||
ENC_TIME_SECS_NTP - 4 bytes, representing a count of seconds since
|
ENC_TIME_SECS_NTP - 4 bytes, representing a count of seconds since
|
||||||
the NTP epoch. (I.e., seconds since the NTP epoch.)
|
the NTP epoch. (I.e., seconds since the NTP epoch.)
|
||||||
|
|
||||||
ENC_TIME_RFC_3971 - 8 bytes, representing a count of 1/64ths of a
|
ENC_TIME_RFC_3971 - 8 bytes, representing a count of 1/64ths of a
|
||||||
second since the UN*X epoch; see section 5.3.1 "Timestamp Option"
|
second since the UN*X epoch; see section 5.3.1 "Timestamp Option"
|
||||||
in RFC 3971.
|
in RFC 3971.
|
||||||
|
|
||||||
ENC_TIME_MSEC_NTP - 4-8 bytes, representing a count of milliseconds since
|
ENC_TIME_MSEC_NTP - 4-8 bytes, representing a count of milliseconds since
|
||||||
the NTP epoch. (I.e., milliseconds since the NTP epoch.)
|
the NTP epoch. (I.e., milliseconds since the NTP epoch.)
|
||||||
|
|
||||||
For FT_RELATIVE_TIME fields, the encoding specifies the form in which
|
For FT_RELATIVE_TIME fields, the encoding specifies the form in which
|
||||||
the time stamp is specified, as well as its byte order. The time stamp
|
the time stamp is specified, as well as its byte order. The time stamp
|
||||||
encodings that are currently supported are:
|
encodings that are currently supported are:
|
||||||
|
|
||||||
ENC_TIME_SECS_NSECS - 8, 12, or 16 bytes. For 8 bytes, the first 4
|
ENC_TIME_SECS_NSECS - 8, 12, or 16 bytes. For 8 bytes, the first 4
|
||||||
bytes are seconds and the next 4 bytes are nanoseconds; for 12
|
bytes are seconds and the next 4 bytes are nanoseconds; for 12
|
||||||
bytes, the first 8 bytes are seconds and the next 4 bytes are
|
bytes, the first 8 bytes are seconds and the next 4 bytes are
|
||||||
nanoseconds; for 16 bytes, the first 8 bytes are seconds and
|
nanoseconds; for 16 bytes, the first 8 bytes are seconds and
|
||||||
|
@ -1791,9 +1791,9 @@ For other types, there is no support for proto_tree_add_item().
|
||||||
|
|
||||||
Now that definitions of fields have detailed information about bitfield
|
Now that definitions of fields have detailed information about bitfield
|
||||||
fields, you can use proto_tree_add_item() with no extra processing to
|
fields, you can use proto_tree_add_item() with no extra processing to
|
||||||
add bitfield values to your tree. Here's an example. Take the Format
|
add bitfield values to your tree. Here's an example. Take the Format
|
||||||
Identifier (FID) field in the Transmission Header (TH) portion of the SNA
|
Identifier (FID) field in the Transmission Header (TH) portion of the SNA
|
||||||
protocol. The FID is the high nibble of the first byte of the TH. The
|
protocol. The FID is the high nibble of the first byte of the TH. The
|
||||||
FID would be registered like this:
|
FID would be registered like this:
|
||||||
|
|
||||||
name = "Format Identifier"
|
name = "Format Identifier"
|
||||||
|
@ -1814,7 +1814,7 @@ The code to add the FID to the tree would be;
|
||||||
The definition of the field already has the information about bitmasking
|
The definition of the field already has the information about bitmasking
|
||||||
and bitshifting, so it does the work of masking and shifting for us!
|
and bitshifting, so it does the work of masking and shifting for us!
|
||||||
This also means that you no longer have to create value_string structs
|
This also means that you no longer have to create value_string structs
|
||||||
with the values bitshifted. The value_string for FID looks like this,
|
with the values bitshifted. The value_string for FID looks like this,
|
||||||
even though the FID value is actually contained in the high nibble.
|
even though the FID value is actually contained in the high nibble.
|
||||||
(You'd expect the values to be 0x0, 0x10, 0x20, etc.)
|
(You'd expect the values to be 0x0, 0x10, 0x20, etc.)
|
||||||
|
|
||||||
|
@ -1850,7 +1850,7 @@ back (to avoid doing tvb_get_...), and/or wish to have the value be decoded
|
||||||
from the tvbuff in a string-encoded format.
|
from the tvbuff in a string-encoded format.
|
||||||
|
|
||||||
The item added to the GUI tree will contain the name (as passed in the
|
The item added to the GUI tree will contain the name (as passed in the
|
||||||
proto_register_*() function) and a value. The value will be fetched
|
proto_register_*() function) and a value. The value will be fetched
|
||||||
from the tvbuff, based on the type of the XXX name and the encoding of
|
from the tvbuff, based on the type of the XXX name and the encoding of
|
||||||
the value as specified by the "encoding" argument.
|
the value as specified by the "encoding" argument.
|
||||||
|
|
||||||
|
@ -1864,7 +1864,7 @@ encoding, this means that a failure to decode the hex value from the string
|
||||||
results in an expert info error being added to the tree.
|
results in an expert info error being added to the tree.
|
||||||
|
|
||||||
For string-decoding, the passed-in encoding argument needs to specify the
|
For string-decoding, the passed-in encoding argument needs to specify the
|
||||||
string encoding (e.g., ENC_ASCII, ENC_UTF_8) as well as the format. For
|
string encoding (e.g., ENC_ASCII, ENC_UTF_8) as well as the format. For
|
||||||
some XXX types, the format is constrained - for example for the encoding format
|
some XXX types, the format is constrained - for example for the encoding format
|
||||||
for proto_tree_add_time_item() can only be one of the ENC_ISO_8601_* ones
|
for proto_tree_add_time_item() can only be one of the ENC_ISO_8601_* ones
|
||||||
or ENC_RFC_822 or ENC_RFC_1123. For proto_tree_add_bytes_item() it can only
|
or ENC_RFC_822 or ENC_RFC_1123. For proto_tree_add_bytes_item() it can only
|
||||||
|
@ -1874,7 +1874,7 @@ proto_tree_add_protocol_format()
|
||||||
--------------------------------
|
--------------------------------
|
||||||
proto_tree_add_protocol_format is used to add the top-level item for the
|
proto_tree_add_protocol_format is used to add the top-level item for the
|
||||||
protocol when the dissector routine 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
|
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
|
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.
|
arguments are a "printf"-style format and any arguments for that format.
|
||||||
The caller must include the name of the protocol in the format; it is
|
The caller must include the name of the protocol in the format; it is
|
||||||
|
@ -1935,7 +1935,7 @@ For proto_tree_add_time(), the 'value_ptr' argument is a pointer to an
|
||||||
"nstime_t", which is a structure containing the time to be added; it has
|
"nstime_t", which is a structure containing the time to be added; it has
|
||||||
'secs' and 'nsecs' members, giving the integral part and the fractional
|
'secs' and 'nsecs' members, giving the integral part and the fractional
|
||||||
part of a time in units of seconds, with 'nsecs' being the number of
|
part of a time in units of seconds, with 'nsecs' being the number of
|
||||||
nanoseconds. For absolute times, "secs" is a UNIX-style seconds since
|
nanoseconds. For absolute times, "secs" is a UNIX-style seconds since
|
||||||
January 1, 1970, 00:00:00 GMT value.
|
January 1, 1970, 00:00:00 GMT value.
|
||||||
|
|
||||||
For proto_tree_add_ipxnet(), the 'value' argument is a 32-bit IPX
|
For proto_tree_add_ipxnet(), the 'value' argument is a 32-bit IPX
|
||||||
|
@ -1965,14 +1965,14 @@ For proto_tree_add_double(), the 'value' argument is a 'double' in the
|
||||||
host's floating-point format.
|
host's floating-point format.
|
||||||
|
|
||||||
For proto_tree_add_uint(), the 'value' argument is a 32-bit unsigned
|
For proto_tree_add_uint(), the 'value' argument is a 32-bit unsigned
|
||||||
integer value, in host byte order. (This routine cannot be used to add
|
integer value, in host byte order. (This routine cannot be used to add
|
||||||
64-bit integers.)
|
64-bit integers.)
|
||||||
|
|
||||||
For proto_tree_add_uint64(), the 'value' argument is a 64-bit unsigned
|
For proto_tree_add_uint64(), the 'value' argument is a 64-bit unsigned
|
||||||
integer value, in host byte order.
|
integer value, in host byte order.
|
||||||
|
|
||||||
For proto_tree_add_int(), the 'value' argument is a 32-bit signed
|
For proto_tree_add_int(), the 'value' argument is a 32-bit signed
|
||||||
integer value, in host byte order. (This routine cannot be used to add
|
integer value, in host byte order. (This routine cannot be used to add
|
||||||
64-bit integers.)
|
64-bit integers.)
|
||||||
|
|
||||||
For proto_tree_add_int64(), the 'value' argument is a 64-bit signed
|
For proto_tree_add_int64(), the 'value' argument is a 64-bit signed
|
||||||
|
@ -2007,10 +2007,10 @@ proto_tree_add_eui64_format()
|
||||||
----------------------------
|
----------------------------
|
||||||
These routines are used to add items to the protocol tree when the
|
These routines are used to add items to the protocol tree when the
|
||||||
dissector routine 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
|
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 same as the corresponding proto_tree_add_XXX() function; the rest of
|
||||||
the arguments are a "printf"-style format and any arguments for that
|
the arguments are a "printf"-style format and any arguments for that
|
||||||
format. The caller must include the name of the field in the format; it
|
format. The caller must include the name of the field in the format; it
|
||||||
is not added automatically as in the proto_tree_add_XXX() functions.
|
is not added automatically as in the proto_tree_add_XXX() functions.
|
||||||
|
|
||||||
proto_tree_add_bytes_format_value()
|
proto_tree_add_bytes_format_value()
|
||||||
|
@ -2034,7 +2034,7 @@ proto_tree_add_eui64_format_value()
|
||||||
|
|
||||||
These routines are used to add items to the protocol tree when the
|
These routines are used to add items to the protocol tree when the
|
||||||
dissector routine 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
|
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
|
as the corresponding proto_tree_add_XXX() function; the rest of the
|
||||||
arguments are a "printf"-style format and any arguments for that format.
|
arguments are a "printf"-style format and any arguments for that format.
|
||||||
With these routines, unlike the proto_tree_add_XXX_format() routines,
|
With these routines, unlike the proto_tree_add_XXX_format() routines,
|
||||||
|
@ -2048,23 +2048,23 @@ proto_tree_add_checksum()
|
||||||
----------------------------
|
----------------------------
|
||||||
proto_tree_add_checksum is used to add a checksum field. The hf field
|
proto_tree_add_checksum is used to add a checksum field. The hf field
|
||||||
provided must be the correct size of the checksum (FT_UINT, FT_UINT16,
|
provided must be the correct size of the checksum (FT_UINT, FT_UINT16,
|
||||||
FT_UINT32, etc). Additional parameters are there to provide "status"
|
FT_UINT32, etc). Additional parameters are there to provide "status"
|
||||||
and expert info depending on whether the checksum matches the provided
|
and expert info depending on whether the checksum matches the provided
|
||||||
value. The "status" and expert info can be used in cases except
|
value. The "status" and expert info can be used in cases except
|
||||||
where PROTO_CHECKSUM_NO_FLAGS is used.
|
where PROTO_CHECKSUM_NO_FLAGS is used.
|
||||||
|
|
||||||
proto_tree_add_subtree()
|
proto_tree_add_subtree()
|
||||||
---------------------
|
---------------------
|
||||||
proto_tree_add_subtree() is used to add a label to the GUI tree and create
|
proto_tree_add_subtree() is used to add a label to the GUI tree and create
|
||||||
a subtree for other fields. It will contain no value, so it is not searchable
|
a subtree for other fields. It will contain no value, so it is not searchable
|
||||||
in the display filter process.
|
in the display filter process.
|
||||||
|
|
||||||
This should only be used for items with subtrees, which may not
|
This should only be used for items with subtrees, which may not
|
||||||
have values themselves - the items in the subtree are the ones with values.
|
have values themselves - the items in the subtree are the ones with values.
|
||||||
|
|
||||||
For a subtree, the label on the subtree might reflect some of the items
|
For a subtree, the label on the subtree might reflect some of the items
|
||||||
in the subtree. This means the label can't be set until at least some
|
in the subtree. This means the label can't be set until at least some
|
||||||
of the items in the subtree have been dissected. To do this, use
|
of the items in the subtree have been dissected. To do this, use
|
||||||
'proto_item_set_text()' or 'proto_item_append_text()':
|
'proto_item_set_text()' or 'proto_item_append_text()':
|
||||||
|
|
||||||
void
|
void
|
||||||
|
@ -2096,7 +2096,7 @@ available without dissecting any of the data in the subtree.
|
||||||
|
|
||||||
Note that an exception might be 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
|
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
|
available. Thus, one should create the item with text that is as
|
||||||
meaningful as possible, and set it or append additional information to
|
meaningful as possible, and set it or append additional information to
|
||||||
it as the values needed to supply that information are extracted.
|
it as the values needed to supply that information are extracted.
|
||||||
|
|
||||||
|
@ -2122,7 +2122,7 @@ Works in the same way but also returns the value of the read bits.
|
||||||
proto_tree_add_split_bits_item_ret_val()
|
proto_tree_add_split_bits_item_ret_val()
|
||||||
-----------------------------------
|
-----------------------------------
|
||||||
Similar, but is used for items that are made of 2 or more smaller sets of bits (crumbs)
|
Similar, but is used for items that are made of 2 or more smaller sets of bits (crumbs)
|
||||||
which are not contiguous, but are concatenated to form the actual value. The size of
|
which are not contiguous, but are concatenated to form the actual value. The size of
|
||||||
the crumbs and the order of assembly are specified in an array of crumb_spec structures.
|
the crumbs and the order of assembly are specified in an array of crumb_spec structures.
|
||||||
|
|
||||||
proto_tree_add_split_bits_crumb()
|
proto_tree_add_split_bits_crumb()
|
||||||
|
@ -2151,7 +2151,7 @@ the individual subfields of the bitmask. These fields must either be integers
|
||||||
Each of the entries in 'fields' will be dissected as an item under the
|
Each of the entries in 'fields' will be dissected as an item under the
|
||||||
'header' expansion and also IF the field is a boolean and IF it is set to 1,
|
'header' expansion and also IF the field is a boolean and IF it is set to 1,
|
||||||
then the name of that boolean field will be printed on the 'header' expansion
|
then the name of that boolean field will be printed on the 'header' expansion
|
||||||
line. For integer type subfields that have a value_string defined, the
|
line. For integer type subfields that have a value_string defined, the
|
||||||
matched string from that value_string will be printed on the expansion line
|
matched string from that value_string will be printed on the expansion line
|
||||||
as well.
|
as well.
|
||||||
|
|
||||||
|
@ -2259,7 +2259,7 @@ 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
|
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
|
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
|
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
|
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
|
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
|
won't be seen unless the user opens the subtree--but they can be found if the
|
||||||
user wants.
|
user wants.
|
||||||
|
@ -2267,8 +2267,8 @@ user wants.
|
||||||
One use for hidden fields (which would be better implemented using visible
|
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
|
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
|
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
|
the representation of that field in the tree is not appropriate. An
|
||||||
example is the token-ring routing information field (RIF). The best way
|
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.
|
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:
|
Rings are 3-digit hex numbers, and bridges are single hex digits:
|
||||||
|
|
||||||
|
@ -2416,7 +2416,7 @@ Where:
|
||||||
next_tvb is the new TVBUFF_SUBSET.
|
next_tvb is the new TVBUFF_SUBSET.
|
||||||
|
|
||||||
offset is the byte offset of 'tvb' at which the new tvbuff
|
offset is the byte offset of 'tvb' at which the new tvbuff
|
||||||
should start. The first byte is the 0th byte.
|
should start. The first byte is the 0th byte.
|
||||||
|
|
||||||
To create a new TVBUFF_SUBSET that begins at a specified offset in a
|
To create a new TVBUFF_SUBSET that begins at a specified offset in a
|
||||||
parent tvbuff, with a specified number of bytes in the payload, the
|
parent tvbuff, with a specified number of bytes in the payload, the
|
||||||
|
@ -2431,7 +2431,7 @@ Where:
|
||||||
next_tvb is the new TVBUFF_SUBSET.
|
next_tvb is the new TVBUFF_SUBSET.
|
||||||
|
|
||||||
offset is the byte offset of 'tvb' at which the new tvbuff
|
offset is the byte offset of 'tvb' at which the new tvbuff
|
||||||
should start. The first byte is the 0th byte.
|
should start. The first byte is the 0th byte.
|
||||||
|
|
||||||
reported_length is the number of bytes that the current protocol
|
reported_length is the number of bytes that the current protocol
|
||||||
says should be in the payload.
|
says should be in the payload.
|
||||||
|
@ -2450,7 +2450,7 @@ Where:
|
||||||
next_tvb is the new TVBUFF_SUBSET.
|
next_tvb is the new TVBUFF_SUBSET.
|
||||||
|
|
||||||
offset is the byte offset of 'tvb' at which the new tvbuff
|
offset is the byte offset of 'tvb' at which the new tvbuff
|
||||||
should start. The first byte is the 0th byte.
|
should start. The first byte is the 0th byte.
|
||||||
|
|
||||||
length is the number of bytes in the new TVBUFF_SUBSET. A length
|
length is the number of bytes in the new TVBUFF_SUBSET. A length
|
||||||
argument of -1 says to use as many bytes as are available in
|
argument of -1 says to use as many bytes as are available in
|
||||||
|
@ -2461,7 +2461,7 @@ Where:
|
||||||
the protocol doesn't say anything about the size of its payload.
|
the protocol doesn't say anything about the size of its payload.
|
||||||
|
|
||||||
To call a dissector you need to get the handle of the dissector using
|
To call a dissector you need to get the handle of the dissector using
|
||||||
find_dissector(), passing it the string name of the dissector. The setting
|
find_dissector(), passing it the string name of the dissector. The setting
|
||||||
of the handle is usually done once at startup during the proto_reg_handoff
|
of the handle is usually done once at startup during the proto_reg_handoff
|
||||||
function within the calling dissector.
|
function within the calling dissector.
|
||||||
|
|
||||||
|
@ -2469,7 +2469,7 @@ function within the calling dissector.
|
||||||
|
|
||||||
Another way to call a subdissector is to setup a dissector table. A dissector
|
Another way to call a subdissector is to setup a dissector table. A dissector
|
||||||
table is a list of subdissectors grouped by a common identifier (integer or
|
table is a list of subdissectors grouped by a common identifier (integer or
|
||||||
string) in a dissector. Subdissectors will register themselves with the dissector
|
string) in a dissector. Subdissectors will register themselves with the dissector
|
||||||
table using their unique identifier using one of the following APIs:
|
table using their unique identifier using one of the following APIs:
|
||||||
|
|
||||||
void dissector_add_uint(const char *abbrev, const guint32 pattern,
|
void dissector_add_uint(const char *abbrev, const guint32 pattern,
|
||||||
|
@ -2540,7 +2540,7 @@ section of epan/dissectors/CMakeLists.txt
|
||||||
./tools/cppcheck/cppcheck.sh <source-filename(s)>
|
./tools/cppcheck/cppcheck.sh <source-filename(s)>
|
||||||
|
|
||||||
- TEST YOUR DISSECTOR BEFORE SUBMITTING IT.
|
- TEST YOUR DISSECTOR BEFORE SUBMITTING IT.
|
||||||
Use fuzz-test.sh and/or randpkt against your dissector. These are
|
Use fuzz-test.sh and/or randpkt against your dissector. These are
|
||||||
described at <https://wiki.wireshark.org/FuzzTesting>.
|
described at <https://wiki.wireshark.org/FuzzTesting>.
|
||||||
|
|
||||||
- Subscribe to <mailto:wireshark-dev[AT]wireshark.org> by sending an email to
|
- Subscribe to <mailto:wireshark-dev[AT]wireshark.org> by sending an email to
|
||||||
|
@ -2555,7 +2555,7 @@ section of epan/dissectors/CMakeLists.txt
|
||||||
should be a summary of the changes followed by an empty line and a more
|
should be a summary of the changes followed by an empty line and a more
|
||||||
verbose description.
|
verbose description.
|
||||||
|
|
||||||
- 'git push origin HEAD:refs/for/master' to push the changes to Gerrit. (If
|
- 'git push origin HEAD:refs/for/master' to push the changes to Gerrit. (If
|
||||||
you previously ran 'git config --add remote.origin.push HEAD:refs/for/master'
|
you previously ran 'git config --add remote.origin.push HEAD:refs/for/master'
|
||||||
then only 'git push' is needed.)
|
then only 'git push' is needed.)
|
||||||
|
|
||||||
|
@ -2565,13 +2565,13 @@ section of epan/dissectors/CMakeLists.txt
|
||||||
and <https://wiki.wireshark.org/ProtocolReference>
|
and <https://wiki.wireshark.org/ProtocolReference>
|
||||||
|
|
||||||
- If possible, add sample capture files to the sample captures page at
|
- If possible, add sample capture files to the sample captures page at
|
||||||
<https://wiki.wireshark.org/SampleCaptures>. These files are used by
|
<https://wiki.wireshark.org/SampleCaptures>. These files are used by
|
||||||
the automated build system for fuzz testing.
|
the automated build system for fuzz testing.
|
||||||
|
|
||||||
- If you don't think the wiki is the right place for your sample capture,
|
- If you don't think the wiki is the right place for your sample capture,
|
||||||
submit a bug report to the Wireshark bug database, found at
|
submit a bug report to the Wireshark bug database, found at
|
||||||
<https://bugs.wireshark.org>, qualified as an enhancement and attach your
|
<https://bugs.wireshark.org>, qualified as an enhancement and attach your
|
||||||
sample capture there. Normally a new dissector won't be accepted without
|
sample capture there. Normally a new dissector won't be accepted without
|
||||||
a sample capture! If you open a bug be sure to cross-link your Gerrit
|
a sample capture! If you open a bug be sure to cross-link your Gerrit
|
||||||
change and bug.
|
change and bug.
|
||||||
|
|
||||||
|
@ -2585,8 +2585,8 @@ it is wise to check the relevant header and source files for additional details.
|
||||||
2.2 Following "conversations".
|
2.2 Following "conversations".
|
||||||
|
|
||||||
In wireshark a conversation is defined as a series of data packets 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
|
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
|
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.
|
ServerA:1000 to ClientA:2000 and the packet from ClientA:2000 to ServerA:1000.
|
||||||
|
|
||||||
2.2.1 Conversation Routines
|
2.2.1 Conversation Routines
|
||||||
|
@ -2599,12 +2599,12 @@ conversation_delete_proto_data, and conversation_set_dissector.
|
||||||
|
|
||||||
2.2.1.1 The conversation_init function.
|
2.2.1.1 The conversation_init function.
|
||||||
|
|
||||||
This is an internal routine for the conversation code. As such 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
|
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
|
called at the start of each capture and before the packets are filtered
|
||||||
with a display filter. The routine will destroy all stored
|
with a display filter. The routine will destroy all stored
|
||||||
conversations. This routine does NOT clean up any data pointers that are
|
conversations. This routine does NOT clean up any data pointers that are
|
||||||
passed in the conversation_add_proto_data 'data' variable. You are
|
passed in the conversation_add_proto_data 'data' variable. You are
|
||||||
responsible for this clean up if you pass a malloc'ed pointer
|
responsible for this clean up if you pass a malloc'ed pointer
|
||||||
in this variable.
|
in this variable.
|
||||||
|
|
||||||
|
@ -2614,13 +2614,13 @@ See item 2.2.1.5 for more information about use of the 'data' pointer.
|
||||||
2.2.1.2 The conversation_new function.
|
2.2.1.2 The conversation_new function.
|
||||||
|
|
||||||
This routine will create a new conversation based upon two address/port
|
This routine will create a new conversation based upon two address/port
|
||||||
pairs. If you want to associate with the conversation a pointer to a
|
pairs. If you want to associate with the conversation a pointer to a
|
||||||
private data structure you must use the conversation_add_proto_data
|
private data structure you must use the conversation_add_proto_data
|
||||||
function. The ptype variable is used to differentiate between
|
function. The ptype variable is used to differentiate between
|
||||||
conversations over different protocols, i.e. TCP and UDP. The options
|
conversations over different protocols, i.e. TCP and UDP. The options
|
||||||
variable is used to define a conversation that will accept any destination
|
variable is used to define a conversation that will accept any destination
|
||||||
address and/or port. Set options = 0 if the destination port and address
|
address and/or port. Set options = 0 if the destination port and address
|
||||||
are know when conversation_new is called. See section 2.4 for more
|
are know when conversation_new is called. See section 2.4 for more
|
||||||
information on usage of the options parameter.
|
information on usage of the options parameter.
|
||||||
|
|
||||||
The conversation_new prototype:
|
The conversation_new prototype:
|
||||||
|
@ -2642,7 +2642,7 @@ distinguish multiple conversations with the same addr1/port1 and addr2/port2
|
||||||
pair that occur within the same capture session.
|
pair that occur within the same capture session.
|
||||||
|
|
||||||
"addr1" and "port1" are the first address/port pair; "addr2" and "port2"
|
"addr1" and "port1" are the first address/port pair; "addr2" and "port2"
|
||||||
are the second address/port pair. A conversation doesn't have source
|
are the second address/port pair. A conversation doesn't have source
|
||||||
and destination address/port pairs - packets in a conversation go in
|
and destination address/port pairs - packets in a conversation go in
|
||||||
both directions - so "addr1"/"port1" may be the source or destination
|
both directions - so "addr1"/"port1" may be the source or destination
|
||||||
address/port pair; "addr2"/"port2" would be the other pair.
|
address/port pair; "addr2"/"port2" would be the other pair.
|
||||||
|
@ -2652,14 +2652,14 @@ conversation lookup will match only the "addr1" address; if NO_PORT2 is
|
||||||
specified, the conversation is set up so that a conversation lookup will
|
specified, the conversation is set up so that a conversation lookup will
|
||||||
match only the "port1" port; if both are specified, i.e.
|
match only the "port1" port; if both are specified, i.e.
|
||||||
NO_ADDR2|NO_PORT2, the conversation is set up so that the lookup will
|
NO_ADDR2|NO_PORT2, the conversation is set up so that the lookup will
|
||||||
match only the "addr1"/"port1" address/port pair. This can be used if a
|
match only the "addr1"/"port1" address/port pair. This can be used if a
|
||||||
packet indicates that, later in the capture, a conversation will be
|
packet indicates that, later in the capture, a conversation will be
|
||||||
created using certain addresses and ports, in the case where the packet
|
created using certain addresses and ports, in the case where the packet
|
||||||
doesn't specify the addresses and ports of both sides.
|
doesn't specify the addresses and ports of both sides.
|
||||||
|
|
||||||
2.2.1.3 The find_conversation function.
|
2.2.1.3 The find_conversation function.
|
||||||
|
|
||||||
Call this routine to look up a conversation. If no conversation is found,
|
Call this routine to look up a conversation. If no conversation is found,
|
||||||
the routine will return a NULL value.
|
the routine will return a NULL value.
|
||||||
|
|
||||||
The find_conversation prototype:
|
The find_conversation prototype:
|
||||||
|
@ -2689,10 +2689,10 @@ returned. If (frame_num >= 50 && frame_num < 100), conversation B is returned.
|
||||||
If (frame_num >= 100) conversation C is returned.
|
If (frame_num >= 100) conversation C is returned.
|
||||||
|
|
||||||
"addr_a" and "port_a" are the first address/port pair; "addr_b" and
|
"addr_a" and "port_a" are the first address/port pair; "addr_b" and
|
||||||
"port_b" are the second address/port pair. Again, as a conversation
|
"port_b" are the second address/port pair. Again, as a conversation
|
||||||
doesn't have source and destination address/port pairs, so
|
doesn't have source and destination address/port pairs, so
|
||||||
"addr_a"/"port_a" may be the source or destination address/port pair;
|
"addr_a"/"port_a" may be the source or destination address/port pair;
|
||||||
"addr_b"/"port_b" would be the other pair. The search will match the
|
"addr_b"/"port_b" would be the other pair. The search will match the
|
||||||
"a" address/port pair against both the "1" and "2" address/port pairs,
|
"a" address/port pair against both the "1" and "2" address/port pairs,
|
||||||
and match the "b" address/port pair against both the "2" and "1"
|
and match the "b" address/port pair against both the "2" and "1"
|
||||||
address/port pairs; you don't have to worry about which side the "a" or
|
address/port pairs; you don't have to worry about which side the "a" or
|
||||||
|
@ -2701,7 +2701,7 @@ address/port pairs; you don't have to worry about which side the "a" or
|
||||||
If the NO_ADDR_B flag was specified to "find_conversation()", the
|
If the NO_ADDR_B flag was specified to "find_conversation()", the
|
||||||
"addr_b" address will be treated as matching any "wildcarded" address;
|
"addr_b" address will be treated as matching any "wildcarded" address;
|
||||||
if the NO_PORT_B flag was specified, the "port_b" port will be treated
|
if the NO_PORT_B flag was specified, the "port_b" port will be treated
|
||||||
as matching any "wildcarded" port. If both flags are specified, i.e.
|
as matching any "wildcarded" port. If both flags are specified, i.e.
|
||||||
NO_ADDR_B|NO_PORT_B, the "addr_b" address will be treated as matching
|
NO_ADDR_B|NO_PORT_B, the "addr_b" address will be treated as matching
|
||||||
any "wildcarded" address and the "port_b" port will be treated as
|
any "wildcarded" address and the "port_b" port will be treated as
|
||||||
matching any "wildcarded" port.
|
matching any "wildcarded" port.
|
||||||
|
@ -2754,11 +2754,11 @@ Where:
|
||||||
int proto = registered protocol number
|
int proto = registered protocol number
|
||||||
void *data = dissector data structure
|
void *data = dissector data structure
|
||||||
|
|
||||||
"conversation" is the value returned by conversation_new. "proto" is a
|
"conversation" is the value returned by conversation_new. "proto" is a
|
||||||
unique protocol number created with proto_register_protocol. Protocols
|
unique protocol number created with proto_register_protocol. Protocols
|
||||||
are typically registered in the proto_register_XXXX section of your
|
are typically registered in the proto_register_XXXX section of your
|
||||||
dissector. "data" is a pointer to the data you wish to associate with the
|
dissector. "data" is a pointer to the data you wish to associate with the
|
||||||
conversation. "data" usually points to "wmem_alloc'd" memory; the
|
conversation. "data" usually points to "wmem_alloc'd" memory; the
|
||||||
memory will be automatically freed each time a new dissection begins
|
memory will be automatically freed each time a new dissection begins
|
||||||
and thus need not be managed (freed) by the dissector.
|
and thus need not be managed (freed) by the dissector.
|
||||||
Using the protocol number allows several dissectors to
|
Using the protocol number allows several dissectors to
|
||||||
|
@ -2778,17 +2778,17 @@ Where:
|
||||||
conversation_t *conv = the conversation in question
|
conversation_t *conv = the conversation in question
|
||||||
int proto = registered protocol number
|
int proto = registered protocol number
|
||||||
|
|
||||||
"conversation" is the conversation created with conversation_new. "proto"
|
"conversation" is the conversation created with conversation_new. "proto"
|
||||||
is a unique protocol number created with proto_register_protocol,
|
is a unique protocol number created with proto_register_protocol,
|
||||||
typically in the proto_register_XXXX portion of a dissector. The function
|
typically in the proto_register_XXXX portion of a dissector. The function
|
||||||
returns a pointer to the data requested, or NULL if no data was found.
|
returns a pointer to the data requested, or NULL if no data was found.
|
||||||
|
|
||||||
|
|
||||||
2.2.1.8 The conversation_delete_proto_data function.
|
2.2.1.8 The conversation_delete_proto_data function.
|
||||||
|
|
||||||
After you are finished with a conversation, you can remove your association
|
After you are finished with a conversation, you can remove your association
|
||||||
with this function. Please note that ONLY the conversation entry is
|
with this function. Please note that ONLY the conversation entry is
|
||||||
removed. If you have allocated any memory for your data (other than with wmem_alloc),
|
removed. If you have allocated any memory for your data (other than with wmem_alloc),
|
||||||
you must free it as well.
|
you must free it as well.
|
||||||
|
|
||||||
The conversation_delete_proto_data prototype:
|
The conversation_delete_proto_data prototype:
|
||||||
|
@ -2799,7 +2799,7 @@ Where:
|
||||||
conversation_t *conv = the conversation in question
|
conversation_t *conv = the conversation in question
|
||||||
int proto = registered protocol number
|
int proto = registered protocol number
|
||||||
|
|
||||||
"conversation" is the conversation created with conversation_new. "proto"
|
"conversation" is the conversation created with conversation_new. "proto"
|
||||||
is a unique protocol number created with proto_register_protocol,
|
is a unique protocol number created with proto_register_protocol,
|
||||||
typically in the proto_register_XXXX portion of a dissector.
|
typically in the proto_register_XXXX portion of a dissector.
|
||||||
|
|
||||||
|
@ -2867,7 +2867,7 @@ the tcp-dissector.
|
||||||
2.2.3 The example conversation code using wmem_file_scope memory.
|
2.2.3 The example conversation code using wmem_file_scope memory.
|
||||||
|
|
||||||
For a conversation between two IP addresses and ports you can use this as an
|
For a conversation between two IP addresses and ports you can use this as an
|
||||||
example. This example uses wmem_alloc() with wmem_file_scope() to allocate
|
example. This example uses wmem_alloc() with wmem_file_scope() to allocate
|
||||||
memory and stores the data pointer in the conversation 'data' variable.
|
memory and stores the data pointer in the conversation 'data' variable.
|
||||||
|
|
||||||
/************************ Global values ************************/
|
/************************ Global values ************************/
|
||||||
|
@ -2945,15 +2945,15 @@ that starts at the specific frame number.
|
||||||
2.2.5 The example conversation code using conversation index field.
|
2.2.5 The example conversation code using conversation index field.
|
||||||
|
|
||||||
Sometimes the conversation isn't enough to define a unique data storage
|
Sometimes the conversation isn't enough to define a unique data storage
|
||||||
value for the network traffic. For example if you are storing information
|
value for the network traffic. For example if you are storing information
|
||||||
about requests carried in a conversation, the request may have an
|
about requests carried in a conversation, the request may have an
|
||||||
identifier that is used to define the request. In this case the
|
identifier that is used to define the request. In this case the
|
||||||
conversation and the identifier are required to find the data storage
|
conversation and the identifier are required to find the data storage
|
||||||
pointer. You can use the conversation data structure index value to
|
pointer. You can use the conversation data structure index value to
|
||||||
uniquely define the conversation.
|
uniquely define the conversation.
|
||||||
|
|
||||||
See packet-afs.c for an example of how to use the conversation index. In
|
See packet-afs.c for an example of how to use the conversation index. In
|
||||||
this dissector multiple requests are sent in the same conversation. To store
|
this dissector multiple requests are sent in the same conversation. To store
|
||||||
information for each request the dissector has an internal hash table based
|
information for each request the dissector has an internal hash table based
|
||||||
upon the conversation index and values inside the request packets.
|
upon the conversation index and values inside the request packets.
|
||||||
|
|
||||||
|
@ -2995,13 +2995,13 @@ upon the conversation index and values inside the request packets.
|
||||||
|
|
||||||
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
|
create a complete conversation, source port/address and
|
||||||
destination port/address. If either the destination port or
|
destination port/address. If either the destination port or
|
||||||
address is known, see section 2.4 Dynamic server port dissector
|
address is known, see section 2.4 Dynamic server port dissector
|
||||||
registration.
|
registration.
|
||||||
|
|
||||||
For protocols that negotiate a secondary port connection, for example
|
For protocols that negotiate a secondary port connection, for example
|
||||||
packet-msproxy.c, a conversation can install a dissector to handle
|
packet-msproxy.c, a conversation can install a dissector to handle
|
||||||
the secondary protocol dissection. After the conversation is created
|
the secondary protocol dissection. After the conversation is created
|
||||||
for the negotiated ports use the conversation_set_dissector to define
|
for the negotiated ports use the conversation_set_dissector to define
|
||||||
the dissection routine.
|
the dissection routine.
|
||||||
Before we create these conversations or assign a dissector to them we should
|
Before we create these conversations or assign a dissector to them we should
|
||||||
|
@ -3079,12 +3079,12 @@ proto_register_PROTOABBREV(void)
|
||||||
|
|
||||||
NOTE: While this example used both NO_ADDR2 and NO_PORT2 to create a
|
NOTE: While this example used both NO_ADDR2 and NO_PORT2 to create a
|
||||||
conversation with only one port and address set, this isn't a
|
conversation with only one port and address set, this isn't a
|
||||||
requirement. Either the second port or the second address can be set
|
requirement. Either the second port or the second address can be set
|
||||||
when the conversation is created.
|
when the conversation is created.
|
||||||
|
|
||||||
For protocols that define a server address and port for a secondary
|
For protocols that define a server address and port for a secondary
|
||||||
protocol, a conversation can be used to link a protocol dissector to
|
protocol, a conversation can be used to link a protocol dissector to
|
||||||
the server port and address. The key is to create the new
|
the server port and address. The key is to create the new
|
||||||
conversation with the second address and port set to the "accept
|
conversation with the second address and port set to the "accept
|
||||||
any" values.
|
any" values.
|
||||||
|
|
||||||
|
@ -3108,8 +3108,8 @@ conversation_set_port2( conversation_t *conv, guint32 port);
|
||||||
conversation_set_addr2( conversation_t *conv, address addr);
|
conversation_set_addr2( conversation_t *conv, address addr);
|
||||||
|
|
||||||
These routines will change the second address or port for the
|
These routines will change the second address or port for the
|
||||||
conversation. So, the server port conversation will be converted into a
|
conversation. So, the server port conversation will be converted into a
|
||||||
more complete conversation definition. Don't use these routines if you
|
more complete conversation definition. Don't use these routines if you
|
||||||
want to 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.
|
server port definition, you must create a new conversation.
|
||||||
|
|
||||||
|
@ -3155,8 +3155,8 @@ static dissector_handle_t 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
|
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
|
dissector. The information is added with the p_add_proto_data function and
|
||||||
retrieved with the p_get_proto_data function. The data pointers passed into
|
retrieved with the p_get_proto_data function. The data pointers passed into
|
||||||
the p_add_proto_data are not managed by the proto_data routines, however the
|
the p_add_proto_data are not managed by the proto_data routines, however the
|
||||||
data pointer memory scope must match that of the scope parameter.
|
data pointer memory scope must match that of the scope parameter.
|
||||||
The two most common use cases for p_add_proto_data/p_get_proto_data are for
|
The two most common use cases for p_add_proto_data/p_get_proto_data are for
|
||||||
|
@ -3173,7 +3173,7 @@ p_get_proto_data(wmem_allocator_t *scope, packet_info *pinfo, int proto, guint32
|
||||||
|
|
||||||
Where:
|
Where:
|
||||||
scope - Lifetime of the data to be stored, typically wmem_file_scope()
|
scope - Lifetime of the data to be stored, typically wmem_file_scope()
|
||||||
or pinfo->pool (packet scope). Must match scope of data
|
or pinfo->pool (packet scope). Must match scope of data
|
||||||
allocated.
|
allocated.
|
||||||
pinfo - The packet info pointer.
|
pinfo - The packet info pointer.
|
||||||
proto - Protocol id returned by the proto_register_protocol call
|
proto - Protocol id returned by the proto_register_protocol call
|
||||||
|
@ -3250,15 +3250,15 @@ Where: module - Returned by the prefs_register_protocol routine
|
||||||
description - Comments added to the preference file above the
|
description - Comments added to the preference file above the
|
||||||
preference value and shown as tooltip in the GUI, or NULL
|
preference value and shown as tooltip in the GUI, or NULL
|
||||||
var - pointer to the storage location that is updated when the
|
var - pointer to the storage location that is updated when the
|
||||||
field is changed in the preference dialog box. Note that
|
field is changed in the preference dialog box. Note that
|
||||||
with string preferences the given pointer is overwritten
|
with string preferences the given pointer is overwritten
|
||||||
with a pointer to a new copy of the string during the
|
with a pointer to a new copy of the string during the
|
||||||
preference registration. The passed-in string may be
|
preference registration. The passed-in string may be
|
||||||
freed, but you must keep another pointer to the string
|
freed, but you must keep another pointer to the string
|
||||||
in order to free it.
|
in order to free it.
|
||||||
base - Base that the unsigned integer is expected to be in,
|
base - Base that the unsigned integer is expected to be in,
|
||||||
see strtoul(3).
|
see strtoul(3).
|
||||||
enumvals - an array of enum_val_t structures. This must be
|
enumvals - an array of enum_val_t structures. This must be
|
||||||
NULL-terminated; the members of that structure are:
|
NULL-terminated; the members of that structure are:
|
||||||
|
|
||||||
a short name, to be used with the "-o" flag - it
|
a short name, to be used with the "-o" flag - it
|
||||||
|
@ -3316,17 +3316,17 @@ a preference obsolete is to register it as such:
|
||||||
2.7 Reassembly/desegmentation for protocols running atop TCP.
|
2.7 Reassembly/desegmentation for protocols running atop TCP.
|
||||||
|
|
||||||
There are two main ways of reassembling a Protocol Data Unit (PDU) which
|
There are two main ways of reassembling a Protocol Data Unit (PDU) which
|
||||||
spans across multiple TCP segments. The first approach is simpler, but
|
spans across multiple TCP segments. The first approach is simpler, but
|
||||||
assumes you are running atop of TCP when this occurs (but your dissector
|
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
|
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
|
fixed amount of data that includes enough information to determine the PDU
|
||||||
length, possibly followed by additional data. The second method is more
|
length, possibly followed by additional data. The second method is more
|
||||||
generic but requires more code and is less efficient.
|
generic but requires more code and is less efficient.
|
||||||
|
|
||||||
2.7.1 Using tcp_dissect_pdus().
|
2.7.1 Using tcp_dissect_pdus().
|
||||||
|
|
||||||
For the first method, you register two different dissection methods, one
|
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
|
for the TCP case, and one for the other cases. It is a good idea to
|
||||||
also 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
|
content that you can find in all PDUs which is called from
|
||||||
dissect_PROTO_tcp when the reassembly is complete and from
|
dissect_PROTO_tcp when the reassembly is complete and from
|
||||||
|
@ -3410,8 +3410,8 @@ If the dissector discovers that the end of the tvbuff does /not/ coincide with
|
||||||
the end of a PDU, (ie, there is half of a PDU at the end of the tvbuff), it can
|
the end of a PDU, (ie, there is half of a PDU at the end of the tvbuff), it can
|
||||||
indicate this to the parent dissector, by updating the pinfo struct. The
|
indicate this to the parent dissector, by updating the pinfo struct. The
|
||||||
desegment_offset field is the offset in the tvbuff at which the dissector will
|
desegment_offset field is the offset in the tvbuff at which the dissector will
|
||||||
continue processing when next called. The desegment_len field should contain
|
continue processing when next called. The desegment_len field should contain
|
||||||
the estimated number of additional bytes required for completing the PDU. Next
|
the estimated number of additional bytes required for completing the PDU. Next
|
||||||
time your dissect_PROTO is called, it will be passed a tvbuff composed of the
|
time your dissect_PROTO is called, it will be passed a tvbuff composed of the
|
||||||
end of the data from the previous tvbuff together with desegment_len more bytes.
|
end of the data from the previous tvbuff together with desegment_len more bytes.
|
||||||
|
|
||||||
|
@ -3479,7 +3479,7 @@ loop.
|
||||||
|
|
||||||
As noted in section 2.7.1, TCP has an API to dissect its PDU that can handle
|
As noted in section 2.7.1, TCP has an API to dissect its PDU that can handle
|
||||||
a PDU spread across multiple packets or multiple PDUs spread across a single
|
a PDU spread across multiple packets or multiple PDUs spread across a single
|
||||||
packet. This section describes a similar mechanism for UDP, but is only
|
packet. This section describes a similar mechanism for UDP, but is only
|
||||||
applicable for one or more PDUs in a single packet. If a protocol runs on top
|
applicable for one or more PDUs in a single packet. If a protocol runs on top
|
||||||
of TCP as well as UDP, a common PDU dissection function can be created for both.
|
of TCP as well as UDP, a common PDU dissection function can be created for both.
|
||||||
|
|
||||||
|
@ -3563,7 +3563,7 @@ The arguments to udp_dissect_pdus are:
|
||||||
2.9 PINOs (Protocols in name only)
|
2.9 PINOs (Protocols in name only)
|
||||||
|
|
||||||
For the typical dissector there is a 1-1 relationship between it and it's
|
For the typical dissector there is a 1-1 relationship between it and it's
|
||||||
protocol. However, there are times when a protocol needs multiple "names"
|
protocol. However, there are times when a protocol needs multiple "names"
|
||||||
because it has multiple dissection functions going into the same dissector
|
because it has multiple dissection functions going into the same dissector
|
||||||
table. The muliple names removes confusion when picking dissection through
|
table. The muliple names removes confusion when picking dissection through
|
||||||
Decode As functionality.
|
Decode As functionality.
|
||||||
|
@ -3571,8 +3571,8 @@ Decode As functionality.
|
||||||
Once the "main" protocol name has been created through proto_register_protocol,
|
Once the "main" protocol name has been created through proto_register_protocol,
|
||||||
additional "pinos" can be created with proto_register_protocol_in_name_only.
|
additional "pinos" can be created with proto_register_protocol_in_name_only.
|
||||||
These pinos have all of the naming conventions of a protocol, but are stored
|
These pinos have all of the naming conventions of a protocol, but are stored
|
||||||
separately as to remove confusion from real protocols. "pinos" the main
|
separately as to remove confusion from real protocols. "pinos" the main
|
||||||
protocol's properties for things like enable/disable. i.e. If the "main"
|
protocol's properties for things like enable/disable. i.e. If the "main"
|
||||||
protocol has been disabled, all of its pinos will be disabled as well.
|
protocol has been disabled, all of its pinos will be disabled as well.
|
||||||
Pinos should not have any fields registered with them or heuristic tables
|
Pinos should not have any fields registered with them or heuristic tables
|
||||||
associated with them.
|
associated with them.
|
||||||
|
@ -3580,8 +3580,8 @@ associated with them.
|
||||||
Another use case for pinos is when a protocol contains a TLV design and it
|
Another use case for pinos is when a protocol contains a TLV design and it
|
||||||
wants to create a dissector table to handle dissection of the "V". Dissector
|
wants to create a dissector table to handle dissection of the "V". Dissector
|
||||||
tables require a "protocol", but the dissection functions for that table
|
tables require a "protocol", but the dissection functions for that table
|
||||||
typically aren't a protocol. In this case proto_register_protocol_in_name_only
|
typically aren't a protocol. In this case proto_register_protocol_in_name_only
|
||||||
creates the necessary placeholder for the dissector table. In addition, because
|
creates the necessary placeholder for the dissector table. In addition, because
|
||||||
a dissector table exists, "V"s of the TLVs can be dissected outside of the
|
a dissector table exists, "V"s of the TLVs can be dissected outside of the
|
||||||
original dissector file.
|
original dissector file.
|
||||||
|
|
||||||
|
@ -3606,7 +3606,7 @@ Consider the following example using IP dissection, stolen from packet-ip.c:
|
||||||
register_decode_as(&ip_da);
|
register_decode_as(&ip_da);
|
||||||
|
|
||||||
ip_da_build_value contains all of the function pointers (typically just 1) that
|
ip_da_build_value contains all of the function pointers (typically just 1) that
|
||||||
can be used to retrieve the value(s) that go into the dissector table. This is
|
can be used to retrieve the value(s) that go into the dissector table. This is
|
||||||
usually data saved by the dissector during packet dissector with an API like
|
usually data saved by the dissector during packet dissector with an API like
|
||||||
p_add_proto_data and retrieved in the "value" function with p_get_proto_data.
|
p_add_proto_data and retrieved in the "value" function with p_get_proto_data.
|
||||||
|
|
||||||
|
@ -3617,7 +3617,7 @@ be passed to the dissector table to change the dissection output.
|
||||||
ip_da pulls everything together including the dissector (protocol) name, the
|
ip_da pulls everything together including the dissector (protocol) name, the
|
||||||
"layer type" of the dissector, the dissector table name, the function pointer
|
"layer type" of the dissector, the dissector table name, the function pointer
|
||||||
values as well as handlers for populating, applying and reseting the changes
|
values as well as handlers for populating, applying and reseting the changes
|
||||||
to the dissector table through Decode As GUI functionality. For dissector
|
to the dissector table through Decode As GUI functionality. For dissector
|
||||||
tables that are an integer or string type, the provided "default" handling
|
tables that are an integer or string type, the provided "default" handling
|
||||||
functions shown in the example should suffice.
|
functions shown in the example should suffice.
|
||||||
|
|
||||||
|
@ -3778,7 +3778,7 @@ can be passed a null protocol tree pointer, in which case they'll
|
||||||
return a null item pointer, and "proto_item_add_subtree()" returns
|
return a null item pointer, and "proto_item_add_subtree()" returns
|
||||||
a null tree pointer if passed a null item pointer, so, if you're
|
a null tree pointer if passed a null item pointer, so, if you're
|
||||||
careful not to dereference any null tree or item pointers, you can
|
careful not to dereference any null tree or item pointers, you can
|
||||||
accomplish this by doing all the dissection work. This might not
|
accomplish this by doing all the dissection work. This might not
|
||||||
be as efficient as skipping that work if you're not building a
|
be as efficient as skipping that work if you're not building a
|
||||||
protocol tree, but if the code would have a lot of tests whether
|
protocol tree, but if the code would have a lot of tests whether
|
||||||
"tree" is null if you skipped that work, you might still be better
|
"tree" is null if you skipped that work, you might still be better
|
||||||
|
|
Loading…
Reference in New Issue