diff options
| -rw-r--r-- | indra/llplugin/llpluginmessage.cpp | 160 | ||||
| -rw-r--r-- | indra/llplugin/llpluginmessage.h | 10 | ||||
| -rw-r--r-- | indra/media_plugins/base/media_plugin_base.h | 20 |
3 files changed, 180 insertions, 10 deletions
diff --git a/indra/llplugin/llpluginmessage.cpp b/indra/llplugin/llpluginmessage.cpp index 34e02c356e..d06f3cefa0 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 @@ -255,16 +398,31 @@ 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..e00022a245 100644 --- a/indra/llplugin/llpluginmessage.h +++ b/indra/llplugin/llpluginmessage.h @@ -104,6 +104,9 @@ private: }; +/** + * @brief Listens for plugin messages. + */ class LLPluginMessageListener { public: @@ -112,6 +115,11 @@ public: }; +/** + * @brief Dispatcher for plugin messages. + * + * Manages the set of plugin message listeners and distributes messages to plugin message listeners. + */ class LLPluginMessageDispatcher { public: @@ -122,7 +130,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; }; diff --git a/indra/media_plugins/base/media_plugin_base.h b/indra/media_plugins/base/media_plugin_base.h index 8f8e89f2e3..ed4dc0cfa9 100644 --- a/indra/media_plugins/base/media_plugin_base.h +++ b/indra/media_plugins/base/media_plugin_base.h @@ -114,15 +114,17 @@ protected: }; /** The plugin <b>must</b> define this function to create its instance. - * It should look something like this: \n -{ \n - MediaPluginFoo *self = new MediaPluginFoo(host_send_func, host_user_data); \n - *plugin_send_func = MediaPluginFoo::staticReceiveMessage; \n - *plugin_user_data = (void*)self; \n - \n - return 0; \n -} \n -*/ + * It should look something like this: + * @code + * { + * MediaPluginFoo *self = new MediaPluginFoo(host_send_func, host_user_data); + * *plugin_send_func = MediaPluginFoo::staticReceiveMessage; + * *plugin_user_data = (void*)self; + * + * return 0; + * } + * @endcode + */ int init_media_plugin( LLPluginInstance::sendMessageFunction host_send_func, void *host_user_data, |