App::IMessageManager class
#include <Spore ModAPI/Spore/App/IMessageManager.h>

This manager defines a messaging system, that allows communication between different parts of the code.

When a message is sent from any part of the code, all the objects that are listening to that specific message (which is identified using an ID) are notified. Therefore, all the parts of the code that need to react to certain events can be notified without he sender needing to know them.

To listen to messages, two things can be used. The first one, and the most common, is the IMessageListener interface, which allow classes to listen to messages. Another alternative is using a handler function, which is a static function that receives messages.

Derived classes

class cMessageManager
The implementation of IMessageManager; this should only be used for extending and detouring.

Public types

enum Options { kOptionAllowLock = 0, kOptionRefCount = 4 }
using MessageHandler_t = void(*)(uint32_t messageID, void*pData, void*pObject)
A static message handler. This is the equivalent to the IMessageListener::HandleMessage() function.

Public static functions

static auto Get() -> IMessageManager*
Returns the active message manager.

Constructors, destructors, conversion operators

~IMessageManager() virtual

Public functions

auto Initialize() -> bool pure virtual
auto Dispose() -> bool pure virtual
auto GetOption(Options option) -> bool pure virtual
Returns the boolean value of the specified option, in the IMessageManager::Options enum.
auto SetOption(Options option, bool bValue) -> void pure virtual
Sets the boolean value of the specified option, in the IMessageManager::Options enum.
auto MessageSend(uint32_t messageID, void* pMessage, IUnmanagedMessageListener* pListener = nullptr) -> void pure virtual
Sends a message in this manager, notifying all the interfaces listening for the specified message ID.
auto MessagePost(uint32_t messageID, IMessageRC* pMessage, IMessageListener* pListener = nullptr) -> void pure virtual
auto MessagePostFunction(uint32_t messageID, IMessageRC* pMessage, int, MessageHandler_t handler, void*) -> void pure virtual
auto AddListener(IMessageListener* pListener, uint32_t messageID) -> void pure virtual
Adds a message listener to this manager, that will be notified of messages with the specified ID.
auto AddListener(LambdaMessageListener::HandleMessage_T function, const std::initializer_list<uint32_t> messageIDs) -> void
Adds a message listener to this manager, that will be notified of messages with the specified ID.
auto AddUnmanagedListener(IUnmanagedMessageListener* pListener, uint32_t messageID) -> void pure virtual
Same as IMessageManager::AddListener(), but this does not call AddRef().
auto AddHandler(MessageHandler_t pFunction, void* pObject, uint32_t messageID, bool bRefCounted = false, int nPriority = -1) -> void pure virtual
Adds a static handler function to this manager, that will be notified of messages with the specified ID.
auto RemoveListener(IUnmanagedMessageListener* pListener, uint32_t messageID, int nPriority = -9999) -> bool pure virtual
Makes the listener stop listening to the specified message ID.
auto RemoveHandler(MessageHandler_t pFunction, uint32_t messageID, int nPriority = -9999) -> bool pure virtual
Makes the handler stop listening to the specified message ID.
auto ProcessQueue(int, int, int) -> int pure virtual
auto ProcessQueue2() -> int pure virtual
auto GetMessageQueue() -> int pure virtual
auto Lock(bool bLock) -> int pure virtual
Locks or unlocks the mutexs in this manager, allowing to safely interact with this manager in different threads.

Protected types

struct Entry

Protected functions

auto AddEntry(const Entry& entry, uint32_t messageID) -> void virtual
Adds the entry to listen to the given message ID.
auto RemoveEntry(void* pMessageObject, uint32_t messageID, int nPriority = -9999) -> bool virtual
Removes the entry assigned at the given messageID with the given priority.

Enum documentation

enum App::IMessageManager::Options

Enumerators
kOptionAllowLock

If true, this manager uses mutexs to work with threads. Additionally, the user can use the function IMessageManager::UseMutex(bool).
kOptionRefCount

If true, the listeners added in the manager will be refcounted.

Function documentation

bool App::IMessageManager::GetOption(Options option) pure virtual

Returns the boolean value of the specified option, in the IMessageManager::Options enum.

Parameters
option The option whose value will be returned.

void App::IMessageManager::SetOption(Options option, bool bValue) pure virtual

Sets the boolean value of the specified option, in the IMessageManager::Options enum.

