Add LLEventAPI class, formalizing the mechanism by which we wrap a C++ API

with an event API. In addition to the LLEventPump name on which to listen,
LLEventAPI accepts a documentation string for event API introspection.
Give every LLEventDispatcher::add() overload a new documentation string
parameter for event API introspection.
Convert every existing event API to new conventions, introducing suitable
documentation strings for the API and each of its operations.

5 files changed, 119 insertions, 13 deletions

diff --git a/indra/llcommon/CMakeLists.txt b/indra/llcommon/CMakeLists.txt
index 2d0363d188..e41c75846b 100644
--- a/indra/llcommon/CMakeLists.txt
+++ b/indra/llcommon/CMakeLists.txt
@@ -41,6 +41,7 @@ set(llcommon_SOURCE_FILES
     llerror.cpp
     llerrorthread.cpp
     llevent.cpp
+    lleventapi.cpp
     lleventcoro.cpp
     lleventdispatcher.cpp
     lleventfilter.cpp
@@ -140,6 +141,7 @@ set(llcommon_HEADER_FILES
     llerrorlegacy.h
     llerrorthread.h
     llevent.h
+    lleventapi.h
     lleventcoro.h
     lleventdispatcher.h
     lleventfilter.h
diff --git a/indra/llcommon/lleventapi.cpp b/indra/llcommon/lleventapi.cpp
new file mode 100644
index 0000000000..1dd104da8f
--- /dev/null
+++ b/indra/llcommon/lleventapi.cpp
@@ -0,0 +1,30 @@
+/**
+ * @file   lleventapi.cpp
+ * @author Nat Goodspeed
+ * @date   2009-11-10
+ * @brief  Implementation for lleventapi.
+ * 
+ * $LicenseInfo:firstyear=2009&license=viewergpl$
+ * Copyright (c) 2009, Linden Research, Inc.
+ * $/LicenseInfo$
+ */
+
+// Precompiled header
+#include "linden_common.h"
+// associated header
+#include "lleventapi.h"
+// STL headers
+// std headers
+// external library headers
+// other Linden headers
+
+LLEventAPI::LLEventAPI(const std::string& name, const std::string& desc, const std::string& field):
+    lbase(name, field),
+    ibase(name),
+    mDesc(desc)
+{
+}
+
+LLEventAPI::~LLEventAPI()
+{
+}
diff --git a/indra/llcommon/lleventapi.h b/indra/llcommon/lleventapi.h
new file mode 100644
index 0000000000..fef12988cb
--- /dev/null
+++ b/indra/llcommon/lleventapi.h
@@ -0,0 +1,53 @@
+/**
+ * @file   lleventapi.h
+ * @author Nat Goodspeed
+ * @date   2009-10-28
+ * @brief  LLEventAPI is the base class for every class that wraps a C++ API
+ *         in an event API
+ * (see https://wiki.lindenlab.com/wiki/Incremental_Viewer_Automation/Event_API).
+ * 
+ * $LicenseInfo:firstyear=2009&license=viewergpl$
+ * Copyright (c) 2009, Linden Research, Inc.
+ * $/LicenseInfo$
+ */
+
+#if ! defined(LL_LLEVENTAPI_H)
+#define LL_LLEVENTAPI_H
+
+#include "lleventdispatcher.h"
+#include "llinstancetracker.h"
+#include <string>
+
+/**
+ * LLEventAPI not only provides operation dispatch functionality, inherited
+ * from LLDispatchListener -- it also gives us event API introspection.
+ * Deriving from LLInstanceTracker lets us enumerate instances.
+ */
+class LLEventAPI: public LLDispatchListener,
+                  public LLInstanceTracker<LLEventAPI, std::string>
+{
+    typedef LLDispatchListener lbase;
+    typedef LLInstanceTracker<LLEventAPI, std::string> ibase;
+
+public:
+    /**
+     * @param name LLEventPump name on which this LLEventAPI will listen. This
+     * also serves as the LLInstanceTracker instance key.
+     * @param desc Documentation string shown to a client trying to discover
+     * available event APIs.
+     * @param field LLSD::Map key used by LLDispatchListener to look up the
+     * subclass method to invoke [default "op"].
+     */
+    LLEventAPI(const std::string& name, const std::string& desc, const std::string& field="op");
+    virtual ~LLEventAPI();
+
+    /// Get the string name of this LLEventAPI
+    std::string getName() const { return ibase::getKey(); }
+    /// Get the documentation string
+    std::string getDesc() const { return mDesc; }
+
+private:
+    std::string mDesc;
+};
+
+#endif /* ! defined(LL_LLEVENTAPI_H) */
diff --git a/indra/llcommon/lleventdispatcher.cpp b/indra/llcommon/lleventdispatcher.cpp
index 6b1413d054..017bf3a521 100644
--- a/indra/llcommon/lleventdispatcher.cpp
+++ b/indra/llcommon/lleventdispatcher.cpp
@@ -36,9 +36,11 @@ LLEventDispatcher::~LLEventDispatcher()
 }
 
 /// Register a callable by name
-void LLEventDispatcher::add(const std::string& name, const Callable& callable, const LLSD& required)
+void LLEventDispatcher::add(const std::string& name, const std::string& desc,
+                            const Callable& callable, const LLSD& required)
 {
-    mDispatch[name] = DispatchMap::mapped_type(callable, required);
+    mDispatch.insert(DispatchMap::value_type(name,
+                                             DispatchMap::mapped_type(callable, desc, required)));
 }
 
 void LLEventDispatcher::addFail(const std::string& name, const std::string& classname) const
@@ -98,14 +100,14 @@ bool LLEventDispatcher::attemptCall(const std::string& name, const LLSD& event)
     }
     // Found the name, so it's plausible to even attempt the call. But first,
     // validate the syntax of the event itself.
