Wireshark · Ethereal-dev: [Ethereal-dev] Patches for Documentation

[Michael Duigou <ethereal@xxxxxxxxxx>]

Adds some doxygen docs for several of the header files and a number of 
edits to the README.developer.

Hopefully useful stuff... I'd really like to see more doxygen 
documentation used across ethereal.

Mike

Index: epan/exceptions.h
===================================================================
--- epan/exceptions.h	(revision 13700)
+++ epan/exceptions.h	(working copy)
@@ -9,11 +9,32 @@
 #define XCEPT_GROUP_ETHEREAL 1
 
 /* Ethereal's exceptions */
-#define BoundsError		1	/* Index is out of range */
-#define ReportedBoundsError	2	/* Index is beyond reported length (not cap_len) */
-#define TypeError		3	/* During dfilter parsing */
-#define DissectorError		4	/* A bug was detected in a dissector */
 
+/**
+    Index is out of range.
+    An attempt was made to read past the end of a buffer.
+**/
+#define BoundsError		1	
+
+/**
+    Index is beyond reported length (not cap_len) 
+    An attempt was made to read past the logical end of a buffer. This
+    differs from a BoundsError in that the parent protocol established a
+    limit past which this dissector should not process in the buffer and that
+    limit was execeeded.
+**/
+#define ReportedBoundsError	2
+
+/**
+    During dfilter parsing 
+**/
+#define TypeError		3
+
+/**
+    A bug was detected in a dissector 
+**/
+#define DissectorError		4	
+
 /* Usage:
  *
  * TRY {
Index: epan/proto.h
===================================================================
--- epan/proto.h	(revision 13700)
+++ epan/proto.h	(working copy)
@@ -889,7 +889,7 @@
 
 
 /** Register a new protocol.
- @param name the name of the new protocol
+ @param name the full name of the new protocol
  @param short_name abbreviated name of the new protocol
  @param filter_name protocol name used for a display filter string 
  @return the new protocol handle */
Index: epan/packet.h
===================================================================
--- epan/packet.h	(revision 13700)
+++ epan/packet.h	(working copy)
@@ -90,6 +90,10 @@
 	char	*false_string;
 } true_false_string;
 
+/**
+* A default set of true/false strings that dissectors can use for 
+* FT_BOOLEAN header fields.
+**/
 extern const true_false_string flags_set_truth;
 
 extern void packet_init(void);
Index: doc/README.developer
===================================================================
--- doc/README.developer	(revision 13700)
+++ doc/README.developer	(working copy)
@@ -419,10 +419,10 @@
 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 remind to add your dissector file to the corresponding makefile, 
-described in chapter "1.9 Editing Makefile.common to add your dissector" below.
+Also, please add your dissector file to the corresponding makefile, 
+described in section "1.9 Editing Makefile.common to add your dissector" below.
 
-Dissectors that use the dissector registration to tell a lower level
+Dissectors that use the dissector registration to register with a lower level
 dissector don't need to define a prototype in the .h file. For other
 dissectors the main dissector routine should have a prototype in a header
 file whose name is "packet-", followed by the abbreviated name for the
@@ -449,7 +449,7 @@
 
 When creating a new file, it is fine to just write "$Id$" as RCS will
 automatically fill in the identifier at the time the file will be added to the
-CVS repository (checked in).
+SVN repository (checked in).
 
 ------------------------------------Cut here------------------------------------
 /* packet-PROTOABBREV.c
@@ -494,6 +494,7 @@
 #include <glib.h>
 
 #include <epan/packet.h>
+#include <epan/prefs.h>
 
 /* IF PROTO exposes code to other dissectors, then it must be exported
    in a header file. If not, a header file is not needed at all. */
@@ -503,6 +504,9 @@
 static int proto_PROTOABBREV = -1;
 static int hf_PROTOABBREV_FIELDABBREV = -1;
 
+/* Global sample preference ("controls" display of numbers) */
+static gboolean gPREF_HEX = FALSE;
+
 /* Initialize the subtree pointers */
 static gint ett_PROTOABBREV = -1;
 
@@ -519,13 +523,17 @@
 	if (check_col(pinfo->cinfo, COL_PROTOCOL)) 
 		col_set_str(pinfo->cinfo, COL_PROTOCOL, "PROTOABBREV");
     
