osmocom
/
wireshark
14
0
Fork 1
Code Issues Pull Requests Projects Releases Wiki Activity

Use `register_dissector()` in doc/README.dissector 

Document `register_dissector()` and
`register_dissector_with_description()` as being preferable alternatives
to `create_dissector_handle()` in doc/README.dissector.

Update the examples in that file which were taken from `packet-hartip.c`
and `packet-dnp.c` to reflect changes in those files made since writing.

One small step toward addressing #5612
This commit is contained in:
David Perry 2023-06-14 15:28:54 -04:00 committed by AndersBroman
parent 80489af0b5
commit 8e5f503267
1 changed files with 23 additions and 13 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

36
doc/README.dissector
View File

@ -2914,13 +2914,23 @@ an application cycle. By keeping track of the frame number a conversation
was started in Wireshark can still tell these different protocols apart.
The second argument to conversation_set_dissector is a dissector handle,
which is created with a call to create_dissector_handle or
register_dissector.
which is created with a call to create_dissector_handle,
register_dissector, or register_dissector_with_description.
register_dissector_with_description takes as arguments a string giving a name
for the dissector, a string with a human-readable summary of the dissector, a
pointer to the dissector function, and a protocol ID as returned by
proto_register_protocol.
register_dissector takes as arguments a string giving a name for the
dissector, a pointer to the dissector function, and a protocol ID
as returned by proto_register_protocol.
create_dissector_handle takes as arguments a pointer to the dissector
function and a protocol ID as returned by proto_register_protocol;
register_dissector takes as arguments a string giving a name for the
dissector, a pointer to the dissector function, and a protocol ID.
function and a protocol ID as returned by proto_register_protocol.
It is recommended to use one of the above two functions instead of this one,
since they allow the dissector to be referenced by name from the command line,
by other dissectors via calls to find_dissector, etc.
The protocol ID is the ID for the protocol dissected by the function.
The function will not be called if the protocol has been disabled by the
@ -2970,7 +2980,7 @@ proto_register_PROTOABBREV(void)
{
...
sub_dissector_handle = create_dissector_handle(sub_dissector,
sub_dissector_handle = register_dissector("PROTOABBREV", sub_dissector,
proto);
...
@ -3246,10 +3256,10 @@ example, stolen from packet-hartip.c:
dissector_handle_t hartip_tcp_handle;
dissector_handle_t hartip_udp_handle;
hartip_tcp_handle = create_dissector_handle(dissect_hartip_tcp, proto_hartip);
hartip_udp_handle = create_dissector_handle(dissect_hartip_udp, proto_hartip);
hartip_udp_handle = register_dissector_with_description("hart_ip", "HART-IP over UDP", dissect_hartip_udp, proto_hartip);
hartip_tcp_handle = register_dissector_with_description("hart_ip.tcp", "HART-IP over TCP", dissect_hartip_tcp, proto_hartip);
dissector_add_uint("udp.port", HARTIP_PORT, hartip_udp_handle);
dissector_add_uint_with_preference("udp.port", HARTIP_PORT, hartip_udp_handle);
dissector_add_uint_with_preference("tcp.port", HARTIP_PORT, hartip_tcp_handle);
The dissect_hartip_udp function does very little work and calls
@ -3397,11 +3407,11 @@ example using UDP and TCP dissection, stolen from packet-dnp.c:
dissector_handle_t dnp3_tcp_handle;
dissector_handle_t dnp3_udp_handle;
dnp3_tcp_handle = create_dissector_handle(dissect_dnp3_tcp, proto_dnp3);
dnp3_udp_handle = create_dissector_handle(dissect_dnp3_udp, proto_dnp3);
dnp3_tcp_handle = register_dissector("dnp3.tcp", dissect_dnp3_tcp, proto_dnp3);
dnp3_udp_handle = register_dissector("dnp3.udp", dissect_dnp3_udp, proto_dnp3);
dissector_add_uint("tcp.port", TCP_PORT_DNP, dnp3_tcp_handle);
dissector_add_uint("udp.port", UDP_PORT_DNP, dnp3_udp_handle);
dissector_add_uint_with_preference("tcp.port", TCP_PORT_DNP, dnp3_tcp_handle);
dissector_add_uint_with_preference("udp.port", UDP_PORT_DNP, dnp3_udp_handle);
Both dissect_dnp3_tcp and dissect_dnp3_udp call tcp_dissect_pdus and
udp_dissect_pdus respectively, with a reference to the same callbacks which