diff options
Diffstat (limited to 'indra/llplugin')
| -rw-r--r-- | indra/llplugin/llplugininstance.cpp | 33 | ||||
| -rw-r--r-- | indra/llplugin/llplugininstance.h | 24 | ||||
| -rw-r--r-- | indra/llplugin/llpluginmessage.cpp | 166 | ||||
| -rw-r--r-- | indra/llplugin/llpluginmessage.h | 16 |
4 files changed, 230 insertions, 9 deletions
diff --git a/indra/llplugin/llplugininstance.cpp b/indra/llplugin/llplugininstance.cpp index 16ba492669..44e3b4950f 100644 --- a/indra/llplugin/llplugininstance.cpp +++ b/indra/llplugin/llplugininstance.cpp @@ -37,13 +37,21 @@ #include "llapr.h" -//virtual +/** Virtual destructor. */ LLPluginInstanceMessageListener::~LLPluginInstanceMessageListener() { } +/** + * TODO:DOC describe how it's used + */ const char *LLPluginInstance::PLUGIN_INIT_FUNCTION_NAME = "LLPluginInitEntryPoint"; +/** + * Constructor. + * + * @param[in] owner Plugin instance. TODO:DOC is this a good description of what "owner" is? + */ LLPluginInstance::LLPluginInstance(LLPluginInstanceMessageListener *owner) : mDSOHandle(NULL), mPluginUserData(NULL), @@ -52,6 +60,9 @@ LLPluginInstance::LLPluginInstance(LLPluginInstanceMessageListener *owner) : mOwner = owner; } +/** + * Destructor. + */ LLPluginInstance::~LLPluginInstance() { if(mDSOHandle != NULL) @@ -61,6 +72,12 @@ LLPluginInstance::~LLPluginInstance() } } +/** + * Dynamically loads the plugin and runs the plugin's init function. + * + * @param[in] plugin_file Name of plugin dll/dylib/so. TODO:DOC is this correct? see .h + * @return 0 if successful, APR error code or error code from the plugin's init function on failure. + */ int LLPluginInstance::load(std::string &plugin_file) { pluginInitFunction init_function = NULL; @@ -102,6 +119,11 @@ int LLPluginInstance::load(std::string &plugin_file) return (int)result; } +/** + * Sends a message to the plugin. + * + * @param[in] message Message + */ void LLPluginInstance::sendMessage(const std::string &message) { if(mPluginSendMessageFunction) @@ -115,6 +137,10 @@ void LLPluginInstance::sendMessage(const std::string &message) } } +/** + * Idle. TODO:DOC what's the purpose of this? + * + */ void LLPluginInstance::idle(void) { } @@ -128,6 +154,11 @@ void LLPluginInstance::staticReceiveMessage(const char *message_string, void **u self->receiveMessage(message_string); } +/** + * Plugin receives message from plugin loader shell. + * + * @param[in] message_string Message + */ void LLPluginInstance::receiveMessage(const char *message_string) { if(mOwner) diff --git a/indra/llplugin/llplugininstance.h b/indra/llplugin/llplugininstance.h index 02936f65fb..c11d5ab5d4 100644 --- a/indra/llplugin/llplugininstance.h +++ b/indra/llplugin/llplugininstance.h @@ -1,6 +1,5 @@ /** * @file llplugininstance.h - * @brief LLPluginInstance handles loading the dynamic library of a plugin and setting up its entry points for message passing. * * @cond * $LicenseInfo:firstyear=2008&license=viewergpl$ @@ -39,13 +38,20 @@ #include "apr_dso.h" +/** + * @brief LLPluginInstanceMessageListener receives messages sent from the plugin loader shell to the plugin. + */ class LLPluginInstanceMessageListener { public: virtual ~LLPluginInstanceMessageListener(); + /** Plugin receives message from plugin loader shell. */ virtual void receivePluginMessage(const std::string &message) = 0; }; +/** + * @brief LLPluginInstance handles loading the dynamic library of a plugin and setting up its entry points for message passing. + */ class LLPluginInstance { LOG_CLASS(LLPluginInstance); @@ -60,19 +66,27 @@ public: // Sends a message to the plugin. void sendMessage(const std::string &message); + // TODO:DOC is this comment obsolete? can't find "send_count" anywhere in indra tree. // send_count is the maximum number of message to process from the send queue. If negative, it will drain the queue completely. // The receive queue is always drained completely. // Returns the total number of messages processed from both queues. void idle(void); - // this is the signature of the "send a message" function. - // message_string is a null-terminated C string - // user_data is the opaque reference that the callee supplied during setup. + /** The signature of the function for sending a message from plugin to plugin loader shell. + * + * @param[in] message_string Null-terminated C string + * @param[in] user_data The opaque reference that the callee supplied during setup. + */ typedef void (*sendMessageFunction) (const char *message_string, void **user_data); - // signature of the plugin init function + /** The signature of the plugin init function. TODO:DOC check direction (pluging loader shell to plugin?) + * + * @param[in] host_user_data Data from plugin loader shell. + * @param[in] plugin_send_function Function for sending from the plugin loader shell to plugin. + */ typedef int (*pluginInitFunction) (sendMessageFunction host_send_func, void *host_user_data, sendMessageFunction *plugin_send_func, void **plugin_user_data); + /** Name of plugin init function */ static const char *PLUGIN_INIT_FUNCTION_NAME; private: diff --git a/indra/llplugin/llpluginmessage.cpp b/indra/llplugin/llpluginmessage.cpp index 34e02c356e..f76d848a70 100644 --- a/indra/llplugin/llpluginmessage.cpp +++ b/indra/llplugin/llpluginmessage.cpp @@ -37,31 +37,57 @@ #include "llsdserialize.h" #include "u64.h" +/** + * Constructor. + */ LLPluginMessage::LLPluginMessage() { } +/** + * Constructor. + * + * @param[in] p Existing message + */ LLPluginMessage::LLPluginMessage(const LLPluginMessage &p) { mMessage = p.mMessage; } +/** + * Constructor. + * + * @param[in] message_class Message class + * @param[in] message_name Message name + */ LLPluginMessage::LLPluginMessage(const std::string &message_class, const std::string &message_name) { setMessage(message_class, message_name); } +/** + * Destructor. + */ LLPluginMessage::~LLPluginMessage() { } +/** + * Reset all internal state. + */ void LLPluginMessage::clear() { mMessage = LLSD::emptyMap(); mMessage["params"] = LLSD::emptyMap(); } +/** + * Sets the message class and name. Also has the side-effect of clearing any key-value pairs in the message. + * + * @param[in] message_class Message class + * @param[in] message_name Message name + */ void LLPluginMessage::setMessage(const std::string &message_class, const std::string &message_name) { clear(); @@ -69,21 +95,45 @@ void LLPluginMessage::setMessage(const std::string &message_class, const std::st mMessage["name"] = message_name; } +/** + * Sets a key/value pair in the message, where the value is a string. + * + * @param[in] key Key + * @param[in] value String value + */ void LLPluginMessage::setValue(const std::string &key, const std::string &value) { mMessage["params"][key] = value; } +/** + * Sets a key/value pair in the message, where the value is LLSD. + * + * @param[in] key Key + * @param[in] value LLSD value + */ void LLPluginMessage::setValueLLSD(const std::string &key, const LLSD &value) { mMessage["params"][key] = value; } +/** + * Sets a key/value pair in the message, where the value is signed 32-bit. + * + * @param[in] key Key + * @param[in] value 32-bit signed value + */ void LLPluginMessage::setValueS32(const std::string &key, S32 value) { mMessage["params"][key] = value; } +/** + * Sets a key/value pair in the message, where the value is unsigned 32-bit. The value is stored as a string beginning with "0x". + * + * @param[in] key Key + * @param[in] value 32-bit unsigned value + */ void LLPluginMessage::setValueU32(const std::string &key, U32 value) { std::stringstream temp; @@ -91,16 +141,34 @@ void LLPluginMessage::setValueU32(const std::string &key, U32 value) setValue(key, temp.str()); } +/** + * Sets a key/value pair in the message, where the value is a bool. + * + * @param[in] key Key + * @param[in] value Boolean value + */ void LLPluginMessage::setValueBoolean(const std::string &key, bool value) { mMessage["params"][key] = value; } +/** + * Sets a key/value pair in the message, where the value is a double. + * + * @param[in] key Key + * @param[in] value Boolean value + */ void LLPluginMessage::setValueReal(const std::string &key, F64 value) { mMessage["params"][key] = value; } +/** + * Sets a key/value pair in the message, where the value is a pointer. The pointer is stored as a string. + * + * @param[in] key Key + * @param[in] value Pointer value + */ void LLPluginMessage::setValuePointer(const std::string &key, void* value) { std::stringstream temp; @@ -109,16 +177,33 @@ void LLPluginMessage::setValuePointer(const std::string &key, void* value) setValue(key, temp.str()); } +/** + * Gets the message class. + * + * @return Message class + */ std::string LLPluginMessage::getClass(void) const { return mMessage["class"]; } +/** + * Gets the message name. + * + * @return Message name + */ std::string LLPluginMessage::getName(void) const { return mMessage["name"]; } +/** + * Returns true if the specified key exists in this message (useful for optional parameters). + * + * @param[in] key Key + * + * @return True if key exists, false otherwise. + */ bool LLPluginMessage::hasValue(const std::string &key) const { bool result = false; @@ -131,6 +216,13 @@ bool LLPluginMessage::hasValue(const std::string &key) const return result; } +/** + * Gets the value of a key as a string. If the key does not exist, an empty string will be returned. + * + * @param[in] key Key + * + * @return String value of key if key exists, empty string if key does not exist. + */ std::string LLPluginMessage::getValue(const std::string &key) const { std::string result; @@ -143,6 +235,13 @@ std::string LLPluginMessage::getValue(const std::string &key) const return result; } +/** + * Gets the value of a key as LLSD. If the key does not exist, a null LLSD will be returned. + * + * @param[in] key Key + * + * @return LLSD value of key if key exists, null LLSD if key does not exist. + */ LLSD LLPluginMessage::getValueLLSD(const std::string &key) const { LLSD result; @@ -155,6 +254,13 @@ LLSD LLPluginMessage::getValueLLSD(const std::string &key) const return result; } +/** + * Gets the value of a key as signed 32-bit int. If the key does not exist, 0 will be returned. + * + * @param[in] key Key + * + * @return Signed 32-bit int value of key if key exists, 0 if key does not exist. + */ S32 LLPluginMessage::getValueS32(const std::string &key) const { S32 result = 0; @@ -167,6 +273,13 @@ S32 LLPluginMessage::getValueS32(const std::string &key) const return result; } +/** + * Gets the value of a key as unsigned 32-bit int. If the key does not exist, 0 will be returned. + * + * @param[in] key Key + * + * @return Unsigned 32-bit int value of key if key exists, 0 if key does not exist. + */ U32 LLPluginMessage::getValueU32(const std::string &key) const { U32 result = 0; @@ -181,6 +294,13 @@ U32 LLPluginMessage::getValueU32(const std::string &key) const return result; } +/** + * Gets the value of a key as a bool. If the key does not exist, false will be returned. + * + * @param[in] key Key + * + * @return Boolean value of key if it exists, false otherwise. + */ bool LLPluginMessage::getValueBoolean(const std::string &key) const { bool result = false; @@ -193,6 +313,13 @@ bool LLPluginMessage::getValueBoolean(const std::string &key) const return result; } +/** + * Gets the value of a key as a double. If the key does not exist, 0 will be returned. + * + * @param[in] key Key + * + * @return Value as a double if key exists, 0 otherwise. + */ F64 LLPluginMessage::getValueReal(const std::string &key) const { F64 result = 0.0f; @@ -205,6 +332,13 @@ F64 LLPluginMessage::getValueReal(const std::string &key) const return result; } +/** + * Gets the value of a key as a pointer. If the key does not exist, NULL will be returned. + * + * @param[in] key Key + * + * @return Pointer value if key exists, NULL otherwise. + */ void* LLPluginMessage::getValuePointer(const std::string &key) const { void* result = NULL; @@ -219,6 +353,11 @@ void* LLPluginMessage::getValuePointer(const std::string &key) const return result; } +/** + * Flatten the message into a string. + * + * @return Message as a string. + */ std::string LLPluginMessage::generate(void) const { std::ostringstream result; @@ -230,7 +369,11 @@ std::string LLPluginMessage::generate(void) const return result.str(); } - +/** + * Parse an incoming message into component parts. Clears all existing state before starting the parse. + * + * @return Returns -1 on failure, otherwise returns the number of key/value pairs in the incoming message. + */ int LLPluginMessage::parse(const std::string &message) { // clear any previous state @@ -244,27 +387,48 @@ int LLPluginMessage::parse(const std::string &message) } +/** + * Destructor + */ LLPluginMessageListener::~LLPluginMessageListener() { // TODO: should listeners have a way to ensure they're removed from dispatcher lists when deleted? } +/** + * Destructor + */ LLPluginMessageDispatcher::~LLPluginMessageDispatcher() { } +/** + * Add a message listener. TODO:DOC need more info on what uses this. when are multiple listeners needed? + * + * @param[in] listener Message listener + */ void LLPluginMessageDispatcher::addPluginMessageListener(LLPluginMessageListener *listener) { mListeners.insert(listener); } +/** + * Remove a message listener. + * + * @param[in] listener Message listener + */ void LLPluginMessageDispatcher::removePluginMessageListener(LLPluginMessageListener *listener) { mListeners.erase(listener); } +/** + * Distribute a message to all message listeners. + * + * @param[in] message Message + */ void LLPluginMessageDispatcher::dispatchPluginMessage(const LLPluginMessage &message) { for (listener_set_t::iterator it = mListeners.begin(); diff --git a/indra/llplugin/llpluginmessage.h b/indra/llplugin/llpluginmessage.h index 99f8d1194f..cbd31e0964 100644 --- a/indra/llplugin/llpluginmessage.h +++ b/indra/llplugin/llpluginmessage.h @@ -1,6 +1,5 @@ /** * @file llpluginmessage.h - * @brief LLPluginMessage encapsulates the serialization/deserialization of messages passed to and from plugins. * * @cond * $LicenseInfo:firstyear=2008&license=viewergpl$ @@ -36,7 +35,9 @@ #include "llsd.h" - +/** + * @brief LLPluginMessage encapsulates the serialization/deserialization of messages passed to and from plugins. + */ class LLPluginMessage { LOG_CLASS(LLPluginMessage); @@ -104,14 +105,23 @@ private: }; +/** + * @brief Listener for plugin messages. + */ class LLPluginMessageListener { public: virtual ~LLPluginMessageListener(); + /** Plugin receives message from plugin loader shell. */ virtual void receivePluginMessage(const LLPluginMessage &message) = 0; }; +/** + * @brief Dispatcher for plugin messages. + * + * Manages the set of plugin message listeners and distributes messages to plugin message listeners. + */ class LLPluginMessageDispatcher { public: @@ -122,7 +132,9 @@ public: protected: void dispatchPluginMessage(const LLPluginMessage &message); + /** A set of message listeners. */ typedef std::set<LLPluginMessageListener*> listener_set_t; + /** The set of message listeners. */ listener_set_t mListeners; }; |