Add doxygen comments.

svn path=/trunk/; revision=49146

1 files changed, 175 insertions, 3 deletions

diff --git a/epan/tap.h b/epan/tap.h
index 184ad52242..b95b98df94 100644
--- a/epan/tap.h
+++ b/epan/tap.h
@@ -36,34 +36,206 @@ typedef void (*tap_reset_cb)(void *tapdata);
 typedef gboolean (*tap_packet_cb)(void *tapdata, packet_info *pinfo, epan_dissect_t *edt, const void *data);
 typedef void (*tap_draw_cb)(void *tapdata);
 
-/*
+/**
  * Flags to indicate what a tap listener's packet routine requires.
  */
 #define TL_REQUIRES_NOTHING	0x00000000	/**< nothing */
 #define TL_REQUIRES_PROTO_TREE	0x00000001	/**< full protocol tree */
 #define TL_REQUIRES_COLUMNS	0x00000002	/**< columns */
-/* Flags to indicate what the tap listener does */
-#define TL_IS_DISSECTOR_HELPER	0x00000004	/** tap helps a dissector do work
+/** Flags to indicate what the tap listener does */
+#define TL_IS_DISSECTOR_HELPER	0x00000004	/**< tap helps a dissector do work
 						 ** but does not, itself, require dissection */
 
 extern void tap_init(void);
+
+/** This function registers that a dissector has the packet tap ability
+ *  available.  The name parameter is the name of this tap and extensions can
+ *  use open_tap(char *name,... to specify that it wants to receive packets/
+ *  events from this tap.
+ *
+ *  This function is only to be called once, when the dissector initializes.
+ *
+ *  The return value from this call is later used as a parameter to the
+ *  tap_packet(unsigned int *tap_id,...
+ *  call so that the tap subsystem knows to which tap point this tapped
+ *  packet is associated.
+ */
 WS_DLL_PUBLIC int register_tap(const char *name);
+
+/** This function will return the tap_id for the specific protocol tap
+ *  or 0 if no such tap was found.
+ */
 WS_DLL_PUBLIC int find_tap_id(const char *name);
+
+/** Everytime the dissector has finished dissecting a packet (and all
+ *  subdissectors have returned) and if the dissector has been made "tappable"
+ *  it will push some data to everyone tapping this layer by a call
+ *  to tap_queue_packet().
+ *  The first parameter is the tap_id returned by the register_tap()
+ *  call for this dissector (so the tap system can keep track of who it came
+ *  from and who is listening to it)
+ *  The second is the packet_info structure which many tap readers will find
+ *  interesting.
+ *  The third argument is specific to each tap point or NULL if no additional
+ *  data is available to this tap.  A tap point in say IP will probably want to
+ *  push the IP header structure here. Same thing for TCP and ONCRPC.
+ *
+ *  The pinfo and the specific pointer are what is supplied to every listener
+ *  in the read_callback() call made to every one currently listening to this
+ *  tap.
+ *
+ *  The tap reader is responsible to know how to parse any structure pointed
+ *  to by the tap specific data pointer.
+ */
 WS_DLL_PUBLIC void tap_queue_packet(int tap_id, packet_info *pinfo, const void *tap_specific_data);
+
+/** Functions used by file.c to drive the tap subsystem */
 WS_DLL_PUBLIC void tap_build_interesting(epan_dissect_t *edt);
+
+/** This function is used to delete/initialize the tap queue and prime an
+ *  epan_dissect_t with all the filters for tap listeners.
+ *  To free the tap queue, we just prepend the used queue to the free queue.
+ */
 extern void tap_queue_init(epan_dissect_t *edt);
+
+/** this function is called after a packet has been fully dissected to push the tapped
+ *  data to all extensions that has callbacks registered.
+ */
+
 extern void tap_push_tapped_queue(epan_dissect_t *edt);
+
+/** This function is called after a packet has been fully dissected to push the tapped
+ *  data to all extensions that has callbacks registered.
+ */
+
 WS_DLL_PUBLIC void reset_tap_listeners(void);
+
+/** This function is called when we need to redraw all tap listeners, for example
+ * when we open/start a new capture or if we need to rescan the packet list.
+ * It should be called from a low priority thread say once every 3 seconds 
+ *
+ * If draw_all is true, redraw all aplications regardless if they have
+ * changed or not.
+ */
 WS_DLL_PUBLIC void draw_tap_listeners(gboolean draw_all);