-/* This field shows up as the "Info" column in the display; you should make
-   it, if possible, summarize what's in the packet, so that a user looking
+/* This field shows up as the "Info" column in the display; you should use
+   it, if possible, to summarize what's in the packet, so that a user looking
    at the list of packets can tell what type of packet it is. See section 1.5
    for more information.
 
-   If you are setting it to a constant string, use "col_set_str()", as
-   it's more efficient than the other "col_set_XXX()" calls.
+   Before changing the contents of a column you should make sure the column is
+   active by calling "check_col(pinfo->cinfo, COL_*)". If it is not active 
+   don't bother setting it.
+   
+   If you are setting the column to a constant string, use "col_set_str()", 
+   as it's more efficient than the other "col_set_XXX()" calls.
 
    If you're setting it to a string you've constructed, or will be
    appending to the column later, use "col_add_str()".
@@ -556,7 +564,7 @@
 		In this mode, Ethereal is only interested in the way protocols
 		interact, protocol conversations are created, packets are reassembled
 		and handed over to higher-level protocol dissectors.
-		This way Ethereal does not build a so-called "protocol tree".
+		In this mode Ethereal does not build a so-called "protocol tree".
 
 	(b) Detailed dissection
 
@@ -624,6 +632,7 @@
 void
 proto_register_PROTOABBREV(void)
 {                 
+  module_t *PROTOABBREV_module;
 
 /* Setup list of header fields  See Section 1.6.1 for details*/
 	static hf_register_info hf[] = {
@@ -646,21 +655,61 @@
 /* Required function calls to register the header fields and subtrees used */
 	proto_register_field_array(proto_PROTOABBREV, hf, array_length(hf));
 	proto_register_subtree_array(ett, array_length(ett));
+        
+/* Register preferences module (See Section 2.6 for more on preferences) */       
+        PROTOABBREV_module = prefs_register_protocol(proto_PROTOABBREV, proto_reg_handoff_PROTOABBREV);
+     
+/* Register a sample preference */        
+        prefs_register_bool_preference(PROTOABBREV_module, "showHex", 
+             "Display numbers in Hex",
+	     "Enable to display numerical values in hexidecimal.",
+	     &gPREF_HEX );        
 }
 
 
 /* If this dissector uses sub-dissector registration add a registration routine.
-   This format is required because a script is used to find these routines and
-   create the code that calls these routines.
+   This exact format is required because a script is used to find these routines 
+   and create the code that calls these routines.
+   
+   This function is also called by preferences whenever "Apply" is pressed 
+   (see prefs_register_protocol above) so it should accommodate being called 
+   more than once.
 */
 void
 proto_reg_handoff_PROTOABBREV(void)
 {
+        static gboolean inited = FALSE;
+        
+        if( inited ) {
+
 	dissector_handle_t PROTOABBREV_handle;
 
 	PROTOABBREV_handle = create_dissector_handle(dissect_PROTOABBREV,
 	    proto_PROTOABBREV);
 	dissector_add("PARENT_SUBFIELD", ID_VALUE, PROTOABBREV_handle);
+        
+        inited = TRUE;
+        }
+        
+        /* 
+          If you perform registration functions which are dependant upon
+          prefs the you should de-register everything which was associated
+          with the previous settings and re-register using the new prefs settings
+          here. In general this means you need to keep track of what value the
+          preference had at the time you registered using a local static in this
+          function. ie.
+
+          static int currentPort = -1;
+
+          if( -1 != currentPort ) {
+              dissector_delete( "tcp.port", currentPort, PROTOABBREV_handle);
+          }
+
+          currentPort = gPortPref;
+
+          dissector_add("tcp.port", currentPort, PROTOABBREV_handle);
+            
+        */
 }
 
 ------------------------------------Cut here------------------------------------
@@ -713,8 +762,8 @@
 register itself with the lower level dissector, or if the protocol dissector
 wants/needs to expose code to other subdissectors.
 
-The dissector has the following header that must be placed into
-packet-PROTOABBREV.h.
+The dissector must declared as exactly as follows in the file 
+packet-PROTOABBREV.h:
 
 void
 dissect_PROTOABBREV(tvbuff_t *tvb, packet_info *pinfo, proto_tree *tree);