-    std::string mismatch(llsd_matches(found->second.second, event));
+    std::string mismatch(llsd_matches(found->second.mRequired, event));
     if (! mismatch.empty())
     {
         LL_ERRS("LLEventDispatcher") << "LLEventDispatcher(" << mDesc << ") calling '" << name
                                      << "': bad request: " << mismatch << LL_ENDL;
     }
     // Event syntax looks good, go for it!
-    (found->second.first)(event);
+    (found->second.mFunc)(event);
     return true;                    // tell caller we were able to call
 }
 
@@ -116,7 +118,7 @@ LLEventDispatcher::Callable LLEventDispatcher::get(const std::string& name) cons
     {
         return Callable();
     }
-    return found->second.first;
+    return found->second.mFunc;
 }
 
 LLDispatchListener::LLDispatchListener(const std::string& pumpname, const std::string& key):
diff --git a/indra/llcommon/lleventdispatcher.h b/indra/llcommon/lleventdispatcher.h
index 5a86b90bff..eba7b607f1 100644
--- a/indra/llcommon/lleventdispatcher.h
+++ b/indra/llcommon/lleventdispatcher.h
@@ -44,7 +44,10 @@ public:
      * is used to validate the structure of each incoming event (see
      * llsd_matches()).
      */
-    void add(const std::string& name, const Callable& callable, const LLSD& required=LLSD());
+    void add(const std::string& name,
+             const std::string& desc,
+             const Callable& callable,
+             const LLSD& required=LLSD());
 
     /**
      * Special case: a subclass of this class can pass an unbound member
@@ -52,18 +55,22 @@ public:
      * <tt>boost::bind()</tt> expression.
      */
     template <class CLASS>
-    void add(const std::string& name, void (CLASS::*method)(const LLSD&),
+    void add(const std::string& name,
+             const std::string& desc,
+             void (CLASS::*method)(const LLSD&),
              const LLSD& required=LLSD())
     {
-        addMethod<CLASS>(name, method, required);
+        addMethod<CLASS>(name, desc, method, required);
     }
 
     /// Overload for both const and non-const methods
     template <class CLASS>
-    void add(const std::string& name, void (CLASS::*method)(const LLSD&) const,
+    void add(const std::string& name,
+             const std::string& desc,
+             void (CLASS::*method)(const LLSD&) const,
              const LLSD& required=LLSD())
     {
-        addMethod<CLASS>(name, method, required);
+        addMethod<CLASS>(name, desc, method, required);
     }
 
     /// Unregister a callable
@@ -86,7 +93,8 @@ public:
 
 private:
     template <class CLASS, typename METHOD>
-    void addMethod(const std::string& name, const METHOD& method, const LLSD& required)
+    void addMethod(const std::string& name, const std::string& desc,
+                   const METHOD& method, const LLSD& required)
     {
         CLASS* downcast = dynamic_cast<CLASS*>(this);
         if (! downcast)
@@ -95,7 +103,7 @@ private:
         }
         else
         {
-            add(name, boost::bind(method, downcast, _1), required);
+            add(name, desc, boost::bind(method, downcast, _1), required);
         }
     }
     void addFail(const std::string& name, const std::string& classname) const;
@@ -103,7 +111,18 @@ private:
     bool attemptCall(const std::string& name, const LLSD& event) const;
 
     std::string mDesc, mKey;
-    typedef std::map<std::string, std::pair<Callable, LLSD> > DispatchMap;
+    struct DispatchEntry
+    {
+        DispatchEntry(const Callable& func, const std::string& desc, const LLSD& required):
+            mFunc(func),
+            mDesc(desc),
+            mRequired(required)
+        {}
+        Callable mFunc;
+        std::string mDesc;
+        LLSD mRequired;
+    };
+    typedef std::map<std::string, DispatchEntry> DispatchMap;
     DispatchMap mDispatch;
 };