Parameters
option The option whose value will be set.
bValue The new boolean value of the option.

void App::IMessageManager::MessageSend(uint32_t messageID, void* pMessage, IUnmanagedMessageListener* pListener = nullptr) pure virtual

Sends a message in this manager, notifying all the interfaces listening for the specified message ID.

Parameters
messageID The ID this message notifies.
pMessage Data related to the message, not all messages need to use this.
pListener [Optional] The IMessageListener that will receive this message. If this is specified, no other listener will be notified.

void App::IMessageManager::AddListener(IMessageListener* pListener, uint32_t messageID) pure virtual

Adds a message listener to this manager, that will be notified of messages with the specified ID.

Parameters
pListener The message listener to add.
messageID The ID of the messages the listener is listening to.

A single listener can be listening to multiple message IDs. If the kOptionRefCount option is true, the IMessageListener::AddRef() method will be called on the listener.

void App::IMessageManager::AddListener(LambdaMessageListener::HandleMessage_T function, const std::initializer_list<uint32_t> messageIDs)

Adds a message listener to this manager, that will be notified of messages with the specified ID.

Parameters
function The message listener to add.
messageIDs A list of the IDs of the messages the listener will listen to.

A single listener can be listening to multiple message IDs.

void App::IMessageManager::AddUnmanagedListener(IUnmanagedMessageListener* pListener, uint32_t messageID) pure virtual

Same as IMessageManager::AddListener(), but this does not call AddRef().

Parameters
pListener The message listener to add.
messageID The ID of the messages the listener is listening to.

void App::IMessageManager::AddHandler(MessageHandler_t pFunction, void* pObject, uint32_t messageID, bool bRefCounted = false, int nPriority = -1) pure virtual

Adds a static handler function to this manager, that will be notified of messages with the specified ID.

Parameters
pFunction A pointer to the handler function.
pObject An object that will be sent as a parameter in the handler function.
messageID The ID of the messages the handler is listening to.
bRefCounted [Optional] If true and kOptionRefCount is true, a kMsgAddRef message will be sent on the handler.
nPriority [Optional] The priority of this handler.

The same handler can be added multiple times using different priorities.

bool App::IMessageManager::RemoveListener(IUnmanagedMessageListener* pListener, uint32_t messageID, int nPriority = -9999) pure virtual

Makes the listener stop listening to the specified message ID.

Parameters
pListener The listener to remove.
messageID The ID of the messages the listener is listening to, and that will stop listening.
nPriority [Optional] The priority the listener must have to be removed. If it's -9999 (by default), it will be ignored.
Returns Whether the handler was removed or not.

Optionally, a priority can be specified; if so, only if the listener with that priority will be removed.

bool App::IMessageManager::RemoveHandler(MessageHandler_t pFunction, uint32_t messageID, int nPriority = -9999) pure virtual

Makes the handler stop listening to the specified message ID.

Parameters
pFunction The handler function to remove.
messageID The ID of the messages the handler is listening to, and that will stop listening.
nPriority [Optional] The priority the handler must have to be removed. If it's -9999 (by default), it will be ignored.
Returns Whether the handler was removed or not.

Optionally, a priority can be specified; if so, only if the handler with that priority will be removed.

int App::IMessageManager::Lock(bool bLock) pure virtual

Locks or unlocks the mutexs in this manager, allowing to safely interact with this manager in different threads.

Parameters
bLock True -> Lock; False -> Unlock

If kOptionAllowLock is not true, this won't do anything.

void App::IMessageManager::AddEntry(const Entry& entry, uint32_t messageID) virtual protected

Adds the entry to listen to the given message ID.

Parameters
entry The entry that contains the listener or handler function.
messageID The message ID the entry will be notified.

bool App::IMessageManager::RemoveEntry(void* pMessageObject, uint32_t messageID, int nPriority = -9999) virtual protected

Removes the entry assigned at the given messageID with the given priority.

Parameters
pMessageObject The handler or listener to remove.
messageID The message ID the entry will be removed from.
nPriority [Optional] The priority of the entry to be removed.
Returns Whether the entry was removed or not.

If the priority is -9999, it will be ignored. If the entry is refcounted and kOptionRefCount is true, Release() will be called on the listener (or a kMsgRelease will be sent to the handler). This function works for both listeners and handlers.