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

1 files changed, 23 insertions, 13 deletions

diff --git a/doc/README.dissector b/doc/README.dissector
index f61e76c913..264e5c7d37 100644
--- a/doc/README.dissector
+++ b/doc/README.dissector
@@ -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.
 
-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.
+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.
+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