Bugfixes and test updates.

src/iosource/Component.cc

@@ -1,3 +1,4 @@
+// See the file "COPYING" in the main distribution directory for copyright.
 
 #include "Component.h"
 

src/iosource/Component.h

@@ -22,7 +22,10 @@ public:
 	typedef IOSource* (*factory_callback)();
 
 	/**
-	 * XXX
+	 * Constructor.
+	 *
+	 * @param name A descriptive name for the component.  This name must
+	 * be unique across all components of this type.
 	 */
 	Component(const std::string& name);
 
@@ -37,9 +40,14 @@ public:
 	~Component();
 
 protected:
-    /**
-     * XXXX
-     */
+	/**
+	 * Constructor to use by derived classes.
+	 *
+	 * @param type The type of the componnent.
+	 *
+	 * @param name A descriptive name for the component.  This name must
+	 * be unique across all components of this type.
+	 */
 	Component(plugin::component::Type type, const std::string& name);
 };
 
@@ -48,12 +56,29 @@ protected:
  */
 class PktSrcComponent : public iosource::Component {
 public:
-	enum InputType { LIVE, TRACE, BOTH };
+	/**
+	 * Type of input a packet source supports.
+	 */
+	enum InputType {
+		LIVE,	///< Live input.
+		TRACE,		///< Offline input from trace file.
+		BOTH	///< Live input as well as offline.
+	};
 
 	typedef PktSrc* (*factory_callback)(const std::string& path, bool is_live);
 
 	/**
-	 * XXX
+	 * Constructor.
+	 *
+	 * @param name A descriptive name for the component.  This name must
+	 * be unique across all components of this type.
+	 *
+	 * @param prefixes The list of interface/file prefixes associated
+	 * with this component.
+	 *
+	 * @param type Type of input the component supports.
+	 *
+	 * @param factor Factory function to instantiate component.
 	 */
 	PktSrcComponent(const std::string& name, const std::string& prefixes, InputType type, factory_callback factory);
 

src/iosource/IOSource.h

@@ -14,56 +14,120 @@ extern "C" {
 namespace iosource {
 
 /**
- * Interface class for components providing/consuming data inside Bro's main loop.
+ * Interface class for components providing/consuming data inside Bro's main
+ * loop.
  */
 class IOSource {
 public:
+	/**
+	 * Constructor.
+	 */
 	IOSource()	{ idle = false; closed = false; }
+
+	/**
+	 * Destructor.
+	 */
 	virtual ~IOSource()	{}
 
-	// Returns true if source has nothing ready to process.
+	/**
+	 * Returns true if source has nothing ready to process.
+	 */
 	bool IsIdle() const	{ return idle; }
 
-	// Returns true if more data is to be expected in the future.
-	// Otherwise, source may be removed.
+	/**
+	 * Returns true if more data is to be expected in the future.
+	 * Otherwise, source may be removed.
+	 */
 	bool IsOpen() const	{ return ! closed; }
 
-	// XXX
+	/**
+	 * Initializes the source. Can be overwritten by derived classes.
+	 */
 	virtual void Init()	{ }
 
-	// XXX
+	/**
+	 * Finalizes the source when it's being closed. Can be overwritten by
+	 * derived classes.
+	 */
 	virtual void Done()	{ }
 
-	// Returns select'able fds (leaves args untouched if we don't have
-	// selectable fds).
+	/**
+	 * Returns select'able file descriptors for this source. Leaves the
+	 * passed values untouched if not available.
+	 *
+	 * @param read Pointer to where to store a read descriptor.
+	 *
+	 * @param write Pointer to where to store a write descriptor.
+	 *
+	 * @param except Pointer to where to store a except descriptor.
+	 */
 	virtual void GetFds(int* read, int* write, int* except) = 0;
 
-	// The following two methods are only called when either IsIdle()
-	// returns false or select() on one of the fds indicates that there's
-	// data to process.
-
-	// Returns timestamp (in global network time) associated with next
-	// data item.  If the source wants the data item to be processed
-	// with a local network time, it sets the argument accordingly.
+	/**
+	 * Returns the timestamp (in \a global network time) associated with
+	 * next data item from this source.  If the source wants the data
+	 * item to be processed with a local network time, it sets the
+	 * argument accordingly.
+	 *
+	 * This method will be called only when either IsIdle() returns
+	 * false, or select() on one of the fds returned by GetFDs()
+	 * indicates that there's data to process.
+	 *
+	 * Must be overridden by derived classes.
+	 *
+	 * @param network_time A pointer to store the \a local network time
+	 * associated with the next item (as opposed to global network time).
+	 *
+	 * @return The global network time of the next entry, or a value
+	 * smaller than zero if none is available currently.
+	 */
 	virtual double NextTimestamp(double* network_time) = 0;
 
-	// Processes and consumes next data item.
+	/**
+	 * Processes and consumes next data item.
+	 *
+	 * This method will be called only when either IsIdle() returns
+	 * false, or select() on one of the fds returned by GetFDs()
+	 * indicates that there's data to process.
+	 *
+	 * Must be overridden by derived classes.
+	 */
 	virtual void Process() = 0;
 
-	// Returns tag of timer manager associated with last processed
-	// data item, nil for global timer manager.
+	/**
+	 * Returns the tag of the timer manafger associated with the last
+	 * procesees data item.
+	 *
+	 * Can be overridden by derived classes.
+	 *
+	 * @return The tag, or null for the global timer manager.
+	 * 
+	 */
 	virtual TimerMgr::Tag* GetCurrentTag()	{ return 0; }
 
-	// Returns a descriptual tag for debugging.
+	/**
+	 * Returns a descriptual tag representing the source for debugging.
+	 *
+	 * Can be overridden by derived classes.
+	 *
+	 * @return The debugging name.
+	 */
 	virtual const char* Tag() = 0;
 
 protected:
-	// Derived classed are to set this to true if they have gone dry
-	// temporarily.
+	/*
+	 * Callback for derived classes to call when they have gone dry
+	 * temporarily.
+	 *
+	 * @param is_idle True if the source is idle currently.
+	 */
 	void SetIdle(bool is_idle)	{ idle = is_idle; }
 
-	// Derived classed are to set this to true if they have gone dry
-	// temporarily.
+	/*
+	 * Callback for derived class to call when they have shutdown.
+	 *
+	 * @param is_closed True if the source is now closed.
+	 */
 	void SetClosed(bool is_closed)	{ closed = is_closed; }
 
 private:

src/iosource/Manager.cc

@@ -1,3 +1,4 @@
+// See the file "COPYING" in the main distribution directory for copyright.
 
 #include <sys/types.h>
 #include <sys/time.h>
@@ -22,7 +23,7 @@ Manager::~Manager()
 	{
 	for ( SourceList::iterator i = sources.begin(); i != sources.end(); ++i )
 		{
-		// ??? (*i)->src->Done();
+		(*i)->src->Done();
 		delete *i;
 		}
 

src/iosource/Manager.h

@@ -12,43 +12,100 @@ class IOSource;
 class PktSrc;
 class PktDumper;
 
+/**
+ * Singleton class managing all IOSources.
+ */
 class Manager {
 public:
+	/**
+	 * Constructor.
+	 */
 	Manager()	{ call_count = 0; dont_counts = 0; }
+
+	/**
+	 * Destructor.
+	 */
 	~Manager();
 
-	// If dont_count is true, this source does not contribute to the
-	// number of IOSources returned by Size().  The effect is that
-	// if all sources but the non-counting ones have gone dry,
-	// processing will shut down.
+	/**
+	 * Registers an IOSource with the manager.
+	 *
+	 * @param src The source. The manager takes ownership.
+	 *
+	 * @param dont_count If true, this source does not contribute to the
+	 * number of IOSources returned by Size().  The effect is that if all
+	 * sources except for the non-counting ones have gone dry, processing
+	 * will shut down.
+	 */
 	void Register(IOSource* src, bool dont_count = false);
 
-	// This may block for some time.
+	/**
+	 * Returns the packet source with the soonest available input. This
+	 * may block for a little while if all are dry.
+	 *
+	 * @param ts A pointer where to store the timestamp of the input that
+	 * the soonest source has available next. 
+	 *
+	 * @return The source, or null if no source has input.
+	 */
 	IOSource* FindSoonest(double* ts);
 
+	/**
+	 * Returns the number of registered and still active sources,
+	 * excluding those that are registered as \a dont_cont.
+	 */
 	int Size() const	{ return sources.size() - dont_counts; }
 
 	typedef std::list<PktSrc *> PktSrcList;
+
+	/**
+	 * Returns a list of all registered PktSrc instances. This is a
+	 * subset of all registered IOSource instances.
+	 */
 	const PktSrcList& GetPktSrcs() const	{ return pkt_srcs; }
 
-	// Terminate IOSource processing immediately by removing all
-	// sources (and therefore returning a Size() of zero).
+	/**
+	 * Terminate all processing immediately by removing all sources (and
+	 * therefore now returning a Size() of zero).
+	 */
 	void Terminate()	{ RemoveAll(); }
 
+	/**
+	 * Opens a new packet source.
+	 *
+	 * @param path The interface or file name, as one would give to Bro \c -i.
+	 *
+	 * @param is_live True if \a path represents a live interface, false
+	 * for a file.
+	 *
+	 * @return The new packet source, or null if an error occured.
+	 */
 	PktSrc* OpenPktSrc(const std::string& path, bool is_live);
+
+	/**
+	 * Opens a new packet dumper.
+	 *
+	 * @param path The file name to dump into.
+	 *
+	 * @param append True to append if \a path already exists.
+ 	 *
+	 * @return The new packet dumper, or null if an error occured.
+	 */
 	PktDumper* OpenPktDumper(const std::string& path, bool append);
 
-protected:
-	void Register(PktSrc* src);
-
-	// When looking for a source with something to process,
-	// every SELECT_FREQUENCY calls we will go ahead and
-	// block on a select().
+private:
+	/**
+	 * When looking for a source with something to process, every
+	 * SELECT_FREQUENCY calls we will go ahead and block on a select().
+	 */
 	static const int SELECT_FREQUENCY = 25;
 
-	// Microseconds to wait in an empty select if no source is ready.
+	/**
+	 * Microseconds to wait in an empty select if no source is ready.
+	 */
 	static const int SELECT_TIMEOUT = 50;
 
+	void Register(PktSrc* src);
 	void RemoveAll();
 
 	unsigned int call_count;

src/iosource/PktDumper.h

@@ -7,6 +7,9 @@
 
 namespace iosource {
 
+/**
+ * Base class for packet dumpers.
+ */
 class PktDumper {
 public:
 	/**

src/iosource/PktSrc.cc

@@ -387,13 +387,13 @@ void PktSrc::Process()
 	if ( pseudo_realtime )
 		{
 		current_pseudo = CheckPseudoTime();
-		net_packet_dispatch(current_pseudo, current_packet.hdr, current_packet.data, pkt_hdr_size, this);
+		net_packet_dispatch(current_pseudo, current_packet.hdr, data, pkt_hdr_size, this);
 		if ( ! first_wallclock )
 			first_wallclock = current_time(true);
 		}
 
 	else
-		net_packet_dispatch(current_packet.ts, current_packet.hdr, current_packet.data, pkt_hdr_size, this);
+		net_packet_dispatch(current_packet.ts, current_packet.hdr, data, pkt_hdr_size, this);
 
 	have_packet = 0;
 	DoneWithPacket();

src/iosource/PktSrc.h

@@ -11,6 +11,9 @@ declare(PDict,BPF_Program);
 
 namespace iosource {
 
+/**
+ * Base class for packet sources.
+ */
 class PktSrc : public IOSource {
 public:
 	/**

src/iosource/pcap/Dumper.h

@@ -1,3 +1,4 @@
+// See the file  in the main distribution directory for copyright.
 
 #ifndef IOSOURCE_PKTSRC_PCAP_DUMPER_H
 #define IOSOURCE_PKTSRC_PCAP_DUMPER_H

src/iosource/pcap/Source.cc

@@ -1,3 +1,4 @@
+// See the file  in the main distribution directory for copyright.
 
 #include <assert.h>