Polishing, mostly documentation updates.

src/plugin/Plugin.h

@@ -10,7 +10,7 @@
 #include "analyzer/Component.h"
 #include "file_analysis/Component.h"
 
-#define BRO_PLUGIN_API_VERSION 2
+static const int BRO_PLUGIN_API_VERSION = 2;
 
 class ODesc;
 class Func;
@@ -28,16 +28,16 @@ class Plugin;
  */
 enum HookType {
 	// Note: when changing this table, update hook_name() in Plugin.cc.
-	HOOK_LOAD_FILE,
-	HOOK_CALL_FUNCTION,
-	HOOK_QUEUE_EVENT,
-	HOOK_DRAIN_EVENTS,
-	HOOK_UPDATE_NETWORK_TIME,
-	HOOK_BRO_OBJ_DTOR,
+	HOOK_LOAD_FILE,			//< Activates Plugin::HookLoadFile().
+	HOOK_CALL_FUNCTION,		//< Activates Plugin::HookCallFunction().
+	HOOK_QUEUE_EVENT,		//< Activates Plugin::HookQueueEvent().
+	HOOK_DRAIN_EVENTS,		//< Activates Plugin::HookDrainEvents()
+	HOOK_UPDATE_NETWORK_TIME,	//< Activates Plugin::HookUpdateNetworkTime.
+	HOOK_BRO_OBJ_DTOR,		//< Activates Plugin::HookBroObjDtor.
 
 	// Meta hooks.
-	META_HOOK_PRE,
-	META_HOOK_POST,
+	META_HOOK_PRE,			//< Activates Plugin::MetaHookPre().
+	META_HOOK_POST,			//< Activates Plugin::MetaHookPost().
 
 	// End marker.
 	NUM_HOOKS,
@@ -49,15 +49,20 @@ enum HookType {
 extern const char* hook_name(HookType h);
 
 /**
- * Helper class to capture a plugin's version. A boolean operator evaluates
- * to true if the version has been set.
- */
+ * Helper class to capture a plugin's version.
+ * */
 struct VersionNumber {
 	int major; //< Major version number;
 	int minor; //< Minor version number;
 
+	/**
+	 *  Constructor.
+	 */
 	VersionNumber()	{ major = minor = -1; }
 
+	/**
+	 *  Returns true if the version is set to a non-negative value.
+	 */
 	operator bool() const { return major >= 0 && minor >= 0; }
 };
 
@@ -133,32 +138,127 @@ private:
 class HookArgument
 {
 public:
+	/**
+	 * Type of the argument.
+	 */
 	enum Type {
 		BOOL, DOUBLE, EVENT, FUNC, INT, STRING, VAL, VAL_LIST, VOID, VOIDP,
 	};
 
+	/**
+	 * Default constructor initialized the argument with type VOID.
+	 */
 	HookArgument()	{ type = VOID; }
+
+	/**
+	 * Constructor with a boolean argument.
+	 */
 	HookArgument(bool a)	{ type = BOOL; arg.bool_ = a; }
+
+	/**
+	 * Constructor with a double argument.
+	 */
 	HookArgument(double a)	{ type = DOUBLE; arg.double_ = a; }
+
+	/**
+	 * Constructor with an event argument.
+	 */
 	HookArgument(const Event* a)	{ type = EVENT; arg.event = a; }
+
+	/**
+	 * Constructor with a function argument.
+	 */
 	HookArgument(const Func* a)	{ type = FUNC; arg.func = a; }
+
+	/**
+	 * Constructor with an integer  argument.
+	 */
 	HookArgument(int a)	{ type = INT; arg.int_ = a; }
+
+	/**
+	 * Constructor with a string argument.
+	 */
 	HookArgument(const std::string& a)	{ type = STRING; arg_string = a; }
+
+	/**
+	 * Constructor with a Bro value argument.
+	 */
 	HookArgument(const Val* a)	{ type = VAL; arg.val = a; }
+
+	/**
+	 * Constructor with a list of Bro values argument.
+	 */
 	HookArgument(const val_list* a)	{ type = VAL_LIST; arg.vals = a; }
+
+	/**
+	 * Constructor with a void pointer argument.
+	 */
 	HookArgument(void* p)	{ type = VOIDP; arg.voidp = p; }
 
+	/**
+	 * Returns the value for a boolen argument. The argument's type must
+	 * match accordingly.
+	 */
 	bool AsBool() const	{ assert(type == BOOL); return arg.bool_; }
+
+	/**
+	 * Returns the value for a double argument. The argument's type must
+	 * match accordingly.
+	 */
 	double AsDouble() const	{ assert(type == DOUBLE); return arg.double_; }
+
+	/**
+	 * Returns the value for an event argument. The argument's type must
+	 * match accordingly.
+	 */
 	const Event* AsEvent() const	{ assert(type == EVENT); return arg.event; }
+
+	/**
+	 * Returns the value for a function argument. The argument's type must
+	 * match accordingly.
+	 */
 	const Func* AsFunc() const	{ assert(type == FUNC); return arg.func; }
+
+	/**
+	 * Returns the value for an integer argument. The argument's type must
+	 * match accordingly.
+	 */
 	double AsInt() const	{ assert(type == INT); return arg.int_; }
+
+	/**
+	 * Returns the value for a string argument. The argument's type must
+	 * match accordingly.
+	 */
 	const std::string& AsString() const	{ assert(type == STRING); return arg_string; }
+
+	/**
+	 * Returns the value for a Bro value argument. The argument's type must
+	 * match accordingly.
+	 */
 	const Val* AsVal() const	{ assert(type == VAL); return arg.val; }
+
+	/**
+	 * Returns the value for a list of Bro values argument. The argument's type must
+	 * match accordingly.
+	 */
 	const val_list* AsValList() const	{ assert(type == VAL_LIST); return arg.vals; }
+
+	/**
+	 * Returns the value for a vod pointer argument. The argument's type
+	 * must match accordingly.
+	 */
 	const void* AsVoidPtr() const	{ assert(type == VOIDP); return arg.voidp; }
 
+	/**
+	 * Returns the argument's type.
+	 */
 	Type GetType() const	{ return type; }
+
+	/**
+	 * Returns a textual representation of the argument.
+	 *
+	 * @param d Description object to use for rendering.
+	 */
 	void Describe(ODesc* d) const;
 
 private:
@@ -185,24 +285,25 @@ typedef std::list<HookArgument> HookArgumentList;
  * Plugins encapsulate functionality that extends one or more of Bro's major
  * subsystems, such as analysis of a specific protocol, or logging output in
  * a particular format. A plugin acts a logical container that can provide a
- * set of different functionality. Specifically, it may:
+ * set of functionality. Specifically, it may:
  *
  * - Provide one or more \a components implementing functionality. For
  *   example, a RPC plugin could provide analyzer for set of related
  *   protocols (RPC, NFS, etc.), each of which would be a separate component.
- *   Likewise, a SQLite plugin could provide both a writer and reader
- *   component. In addition to components, a plugin can also provide of
- *   script-level elements defined in *.bif files.
+ *   Likewise, an SQLite plugin could provide both a writer and reader
+ *   component.
  *
- * - Provide BiF elements (functions, events, types, globals).
+ * - Provide BiF elements (functions, events, types, globals). Typically
+ *   they'll be defined in *.bif files, but a plugin can also create them
+ *   internally.
  *
  * - Provide hooks (aka callbacks) into Bro's core processing to inject
  *   and/or alter functionality.
  *
- * Note that a plugin needs to explicitly register all the functionality it
- * provides. For components, it needs to call AddComponent(); for BiFs
- * AddBifItem(); and for hooks EnableHook() and then also implemennt the
- * corresponding virtual methods).
+ * A plugin needs to explicitly register all the functionality it provides.
+ * For components, it needs to call AddComponent(); for BiFs AddBifItem();
+ * and for hooks EnableHook() and then also implemennt the corresponding
+ * virtual methods.
  *
  */
 class Plugin {
@@ -232,14 +333,14 @@ public:
 	const std::string& Description() const;
 
 	/**
-	 * Returns the version of the plugin. Version are only meaningful for
-	 * dynamically compiled plugins; for statically compiled ones, this
-	 * will always return 0.
+	 * Returns the version of the plugin. Versions are only meaningful
+	 * for dynamically compiled plugins; for statically compiled ones,
+	 * this will always return 0.
 	 */
 	VersionNumber Version() const;
 
 	/**
-	 * Returns true if this is a dynamically linked in plugin.
+	 * Returns true if this is a dynamically linked plugin.
 	 */
 	bool DynamicPlugin() const;
 
@@ -251,16 +352,17 @@ public:
 
 	/**
 	 * For dynamic plugins, returns the full path to the shared library
-	 * from which it was loaded. For static plugins, returns null.
+	 * from which it was loaded. For static plugins, returns an empty
+	 * string.
 	 **/
 	const std::string& PluginPath() const;
 
 	/**
-	 * Returns the internal API version that this plugin relies on. Only
-	 * plugins that match Bro's current API version may be used. For
-	 * statically compiled plugins this is automatically the case, but
-	 * dynamically loaded plugins may cause a mismatch if they were
-	 * compiled for a different Bro version.
+	 * Returns the internal version of the Bro API that this plugin
+	 * relies on. Only plugins that match Bro's current API version can
+	 * be used. For statically compiled plugins this is automatically the
+	 * case, but dynamically loaded plugins may cause a mismatch if they
+	 * were compiled for a different Bro version.
 	 */
 	int APIVersion() const;
 
@@ -284,7 +386,7 @@ public:
 	 *
 	 * @return A configuration describing the plugin.
 	 */
-	virtual Configuration Configure() { return Configuration(); } // TODO: Change to abstract method.
+	virtual Configuration Configure() = 0;
 
 	/**
 	 * First-stage initialization of the plugin called early during Bro's
@@ -319,13 +421,18 @@ public:
 	void Describe(ODesc* d) const;
 
 	/**
-	 * Registers an individual BiF that the plugin defines.  The
+	 * Registers an individual BiF that the plugin defines. The
 	 * information is for informational purpuses only and will show up in
 	 * the result of BifItems() as well as in the Describe() output.
 	 * Another way to add this information is via overriding
 	 * CustomBifItems().
 	 *
-	 * \todo Do we need both this an CustomBifItems()?
+	 * Note that this method is rarely the right one to use. As it's for
+	 * informational purposes only, the plugin still needs to register
+	 * the BiF items themselves with the corresponding Bro parts. Doing
+	 * so can be tricky, and it's recommned to instead define BiF items
+	 * in separate *.bif files that the plugin then pulls in. If defined
+	 * there, one does *not* need to call this method.
 	 *
 	 * @param name The name of the BiF item.
 	 *
@@ -343,7 +450,8 @@ public:
 	 *
 	 * This method must not be called after InitPostScript().
 	 *
-	 * @param file The file to load. It will be searched along the standard paths.
+	 * @param file The file to load. It will be searched along the
+	 * standard paths.
 	 *
 	 * @return True if successful (which however may only mean
 	 * "successfully queued").
@@ -353,12 +461,6 @@ public:
 protected:
 	friend class Manager;
 
-	/**
-	 * Intializes the plugin's configutation. Called by the manager
-	 * before anything else.
-	 */
-	void DoConfigure();
-
 	/**
 	 * Registers and activates a component.
 	 *
@@ -372,12 +474,11 @@ protected:
 	 * have performance impaxct as many trigger frequently inside Bro's
 	 * main processing path.
 	 *
-	 * Note that hooks may be enabled/disabled dynamically at any time,
-	 * the output of Bro's \c -NN option will only reflect that state at
-	 * startup time; hence usually one should call this for a plugin's
-	 * hooks in either the plugin's ctor or in InitPreScript(). For
-	 * consistency with other parts of the API, there's a macro
-	 * PLUGIN_ENABLE_HOOK for use inside the ctor.
+	 * Note that while hooks may be enabled/disabled dynamically at any
+	 * time, the output of Bro's \c -NN option will only reflect their
+	 * state at startup time. Usually one should call this method for a
+	 * plugin's hooks in either the plugin's constructor or in
+	 * InitPreScript().
 	 *
 	 * @param hook The hook to enable.
 	 *
@@ -403,34 +504,27 @@ protected:
 	hook_list EnabledHooks() const;
 
 	/**
-	 * Register interest in an event. The event will then be raised, and
-	 * hence passed to the plugin, even if there no handler defined.
-	 *
-	 * @param handler The object being interested in.
+	 * Registers interest in an event, even if there's no handler for it.
+	 * Normally a plugin receives events through HookQueueEvent() only if Bro
+	 * actually has code to execute for it. By calling this method, the
+	 * plugin tells Bro to raise the event even if there's no correspondong
+	 * handler; it will then go into HookQueueEvent() just as any other.
+     *
+	 * @param handler The event handler being interested in.
 	 */
 	void RequestEvent(EventHandlerPtr handler);
 
 	/**
-	 * Register interest in the destruction of a BroObj instance. When
+	 * Registers interest in the destruction of a BroObj instance. When
 	 * Bro's reference counting triggers the objects destructor to run,
-	 * the \a HookBroObjDtor will be called.
+	 * \a HookBroObjDtor will be called.
+	 *
+	 * Note that his can get expensive if triggered for many objects.
 	 *
 	 * @param handler The object being interested in.
 	 */
 	void RequestBroObjDtor(BroObj* obj);
 
-	/**
-	 * Virtual method that can be overriden by derived class to provide
-	 * information about further script-level elements that the plugin
-	 * provides on its own, i.e., outside of the standard mechanism
-	 * processing *.bif files automatically. The returned information is
-	 * for informational purposes only and will show up in the result of
-	 * BifItems() as well as in the Describe() output.
-	 *
-	 * \todo Do we need both this an AddBifItem()?
-	 */
-	virtual bif_item_list CustomBifItems() const;
-
 	// Hook functions.
 
 	/**
@@ -439,18 +533,18 @@ protected:
 	 * timing guaranteed. It will be called once for each input file Bro
 	 * is about to load, either given on the command line or via @load
 	 * script directives. The hook can take over the file, in which case
-	 * Bro not further process it otherwise.
-     *
-     * @param file The filename to be loaded.
-     *
-     * @param ext The extension of the filename. This is provided separately
-     * just for convenience. The dot is excluded.
+	 * Bro will not further process it otherwise.
+	 *
+	 * @param file The filename to be loaded, including extension.
+	 *
+	 * @param ext The extension of the filename. This is provided
+	 * separately just for convenience. The dot is excluded.
 	 *
 	 * @return 1 if the plugin took over the file and loaded it
 	 * successfully; 0 if the plugin took over the file but had trouble
-	 * loading it (Bro will abort in this case, the plugin should have
-	 * printed an error message); and -1 if the plugin wasn't interested
-	 * in the file at all.
+	 * loading it (Bro will abort in this case, and the plugin should
+	 * have printed an error message); and -1 if the plugin wasn't
+	 * interested in the file at all.
 	 */
 	virtual int HookLoadFile(const std::string& file, const std::string& ext);
 
@@ -471,11 +565,11 @@ protected:
 	 * in place long as it ensures matching types and correct reference
 	 * counting.
 	 *
-	 * @return If the plugin handled the call, a +1 Val with the result
-	 * value to pass back to the interpreter (for void functions and
-	 * events any \a Val is fine; it will be ignored; best to use a \c
-	 * TYPE_ANY). If the plugin did not handle the call, it must return
-	 * null.
+	 * @return If the plugin handled the call, a Val with +1 reference
+	 * count containomg the result value to pass back to the interpreter
+	 * (for void functions and events any \a Val is fine; it will be
+	 * ignored; best to use a \c TYPE_ANY). If the plugin did not handle
+	 * the call, it must return null.
 	 */
 	virtual Val* HookCallFunction(const Func* func, val_list* args);
 
@@ -485,7 +579,7 @@ protected:
 	 * with this hook enabled a chance to handle the queuing otherwise
 	 * (in the order of their priorities). A plugin can either just
 	 * inspect the event, or take it over (i.e., prevent the interpreter
-	 * from queuing it it).
+	 * from queuing it itself).
 	 *
 	 * The default implementation does never handle the queuing in any
 	 * way.
@@ -501,7 +595,7 @@ protected:
 	virtual bool HookQueueEvent(Event* event);
 
 	/**
-	 * Hook intp event queue draining. This method will be called
+	 * Hook into event queue draining. This method will be called
 	 * whenever the event manager is draining its queue.
 	 */
 	virtual void HookDrainEvents();
@@ -529,7 +623,9 @@ protected:
 	// Meta hooks.
 
 	/**
-	 * A meta hook called just before another hook gets to execute.
+	 * A meta hook called just before another hook gets to execute. This
+	 * will be called independent of whether there's an implementation
+	 * for the hook.
 	 *
 	 * hook: The name of the hook about the execute. This will be the
 	 * same as the corresponding method name (e.g., \c HookQueueEvent).
@@ -541,7 +637,7 @@ protected:
 	virtual void MetaHookPre(HookType hook, const HookArgumentList& args);
 
 	/**
-	 * A meta hook called just after another hook gets to execute. This
+	 * A meta hook called just after another hook got to execute. This
 	 * will be called independent of whether there's an implementation
 	 * for the hook.
 	 *
@@ -555,14 +651,18 @@ protected:
 	 */
 	virtual void MetaHookPost(HookType hook, const HookArgumentList& args, HookArgument result);
 
-	// Methods that are used internally primarily.
+private:
+	/**
+	 * Intializes the plugin's internal configuration. Called by the
+	 * manager before anything else.
+	 */
+	void DoConfigure();
 
 	/**
 	 * Sets the base directory and shared library path from which the
 	 * plugin was loaded.
 	 *
-	 * This is used primarily internally; plugins will have there
-	 * location set automatically.
+	 * This is called by the manager.
 	 *
 	 * @param dir The plugin directory. The functions makes an internal
 	 * copy of string.
@@ -575,22 +675,20 @@ protected:
 	/**
 	 * Marks the plugin as dynamically loaded.
 	 *
-	 * This is used primarily internally; plugins will have this called
-	 * by the manager.
+	 * This is called by the manager.
 	 *
 	 * @param is_dynamic True if it's a dynamically loaded module.
 	 */
 	void SetDynamic(bool is_dynamic);
 
-private:
 	Configuration config;
 
 	std::string base_dir;	// The plugin's base directory.
 	std::string sopath;	// For dynamic plugins, the full path to the shared library.
 	bool dynamic;	// True if a dynamic plugin.
 
-	component_list components;
-	bif_item_list bif_items;
+	component_list components;	// Components the plugin provides.
+	bif_item_list bif_items;	// BiF items the plugin provides.
 };
 
 }