Add section to README.dissector about dissector tables

Bug: 8985
Change-Id: I9245fb556a55da681fe53dd5c12bb549c83c89c6
Reviewed-on: https://code.wireshark.org/review/7926
Reviewed-by: Michael Mann <mmann78@netscape.net>
Reviewed-by: Anders Broman <a.broman58@gmail.com>

1 files changed, 47 insertions, 0 deletions

diff --git a/doc/README.dissector b/doc/README.dissector
index 1440370ae3..cdfce9ab1e 100644
--- a/doc/README.dissector
+++ b/doc/README.dissector
@@ -2116,6 +2116,53 @@ Where:
     says should be in the payload. A reported_length of -1 says that
     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
+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
+function within the calling dissector.
+
+1.7.1 Dissector Tables
+
+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
+string) in a dissector.  Subdissectors will register themselves with the dissector
+table using their unique identifier using one of the following APIs:
+
+    void dissector_add_uint(const char *abbrev, const guint32 pattern,
+                            dissector_handle_t handle);
+
+    void dissector_add_uint_range(const char *abbrev, struct epan_range *range,
+                            dissector_handle_t handle);
+
+    void dissector_add_string(const char *name, const gchar *pattern,
+                            dissector_handle_t handle);
+
+    void dissector_add_for_decode_as(const char *name,
+                            dissector_handle_t handle);
+
+    dissector_add_for_decode_as doesn't add a unique identifier in the dissector
+    table, but it lets the user add it from the command line or, in Wireshark,
+    through the "Decode As" UI.
+
+Then when the dissector hits the common identifier field, it will useone of the
+following APIs to invoke the subdissector:
+
+    int dissector_try_uint(dissector_table_t sub_dissectors,
+        const guint32 uint_val, tvbuff_t *tvb, packet_info *pinfo,
+        proto_tree *tree);
+
+    int dissector_try_uint_new(dissector_table_t sub_dissectors,
+        const guint32 uint_val, tvbuff_t *tvb, packet_info *pinfo,
+        proto_tree *tree, const gboolean add_proto_name, void *data);
+
+    int dissector_try_string(dissector_table_t sub_dissectors, const gchar *string,
+        tvbuff_t *tvb, packet_info *pinfo, proto_tree *tree, void *data);
+
+These pass a subset of the remaining packet (typically the rest of the
+packet) for the dissector table to determine which subdissector is called.
+This allows dissection of a packet to be expanded outside of dissector without
+having to modify the dissector directly.
+
 
 1.8 Editing Makefile.common and CMakeLists.txt to add your dissector.