Update documentation for tcp_dissect_pdus. Bug 9491 (https://bugs.wireshark.org...

From Peter Wu: update to README.dissector
From me: update to WSDG_chapter_dissection.xml

git-svn-id: http://anonsvn.wireshark.org/wireshark/trunk@53678 f5534014-38df-0310-8fa8-9805f1628bb7

diff --git a/doc/README.dissector b/doc/README.dissector
index 814dae956b59bcd2cddda0a417e57b947f70d4bf..6df380078e04a92d467acee738a0e13a7d79ae50 100644 (file)
--- a/doc/README.dissector
+++ b/doc/README.dissector
@@ -72,7 +72,7 @@ Usually, you will put your newly created dissector file into the directory
 epan/dissectors/, just like all the other packet-*.c files already in there.
 
 Also, please add your dissector file to the corresponding makefiles,
-described in section "1.9 Editing Makefile.common and CMakeLists.txt
+described in section "1.8 Editing Makefile.common and CMakeLists.txt
 to add your dissector" below.
 
 Dissectors that use the dissector registration API to register with a lower
@@ -2833,15 +2833,17 @@ dissect_PROTO_udp (or dissect_PROTO_other).
 To register the distinct dissector functions, consider the following
 example, stolen from packet-dns.c:
 
+    #include "packet-tcp.h"
+
     dissector_handle_t dns_udp_handle;
     dissector_handle_t dns_tcp_handle;
     dissector_handle_t mdns_udp_handle;
 
-    dns_udp_handle = create_dissector_handle(dissect_dns_udp,
+    dns_udp_handle = new_create_dissector_handle(dissect_dns_udp,
         proto_dns);
-    dns_tcp_handle = create_dissector_handle(dissect_dns_tcp,
+    dns_tcp_handle = new_create_dissector_handle(dissect_dns_tcp,
         proto_dns);
-    mdns_udp_handle = create_dissector_handle(dissect_mdns_udp,
+    mdns_udp_handle = new_create_dissector_handle(dissect_mdns_udp,
         proto_dns);
 
     dissector_add_uint("udp.port", UDP_PORT_DNS, dns_udp_handle);
@@ -2853,11 +2855,13 @@ The dissect_dns_udp function does very little work and calls
 dissect_dns_common, while dissect_dns_tcp calls tcp_dissect_pdus with a
 reference to a callback which will be called with reassembled data:
 
-    static void
-    dissect_dns_tcp(tvbuff_t *tvb, packet_info *pinfo, proto_tree *tree)
+    static int
+    dissect_dns_tcp(tvbuff_t *tvb, packet_info *pinfo, proto_tree *tree,
+                    void *data _U_)
     {
         tcp_dissect_pdus(tvb, pinfo, tree, dns_desegment, 2,
-            get_dns_pdu_len, dissect_dns_tcp_pdu);
+            get_dns_pdu_len, dissect_dns_tcp_pdu, data);
+        return tvb_length(tvb);
     }
 
 (The dissect_dns_tcp_pdu function acts similarly to dissect_dns_udp.)
@@ -2880,10 +2884,13 @@ The arguments to tcp_dissect_pdus are:
     might not be available, so don't refer to any data past that) - the
     total length of the PDU, in bytes;
 
-    a routine to dissect the pdu that's passed a tvbuff pointer,
-    packet_info pointer, and proto_tree pointer, with the tvbuff
-    containing a possibly-reassembled PDU.  (The "reported_length"
-    of the tvbuff will be the length of the PDU).
+    a new_dissector_t routine to dissect the pdu that's passed a tvbuff
+    pointer, packet_info pointer, proto_tree pointer and a void pointer for
+    user data, with the tvbuff containing a possibly-reassembled PDU. (The
+    "reported_length" of the tvbuff will be the length of the PDU).
+
+    a void pointer to user data that is passed to the dissector routine
+    referenced in the previous parameter.
 
 2.7.2 Modifying the pinfo struct.
 

diff --git a/docbook/wsdg_src/WSDG_chapter_dissection.xml b/docbook/wsdg_src/WSDG_chapter_dissection.xml
index 40b73bc537fd230a5541a04f2138b37af1d7bd9a..58ee50ccf7229843c5010f94a5fb08bcc372f6ad 100644 (file)
--- a/docbook/wsdg_src/WSDG_chapter_dissection.xml
+++ b/docbook/wsdg_src/WSDG_chapter_dissection.xml
@@ -978,17 +978,11 @@ static gint *ett[] =
 
 #define FRAME_HEADER_LEN 8
 
-/* The main dissecting routine */
-static void dissect_foo(tvbuff_t *tvb, packet_info *pinfo, proto_tree *tree)
-{
-    tcp_dissect_pdus(tvb, pinfo, tree, TRUE, FRAME_HEADER_LEN,
-                     get_foo_message_len, dissect_foo_message);
-}
-
 /* This method dissects fully reassembled messages */
-static void dissect_foo_message(tvbuff_t *tvb, packet_info *pinfo, proto_tree *tree)
+static int dissect_foo_message(tvbuff_t *tvb, packet_info *pinfo, proto_tree *tree, void* data _U_)
 {
     /* TODO: implement your dissecting code */
+    return tvb_length(tvb);
 }
 
 /* determine PDU length of protocol foo */
@@ -998,6 +992,14 @@ static guint get_foo_message_len(packet_info *pinfo, tvbuff_t *tvb, int offset)
     return (guint)tvb_get_ntohl(tvb, offset+4); /* e.g. length is at offset 4 */
 }
 
+/* The main dissecting routine */
+static int dissect_foo(tvbuff_t *tvb, packet_info *pinfo, proto_tree *tree, void* data)
+{
+    tcp_dissect_pdus(tvb, pinfo, tree, TRUE, FRAME_HEADER_LEN,
+                     get_foo_message_len, dissect_foo_message, data);
+    return tvb_length(tvb);
+}
+
 ...]]>
                        </programlisting>
                </example>
@@ -1007,16 +1009,17 @@ static guint get_foo_message_len(packet_info *pinfo, tvbuff_t *tvb, int offset)
                        This function gets called whenever a message has been reassembled.
                </para>
                <para>
-                       The parameters <parameter>tvb</parameter>, <parameter>pinfo</parameter> and <parameter>tree</parameter>
-                       are just handed over to <function>tcp_dissect_pdus()</function>.
-                       The 4th parameter is a flag to indicate if the data should be reassembled or not. This could be set
-                       according to a dissector preference as well.
-                       Parameter 5 indicates how much data has at least to be available to be able to determine the length
-                       of the foo message.
-                       Parameter 6 is a function pointer to a method that returns this length. It gets called when at least
-                       the number of bytes given in the previous parameter is available.
-                       Parameter 7 is a function pointer to your real message dissector.
-               </para>
+                       The parameters <parameter>tvb</parameter>, <parameter>pinfo</parameter>, <parameter>tree</parameter>
+      and <parameter>data</parameter> are just handed over to <function>tcp_dissect_pdus()</function>.
+      The 4th parameter is a flag to indicate if the data should be reassembled or not. This could be set
+      according to a dissector preference as well.
+      Parameter 5 indicates how much data has at least to be available to be able to determine the length
+      of the foo message.
+      Parameter 6 is a function pointer to a method that returns this length. It gets called when at least
+      the number of bytes given in the previous parameter is available.
+      Parameter 7 is a function pointer to your real message dissector.
+      Parameter 8 is a the data passed in from parent dissector.
+    </para>
        </section>
   </section>
   <section id="ChDissectTap">