More API documentation.

scripts/base/frameworks/analyzer/main.bro

@@ -1,43 +1,90 @@
-
+##! Framework for managing Bro's protocol analyzers.
+##!
+##! The analyzer framework allows to dynamically enable or disable analyzers, as
+##! well as to manage the well-known ports which automatically active a particular
+##! analyzer for new connections.  
+##! 
+##! Protocol analyzers are identified by unique tags of type
+##! :bro:type:`Analyzer::Tag`, such as :bro:enum:`Analyzer::ANALYZER_HTTP` and
+##! :bro:enum:`Analyzer::ANALYZER_HTTP`. These tags are defined internally by the
+##! analyzers themselves, and documented in their analyzer-specific description along with the
+##! events that they generate.
+##!
+##! .. todo: ``The ANALYZER_*`` are in fact not yet documented, we need to add that
+##!    to Broxygen. 
 module Analyzer;
 
-# Analyzer::Tag is defined in types.bif, and automatically extended by plugins
-# as they are loaded.
-
 export {
-	## XXX
+	## If true, all available analyzers are initially disabled at startup. One can
+	## then selectively enable them with :bro:id:`enable_analyzer`. 
 	global disable_all = F &redef;
 
-	## XXX.
+	## Enables an analyzer. Once enabled, the analyzer may be used for analysis of
+	## future connections as decided by Bro's dynamic protocol detection.  
+	##
+	## tag: The tag of the analyzer to enable.
+	##
+	## Returns: True if the analyzer was successfully enabled.
 	global enable_analyzer: function(tag: Analyzer::Tag) : bool;
 
-	## XXX.
+	## Disables an analyzer. Once disabled, the analyzer will not be used
+	## further for analysis of future connections. 
+	##
+	## tag: The tag of the analyzer to disable. 
+	##
+	## Returns: True if the analyzer was successfully disabled.  
 	global disable_analyzer: function(tag: Analyzer::Tag) : bool;
 
-	## XXX.
+	## Registers a set of well-known ports for an analyzer. If a future connection
+	## on one of these ports is seen, the analyzer will be automatically assigned
+	## to parsing it. The function *adds* to all ports already registered, it doesn't
+	## replace them .
+	##
+	## tag: The tag of the analyzer. 
+	##
+	## ports: The set of well-known ports to associate with the analyzer.  
+	##
+	## Returns: True if the ports were sucessfully registered. 
 	global register_for_ports: function(tag: Analyzer::Tag, ports: set[port]) : bool;
 
-	## XXX.
+	## Registers an individual well-known port for an analyzer. If a future connection
+	## on this ports is seen, the analyzer will be automatically assigned to parsing
+	## it. The function *adds* to all ports already registered, it doesn't
+	## replace them .
+	##
+	## tag: The tag of the analyzer. 
+	##
+	## p: The well-known port to associate with the analyzer.  
+	##
+	## Returns: True if the port was sucessfully registered.
 	global register_for_port: function(tag: Analyzer::Tag, p: port) : bool;
 
-	## XXX.
+	## Returns a set of all well-known ports currently registered for a
+	## specific analyzer.  
+	## 
+	## tag: The tag of the analyzer. 
+	##
+	## Returns: The set of ports.
 	global registered_ports: function(tag: Analyzer::Tag) : set[port];
 
-	## XXX
+	## Returns a table of all ports-to-analyzer mappings currently registered. 
+	## 
+	## Returns: A table mapping each analyzer to the set of ports
+	## registered for it.
 	global all_registered_ports: function() : table[Analyzer::Tag] of set[port]; 
 
-	## Translate an analyzer type to an ASCII string.
+	## Translates an analyzer type to a string with the analyzer's.
 	##
-	## atype: The analyzer tag.
+	## tag: The analyzer tag.
 	##
-	## Returns: The analyzer *aid* as string.
+	## Returns: The analyzer name corresponding to the tag. 
-	global name: function(atype: Analyzer::Tag) : string;
+	global name: function(tag: Analyzer::Tag) : string;
 
-	## Schedules an analyzer for a future connection from a given IP address and
+	## Schedules an analyzer for a future connection originating from a given IP
-	## port. The function ignores the scheduling request if the connection did
+	## address and port.     
-	## not occur within the specified time interval.
 	##
-	## orig: The IP address originating a connection in the future.
+	## orig: The IP address originating a connection in the future. 
+	## 0.0.0.0 can be used as a wildcard to match any originator address.
 	##
 	## resp: The IP address responding to a connection from *orig*.
 	##
@@ -45,13 +92,15 @@ export {
 	##
 	## analyzer: The analyzer ID.
 	##
-	## tout: The timeout interval after which to ignore the scheduling request.
+	## tout: A timeout interval after which the scheduling request will be
+	## discarded if the connection has not yet been seen.
 	##
 	## Returns: True if succesful.
 	global schedule_analyzer: function(orig: addr, resp: addr, resp_p: port,
 					   analyzer: Analyzer::Tag, tout: interval) : bool;
 
-	## Analyzers to disable at startup.
+	## A set of analyzers to disable by at startup. The default set
+	## contains legacy analyzers that are no longer supported.
 	global disabled_analyzers: set[Analyzer::Tag] = {
 		ANALYZER_INTERCONN,
 		ANALYZER_STEPPINGSTONE,

src/analyzer/Analyzer.h

@@ -28,23 +28,39 @@ typedef list<Analyzer*> analyzer_list;
 typedef uint32 ID;
 typedef void (Analyzer::*analyzer_timer_func)(double t);
 
-	/**
+/**
-	 * XXX
+ * Class to receive processed output from an anlyzer.
-	 */
+ */
 class OutputHandler {
 public:
+	/**
+	 * Destructor.
+	 */
 	virtual	~OutputHandler() { }
 
+	/**
+	 * Hook for receiving packet data. Parameters are the same as for
+	 * Analyzer::DeliverPacket().
+	 */
 	virtual void DeliverPacket(int len, const u_char* data,
 				   bool orig, int seq,
 				   const IP_Hdr* ip, int caplen)
 		{ }
+
+	/**
+	 * Hook for receiving stream data. Parameters are the same as for
+	 * Analyzer::DeliverStream().
+	 */
 	virtual void DeliverStream(int len, const u_char* data,
 				   bool orig)	{ }
+
+	/**
+	 * Hook for receiving notification of stream gaps. Parameters are the
+	 * same as for Analyzer::Undelivered().
+	 */
 	virtual void Undelivered(int seq, int len, bool orig)	{ }
 };
 
-
 /**
  * Main analyzer interface.
  *