@@ -722,7 +771,7 @@
 
 1.4.2 Extracting data from packets.
 
-NOTE: See the README.tvbuff for more details
+NOTE: See the README.tvbuff file for more details
 
 The "tvb" argument to a dissector points to a buffer containing the raw
 data to be analyzed by the dissector; for example, for a protocol
@@ -1888,7 +1937,7 @@
 be passed as arguments to a routine using those strings.)
 
 
-1.8 Calling Other Dissector 
+1.8 Calling Other Dissectors
 
 NOTE: This is discussed in the README.tvbuff file.  For more 
 information on tvbuffers consult that file.
@@ -1965,10 +2014,28 @@
 tarballs are built (otherwise, the source in the release tarballs won't
 compile).
 
-1.10 Using the CVS source code tree.
+1.10 Using the SVN source code tree.
 
+  See <http://www.ethereal.com/development.html#source>
+
 1.11 Submitting code for your new dissector.
 
+  - Subscribe to <mailto:ethereal-dev@xxxxxxxxxxxx> by sending an email to
+    <mailto:ethereal-dev-request@xxxxxxxxxxxx?body="help";> or visiting 
+    <http://www.ethereal.com/lists/>.
+  
+  - 'svn add' all the files of your new dissector.
+  
+  - 'svn diff' the workspace and save the result to a file.
+  
+  - Send the diff file along with a note requesting it's inclusion to
+    <mailto:ethereal-dev@xxxxxxxxxxxx>. You can also use this procedure for
+    providing patches to your dissector or any other part of ethereal.
+    
+  - If you find that you are contributing a lot to ethereal on an ongoing
+    basis you can request to become a committer which will allow you to commit
+    files to subversion directly.
+
 2. Advanced dissector topics.
 
 2.1 ?? 
@@ -2244,11 +2311,11 @@
 upon the conversation index and values inside the request packets. 
 
 
-/* in the dissector routine */
+        /* in the dissector routine */
 
-/* to find a request value, first lookup conversation to get index */
-/* then used the conversation index, and request data to find data */
-/* in the local hash table */
+        /* to find a request value, first lookup conversation to get index */
+        /* then used the conversation index, and request data to find data */
+        /* in the local hash table */
 
 	conversation = find_conversation(&pinfo->src, &pinfo->dst, pinfo->ptype,
 	    pinfo->srcport, pinfo->destport, 0);
@@ -2285,7 +2352,7 @@
 2.3 Dynamic conversation dissector registration
 
 
-NOTE: This sections assumes that all information is available to
+NOTE:   This sections assumes that all information is available to
 	create a complete conversation, source port/address and
 	destination port/address.  If either the destination port or
 	address is know, see section 2.4 Dynamic server port dissector
@@ -2516,17 +2583,17 @@
 
 2.7 Reassembly/desegmentation for protocols running atop TCP
 
-There are two main ways of reassembling PDUs spanning across multiple
-TCP segmentss.  The first one is simpler, but assumes you are running
-atop of TCP when this occurs (but your dissector might run atop of UDP,
-too, for example), and that your PDUs consist of a fixed amount of data
-that includes enough information to determine the PDU length, possibly
-followed by additional data.  The second one is more generic but
-requires more code and is less efficient.
+There are two main ways of reassembling a Protocol Data Unit (PDU) which
+spans across multiple TCP segments.  The first approach is simpler, but  
+assumes you are running atop of TCP when this occurs (but your dissector  
+might run atop of UDP, too, for example), and that your PDUs consist of a  
+fixed amount of data that includes enough information to determine the PDU 
+length, possibly followed by additional data.  The second method is more 
+generic but requires more code and is less efficient.
 
 For the first method, you register two different dissection methods, one
 for the TCP case, and one for the other cases.  It is a good idea to
-have a dissect_PROTO_common function which will parse the generic
+also have a dissect_PROTO_common function which will parse the generic
 content that you can find in all PDUs which is called from
 dissect_PROTO_tcp when the reassembly is complete and from
 dissect_PROTO_udp (or dissect_PROTO_other).