+
+/** this function attaches the tap_listener to the named tap.
+ * function returns :
+ *     NULL: ok.
+ * non-NULL: error, return value points to GString containing error
+ *           message.
+ * @param tapname    The name of the tap we want to listen to.
+ * @param tapdata    is the instance identifier. The tap system uses the value of this
+ *                   pointer to distinguish between different instances of a tap.
+ *                   Just make sure that it is unique by letting it be the pointer to a struct
+ *                   holding all state variables. If you want to allow multiple concurrent
+ *                   instances, just put ALL state variables inside a struct allocated by
+ *                   g_malloc() and use that pointer.
+ * @param fstring    is a pointer to a filter string.
+ *                   If this is NULL, then the tap system will provide ALL packets passing the
+ *                   tapped protocol to your listener.
+ *                   If you specify a filter string here the tap system will first try
+ *                   to apply this string to the packet and then only pass those packets that
+ *                   matched the filter to your listener.
+ *                   The syntax for the filter string is identical to normal display filters.
+ *                
+ *                   NOTE: Specifying filter strings will have a significant performance impact
+ *                   on your application and Wireshark. If possible it is MUCH better to take
+ *                   unfiltered data and just filter it yourself in the packet-callback than
+ *                   to specify a filter string.
+ *                   ONLY use a filter string if no other option exist.
+ *
+ * @param flags      is a set of flags for the tap listener.  The flags that can be set are:
+ *
+ *                      TL_REQUIRES_PROTO_TREE
+ *                   
+ *                   	set if your tap listener "packet" routine requires a protocol
+ *                   	tree to be built.  It will require a protocol tree to be
+ *                   	built if either
+ *
+ *                   		1) it looks at the protocol tree in edt->tree
+ *
+ *                   	or
+ *                   
+ *                   		2) the tap-specific data passed to it is constructed only if
+ *                   		   the protocol tree is being built.
+ *
+ *                      TL_REQUIRES_COLUMNS
+ *
+ *                   	set if your tap listener "packet" routine requires the column
+ *                   	strings to be constructed.
+ *
+ *                       If no flags are needed, use TL_REQUIRES_NOTHING.
+ * 
+ * @param tap_reset  void (*reset)(void *tapdata)
+ *                   This callback is called whenever Wireshark wants to inform your
+ *                   listener that it is about to start [re]reading a capture file or a new capture
+ *                   from an interface and that your application should reset any state it has
+ *                   in the *tapdata instance.
+ * @param tap_packet gboolean (*packet)(void *tapdata, packet_info *pinfo, epan_dissect_t *edt, const void *data)
+ *                   This callback is used whenever a new packet has arrived at the tap and that
+ *                   it has passed the filter (if there were a filter).
+ *                   The *data structure type is specific to each tap.
+ *                   This function returns an gboolean and it should return
+ *                    TRUE, if the data in the packet caused state to be updated
+ *                          (and thus a redraw of the window would later be required)
+ *                    FALSE, if we don't need to redraw the window.
+ *                   NOTE: that (*packet) should be as fast and efficient as possible. Use this
+ *                   function ONLY to store data for later and do the CPU-intensive processing
+ *                   or GUI updates down in (*draw) instead.
+ * @param tap_draw   void (*draw)(void *tapdata)
+ *                   This callback is used when Wireshark wants your application to redraw its
+ *                   output. It will usually not be called unless your application has received
+ *                   new data through the (*packet) callback.
+ *                   On some ports of Wireshark (gtk2) (*draw) will be called asynchronously
+ *                   from a separate thread up to once every 2-3 seconds.
+ *                   On other ports it might only be called once when the capture is finished
+ *                   or the file has been [re]read completely.
+ */
+
 WS_DLL_PUBLIC GString *register_tap_listener(const char *tapname, void *tapdata,
     const char *fstring, guint flags, tap_reset_cb tap_reset,
     tap_packet_cb tap_packet, tap_draw_cb tap_draw);
+
+/** This function sets a new dfilter to a tap listener */
 WS_DLL_PUBLIC GString *set_tap_dfilter(void *tapdata, const char *fstring);
+
+/** this function removes a tap listener */
 WS_DLL_PUBLIC void remove_tap_listener(void *tapdata);
+
+/**
+ * Return TRUE if we have one or more tap listeners that require dissection,
+ * FALSE otherwise.
+ */
 WS_DLL_PUBLIC gboolean tap_listeners_require_dissection(void);
+
+/** Returns TRUE there is an active tap listener for the specified tap id. */
 extern gboolean have_tap_listener(int tap_id);
+
+/** Return TRUE if we have any tap listeners with filters, FALSE otherwise. */
 WS_DLL_PUBLIC gboolean have_filtering_tap_listeners(void);
+
+/**
+ * Get the union of all the flags for all the tap listeners; that gives
+ * an indication of whether the protocol tree, or the columns, are
+ * required by any taps.
+ */
 WS_DLL_PUBLIC guint union_of_tap_listener_flags(void);
+
+/** This function can be used by a dissector to fetch any tapped data before
+ * returning.
+ * This can be useful if one wants to extract the data inside dissector  BEFORE
+ * it exists as an alternative to the callbacks that are all called AFTER the
+ * dissection has completed.
+ *
+ * Example: SMB2 uses this mechanism to extract the data tapped from NTLMSSP
+ * containing the account and domain names before exiting.
+ * Note that the SMB2 tap listener specifies all three callbacks as NULL.
+ *
+ * Beware: when using this mechanism to extract the tapped data you can not
+ * use "filters" and should specify the "filter" as NULL when registering
+ * the tap listener.
+ */
 WS_DLL_PUBLIC const void *fetch_tapped_data(int tap_id, int idx);
 
 #ifdef __cplusplus