More explanation of example heuristic code.

Approach suggested by Jeff seems right to me:
https://www.wireshark.org/lists/wireshark-dev/201402/msg00198.html

Change-Id: I3d54cb49e2f0027ee79f68a633f57382101241b5
Reviewed-on: https://code.wireshark.org/review/350
Reviewed-by: Evan Huus <eapache@gmail.com>

1 files changed, 16 insertions, 11 deletions

diff --git a/doc/packet-PROTOABBREV.c b/doc/packet-PROTOABBREV.c
index b1fedfec41..0315082b89 100644
--- a/doc/packet-PROTOABBREV.c
+++ b/doc/packet-PROTOABBREV.c
@@ -96,20 +96,25 @@ dissect_PROTOABBREV(tvbuff_t *tvb, packet_info *pinfo, proto_tree *tree,
      * For example:
      */
 
-    /* Check that the packet is long enough for it to belong to us */
+    /* Check that the packet is long enough for it to belong to us. */
     if (tvb_reported_length(tvb) < PROTOABBREV_MIN_LENGTH)
         return 0;
 
-    /* Check that there's enough data present to run the heuristics */
-    if (tvb_captured_length(tvb) > SOME_HEURISTIC_VALUE) {
-        /* Fetch some values from the packet header using tvb_get_*(). If these
-         * values are not valid/possible in your protocol then return 0 to give
-         * some other dissector a chance to dissect it.
-         */
-        if ( TEST_HEURISTICS )
-            /* these values are not possible in PROTONAME */
-            return 0;
-    }
+    /* Check that there's enough data present to run the heuristics. If there
+     * isn't, reject the packet; it will probably be dissected as data and if
+     * the user wants it dissected despite it being short they can use the
+     * "Decode-As" functionality. If your heuristic needs to look very deep into
+     * the packet you may not want to require *all* data to be present, but you
+     * should ensure that the heuristic does not access beyond the captured
+     * length of the packet regardless. */
+    if (tvb_captured_length(tvb) < MAX_NEEDED_FOR_HEURISTICS)
+        return 0;
+
+    /* Fetch some values from the packet header using tvb_get_*(). If these
+     * values are not valid/possible in your protocol then return 0 to give
+     * some other dissector a chance to dissect it. */
+    if ( TEST_HEURISTICS_FAIL )
+        return 0;
 
     /*** COLUMN DATA ***/